Brug af API'et

Gennemgåede eksempler for THMI's offentlige API — godkendelse, læsning af værdier, forespørgsler på historik, fejlhåndtering og formater.

Denne side er den praktiske ledsager til listen over endpoints: hvordan du godkender, hvordan en body til en historikforespørgsel ser ud, hvordan tidsstempler og fejl er opbygget, og hvordan du vælger JSON eller CSV. Brug OpenAPI-specifikationen for den fulde, maskinlæsbare kontrakt.

Godkendelse

Send din adgangsnøgle som et bearer-token i hver anmodning. Headeren skal starte med Bearer . Intet andet accepteres, og der er ingen mulighed for at bruge en forespørgselsparameter i stedet:

curl https://<your-cloud-host>/api/v1/projects/list \
  -H "Authorization: Bearer <your-token>"

En anmodning med en manglende eller forkert formateret Authorization-header afvises med 401 Unauthorized, før den når nogen projektdata. En gyldig nøgle, der ikke har fået adgang til det projekt eller den ressource, du beder om, får 403 Forbidden.

Læs en aktuel værdi

Aktuelle værdier hentes med almindelige GET-anmodninger. Hent ét tag efter dets sti:

curl "https://<your-cloud-host>/api/v1/<projectId>/tag/values/by-path?tagPath=Building/Boiler/SupplyTemp" \
  -H "Authorization: Bearer <your-token>"

Alt undtagen historik og CSV-eksport er GET. Se Endpoints for det fulde sæt (projekter, tags, værdier, sider og tidszoner).

Forespørgsler på historik

Historik er den eneste læsning, der bruger POST. Det er ikke, fordi den ændrer noget, men fordi forespørgslen er for stor til en URL. Body’en bærer tidsintervallet, tags og hvordan de skal aggregeres. Vælg endpoint ud fra, hvordan du identificerer tags (by-path eller by-id), og svarformatet ud fra det sidste segment i stien (json eller csv):

curl -X POST "https://<your-cloud-host>/api/v1/<projectId>/history/aggregate/by-path/json" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "timeFrom": 1572548400000,
    "timeTo": 1574239662847,
    "timeZone": "Europe/Stockholm",
    "groupingType": "HOURS",
    "valueType": "ACTUAL",
    "tagList": ["Building/Boiler/SupplyTemp", "Building/Boiler/ReturnTemp"]
  }'

For by-id skal du angive tag-id’er i tagList i stedet for stier. Det forældede …/history/aggregate/{format} (uden by-path/by-id) opfører sig som by-id.

Tidsstempler

Alle tidsstempler, både de timeFrom/timeTo, du sender, og de tidspunkter, du får tilbage, er et heltal i epoch-millisekunder (UTC), ikke en ISO-streng. timeZone påvirker kun, hvordan grupperne tilpasses og navngives, ikke enhederne. Konvertér til og fra din egen tidszone på din side.

Formater

• Svar er som standard JSON. Historik og eksporten af den kan også levere CSV, og sider gengives som SVG.
• Formatet vælges af stien, ikke af en Accept-header: Det afsluttende /json eller /csv på historik-endpoints bestemmer det. Hvis du beder om csv, streames de samme data som en CSV-download.

Fejl

Fejl returneres som en lille JSON-struktur med status sat til fail:

{
  "status": "fail",
  "message": "A human-readable explanation",
  "code": "optional_error_code"
}

HTTP-statussen fortæller dig kategorien: