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.
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
}
]
}
FELSŐ
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
ésOR
. - Összehasonlító operátorok
=
,!=
,>
,<
,>=
,<=
,<>
ésIN
.
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
, MIN
COUNT
, 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.