Använda API:et

Genomarbetade exempel för THMI:s publika API — autentisering, läsa värden, fråga historik, felhantering och format.

Den här sidan är den praktiska följeslagaren till slutpunktslistan: hur du autentiserar, hur en historikfrågas kropp ser ut, hur tidsstämplar och fel är utformade och hur du väljer JSON eller CSV. För det fullständiga, maskinläsbara kontraktet, använd OpenAPI-specifikationen.

Autentisering

Skicka din åtkomstnyckel som en bearer-token på varje begäran. Rubriken måste börja med Bearer — inget annat accepteras, och det finns ingen reserv via frågeparameter:

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

En begäran med en saknad eller felaktig Authorization-rubrik avvisas med 401 Unauthorized innan den når någon projektdata. En giltig nyckel som inte beviljats det projekt eller den resurs du frågar efter får 403 Forbidden.

Läsa ett aktuellt värde

Aktuella värden är vanliga GET-begäranden. Hämta en tagg via dess sökväg:

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

Allt utom historik och CSV-export är en GET — se Slutpunkter för hela uppsättningen (projekt, taggar, värden, sidor, tidszoner).

Fråga historik

Historik är den enda läsningen som använder POST — inte för att den ändrar något, utan för att frågan är för stor för en URL. Kroppen bär tidsintervallet, taggarna och hur de ska aggregeras. Välj slutpunkt efter hur du identifierar taggar (by-path eller by-id) och svarsformatet efter det sista sökvägssegmentet (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"]
  }'

För by-id, lägg tagg-id:n i tagList i stället för sökvägar. Den föråldrade …/history/aggregate/{format} (utan by-path/by-id) beter sig som by-id.

Tidsstämplar

Varje tidsstämpel — de timeFrom/timeTo du skickar och punkttiderna du får tillbaka — är ett heltal i epok-millisekunder (UTC), inte en ISO-sträng. timeZone påverkar bara hur hinkar riktas och märks, inte enheterna. Konvertera till och från din egen zon på din sida.

Format

• Svar är JSON som standard. Historik och dess export producerar även CSV, och sidor renderas som SVG.
• Formatet väljs av sökvägen, inte en Accept-rubrik — det avslutande /json eller /csv på historikslutpunkterna väljer det. Att begära csv strömmar samma data som en CSV-nedladdning.

Fel

Fel kommer tillbaka som ett litet JSON-hölje med en status som är fail:

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

HTTP-statusen anger kategorin: