API:n käyttö

Käytännön esimerkkejä THMI:n julkisesta API:sta, kuten todennus, arvojen lukeminen, historian kyselyt, virheiden käsittely ja muodot.

Tämä sivu on päätepisteluettelon käytännön kumppani: miten todennetaan, miltä historiakyselyn runko näyttää, millaisia aikaleimat ja virheet ovat ja miten valitaan JSON tai CSV. Käytä täydellisenä, koneluettavana sopimuksena OpenAPI-määritystä.

Todennus

Lähetä käyttötunnisteesi bearer-tunnisteena jokaisessa pyynnössä. Otsakkeen on alettava sanalla Bearer . Mitään muuta ei hyväksytä, eikä kyselyparametria voi käyttää vaihtoehtona:

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

Pyyntö, josta Authorization-otsake puuttuu tai jossa se on virheellinen, hylätään vastauksella 401 Unauthorized ennen kuin se pääsee mihinkään projektin dataan. Kelvollinen tunniste, jolle ei ole myönnetty pyydettyä projektia tai resurssia, saa vastauksen 403 Forbidden.

Nykyisen arvon lukeminen

Nykyiset arvot haetaan tavallisilla GET-pyynnöillä. Hae yksi tagi sen polun mukaan:

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

Kaikki muu paitsi historia ja CSV-vienti on GET-pyyntöjä. Koko joukko (projektit, tagit, arvot, sivut, aikavyöhykkeet) löytyy sivulta Päätepisteet.

Historian kyselyt

Historia on ainoa lukutoiminto, joka käyttää POST-metodia. Syy ei ole se, että se muuttaisi jotakin, vaan se, että kysely on liian suuri URL-osoitteeseen. Runko sisältää aikavälin, tagit ja tiedon siitä, miten ne kootaan. Valitse päätepiste sen mukaan, miten tunnistat tagit (by-path tai by-id), ja vastauksen muoto polun viimeisellä osalla (json tai 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"]
  }'

Kun käytät by-id-päätepistettä, laita tagList-kenttään tagien tunnukset polkujen sijaan. Vanhentunut …/history/aggregate/{format} (ilman by-path- tai by-id-osaa) toimii kuten by-id.

Aikaleimat

Jokainen aikaleima, sekä lähettämäsi timeFrom/timeTo että takaisin saamasi pisteiden ajat, on epoch-millisekunteina ilmaistu kokonaisluku (UTC) eikä ISO-merkkijono. timeZone vaikuttaa vain siihen, miten jaksot kohdistetaan ja nimetään, ei yksiköihin. Muunna aikaleimat omaan aikavyöhykkeeseesi ja siitä takaisin omassa päässäsi.

Muodot

• Vastaukset ovat oletuksena JSON-muodossa. Historia ja sen vienti tuottavat myös CSV-muotoa, ja sivut renderöidään SVG-muodossa.
• Muoto valitaan polulla eikä Accept-otsakkeella: historian päätepisteiden loppuosa /json tai /csv valitsee sen. Kun pyydät csv-muotoa, sama data suoratoistetaan CSV-latauksena.

Virheet

Virheet palautetaan pienenä JSON-kuorena, jonka status on fail:

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

HTTP-tilakoodi kertoo virheen luokan: