Az IoT Central REST API használata eszközök lekérdezésére

Az IoT Central REST API lehetővé teszi az IoT Central-alkalmazásokkal integrálható ügyfélalkalmazások fejlesztését. A REST API-val lekérdezheti az eszközöket az IoT Central-alkalmazásban. Az alábbiakban példákat talál a REST API lekérdezés használatára:

• Az eszköz által jelentett utolsó 10 telemetriai érték lekérése.
• Keresse meg az összes olyan eszközt, amely hibaállapotban van, és elavult belső vezérlőprogrammal rendelkezik.
• Az eszközök telemetriai trendjei, 10 perces időszakokban átlagolt.
• Szerezze be az összes termosztát-eszköz belső vezérlőprogramjának aktuális verzióját.

Ez a cikk azt ismerteti, hogyan használhatja az API-t /query az eszközök lekérdezésére.

Az eszközök összetevőkbe és modulokba csoportosíthatják az általa támogatott tulajdonságokat, telemetriát és parancsokat.

Minden IoT Central REST API-híváshoz szükség van egy engedélyezési fejlécre. További információ: IoT Central REST API-hívások hitelesítése és engedélyezése.

Az IoT Central REST API referenciadokumentációját az Azure IoT Central REST API-referenciájában találja.

Tipp.

A Postman használatával kipróbálhatja a cikkben ismertetett REST API-hívásokat. Töltse le az IoT Central Postman gyűjteményt , és importálja a Postmanbe. A gyűjteményben olyan változókat kell beállítania, mint az alkalmazás altartománya és a rendszergazdai jogkivonat.

Ha meg szeretné tudni, hogyan kérdezhet le eszközöket az IoT Central felhasználói felületén keresztül, olvassa el az Eszközadatok elemzéséhez az Adatkezelő használata című témakört .

Lekérdezés futtatása

Lekérdezés futtatásához használja a következő kérést:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

A lekérdezés a kérelem törzsében található, és a következő példához hasonlóan néz ki:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

A dtmi:eclipsethreadx:devkit:hlby5jgib2o záradék értéke FROM egy eszközsablon azonosítója. Az eszközsablon azonosítójának megkereséséhez lépjen az IoT Central-alkalmazás Eszközök lapjára, és mutasson a sablont használó eszközre. A kártya tartalmazza az eszközsablon azonosítóját:

A válasz telemetriát tartalmaz több olyan eszközről, amelyek ugyanazt az eszközsablont használják. A kérésre adott válasz a következő példához hasonlóan néz ki:

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Syntax

A lekérdezés szintaxisa hasonló az SQL-szintaxishoz, és a következő záradékokból áll:

• SELECT szükséges, és meghatározza a lekérni kívánt adatokat, például az eszköz telemetriai értékeit.
• FROM szükséges, és azonosítja a lekérdezett eszköztípust. Ez a záradék megadja az eszközsablon azonosítóját.
• WHERE nem kötelező, és lehetővé teszi az eredmények szűrését.
• ORDER BY nem kötelező, és lehetővé teszi az eredmények rendezését.
• GROUP BY nem kötelező, és lehetővé teszi az eredmények összesítését.

A következő szakaszok részletesebben ismertetik ezeket a záradékokat.

SELECT záradék

A SELECT záradék felsorolja a lekérdezés kimenetében felvenni kívánt adatértékeket, és a következő elemeket is tartalmazhatja:

• Telemetria. Használja az eszközsablon telemetriai nevét.
• $id. Az eszköz azonosítója.
• $provisioned. Logikai érték, amely megmutatja, hogy az eszköz ki van-e építve.
• $simulated. Logikai érték, amely megmutatja, hogy az eszköz szimulált eszköz-e.
• $ts. A telemetriai értékhez társított időbélyeg.

Ha az eszközsablon összetevőket használ, az összetevőben definiált telemetriára az alábbiak szerint hivatkozhat:

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Az összetevő nevét az eszközsablonban találja:

A záradékban a SELECT következő korlátozások érvényesek:

• Nincs helyettesítő karakter.
• A kijelölési listában legfeljebb 15 elem szerepelhet.
• A lekérdezés legfeljebb 10 000 rekordot ad vissza.

Aliasok

AS A kulcsszóval definiálhat aliast egy elemhez a SELECT záradékban. Az alias a lekérdezés kimenetében használatos. A lekérdezés más részein is használhatja. Példa:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Tipp.

A kijelölési listában nem használhat más elemet aliasként. Az alábbiak például nem engedélyezettek SELECT id, temp AS id....

Az eredmény a következő kimenethez hasonlóan néz ki:

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

Ezzel korlátozhatja TOP a lekérdezés által visszaadott eredmények számát. A következő lekérdezés például az első 10 találatot adja vissza:

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Ha nem használja TOP, a lekérdezés legfeljebb 10 000 eredményt ad vissza.

Ha az eredményeket az eredmények számának korlátozása előtt TOP szeretné rendezni, használja az ORDER BY parancsot.

FROM záradék

A FROM záradéknak tartalmaznia kell egy eszközsablon-azonosítót. A FROM záradék megadja a lekérdezett eszköz típusát.

Az eszközsablon azonosítójának megkereséséhez lépjen az IoT Central-alkalmazás Eszközök lapjára, és mutasson a sablont használó eszközre. A kártya tartalmazza az eszközsablon azonosítóját:

Az Eszközök – REST API-hívással is lekérheti az eszköz eszközsablon-azonosítóját.

WHERE záradék

A WHERE záradék lehetővé teszi értékek és időablakok használatát az eredmények szűréséhez:

Időablakok

Ha egy adott időkereten belül szeretné megkapni az alkalmazás által kapott telemetriát, használja WITHIN_WINDOW a WHERE záradék részeként. Ha például az elmúlt napra vonatkozóan szeretné lekérni a hőmérséklet- és páratartalom-telemetriát, használja a következő lekérdezést:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Az időablak értéke az ISO 8601 időtartamformátumot használja. Az alábbi táblázat néhány példát tartalmaz:

Példa	Leírás
PT10M	Elmúlt 10 perc
P1D	Elmúlt nap
P2DT12H	Elmúlt 2 nap és 12 óra
P1W	Múlt hét
PT5H	Elmúlt öt óra
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z"	Adott időtartomány

Érték-összehasonlítások

A telemetria adott értékek alapján is lekérhető. Az alábbi lekérdezés például az összes olyan üzenetet adja vissza, amelyben a hőmérséklet nagyobb, mint nulla, a nyomás nagyobb, mint 50, az eszközazonosító pedig a 002-ből és a 003-ból vett minta:

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

A következő operátorok támogatottak:

• Logikai operátorok AND és OR.
• Összehasonlító operátorok =, !=, >, <, >=, <=, <>és IN.

Feljegyzés

Az IN operátor csak telemetriával és $id.

A záradékban a WHERE következő korlátozások érvényesek:

• Egyetlen lekérdezésben legfeljebb 10 operátor használható.
• A lekérdezésekben a WHERE záradék csak telemetriai és eszköz metaadat-szűrőket tartalmazhat.
• Egy lekérdezésben legfeljebb 10 000 rekordot kérdezhet le.

Összesítések és GROUP BY záradék

Az aggregációs függvények lehetővé teszik az olyan értékek kiszámítását, mint az átlag, a maximum és a minimum a telemetriai adatokon egy időablakon belül. Az alábbi lekérdezés például az eszköz sample-001 átlagos hőmérsékletét és páratartalmat számítja ki 10 perces ablakokban:

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

Az eredmények a következő kimenethez hasonlóan néznek ki:

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

A következő összesítési függvények támogatottak: SUM, , MAX, MINCOUNT, AVG, FIRSTés LAST.

Az ablak méretének megadására használható GROUP BY WINDOW . Ha nem használja GROUP BY WINDOW, a lekérdezés összesíti a telemetriát az elmúlt 30 napban.

Feljegyzés

A telemetriai értékek csak összesíthetők.

ORDER BY záradék

A ORDER BY záradék lehetővé teszi, hogy a lekérdezés eredményeit telemetriai érték, időbélyeg vagy eszközazonosító szerint rendezze. Növekvő vagy csökkenő sorrendben rendezhet. A következő lekérdezés például a legutóbbi eredményeket adja vissza először:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

Tipp.

Összevonás ORDER BY a TOP lekérdezés által a rendezés után visszaadott eredmények számának korlátozásához.

Korlátok

A lekérdezések jelenlegi korlátai a következők:

• Legfeljebb 15 elem szerepel a SELECT záradéklistában.
• A záradékban WHERE legfeljebb 10 logikai művelet szerepel.
• A lekérdezési sztring maximális hossza 350 karakter.
• A záradéklistában nem használhatja a SELECT helyettesítő karaktert (*).
• A lekérdezések legfeljebb 10 000 rekordot képesek lekérni.

Következő lépések

Most, hogy megtanulta, hogyan kérdezhet le eszközöket a REST API-val, javasolt következő lépésként megtudhatja , hogyan kezelheti az IoT Central REST API-t a felhasználók és szerepkörök kezelésére.