Ikereszközök megismerése és használata az IoT Hubban
Az ikereszközök olyan JSON-dokumentumok, amelyek eszközállapot-információkat tárolnak, beleértve a metaadatokat, a konfigurációkat és a feltételeket. Az IoT Hub minden egyes rácsatlakoztatott eszközhöz fenntart egy ikereszközt.
Feljegyzés
A cikkben ismertetett funkciók csak az IoT Hub standard szintjén érhetők el. Az alapszintű és standard/ingyenes IoT Hub-szintekről további információt a megoldáshoz megfelelő IoT Hub-szint kiválasztása című témakörben talál.
Ez a cikk a következőket ismerteti:
- Az ikereszköz felépítése: címkék, kívánt tulajdonságok és jelentett tulajdonságok.
- Az eszközalkalmazások és a megoldás háttérrendszere által az ikereszközökön elvégezhető műveletek.
Az ikereszközök használata:
Eszközspecifikus metaadatok tárolása a felhőben. Például az automaták helye.
Az eszközalkalmazás aktuális állapotinformációinak, például az elérhető képességeknek és feltételeknek a jelentése. Például azt, hogy egy eszköz csatlakozik-e az IoT Hubhoz mobil- vagy Wi-Fi-kapcsolaton keresztül.
Szinkronizálja a hosszú ideig futó munkafolyamatok állapotát az eszközalkalmazás és a háttéralkalmazások között. Ha például egy háttéralkalmazás megadja a telepíteni kívánt új belsővezérlőprogram-verziót, és az eszközalkalmazás a frissítési folyamat különböző szakaszait jelenti.
Az eszköz metaadatainak, konfigurációjának vagy állapotának lekérdezése.
A jelentett tulajdonságok, az eszközről a felhőbe irányuló üzenetek vagy a fájlfeltöltés használatáról további információt az Eszközről a felhőbe kommunikációs útmutatóban talál.
A kívánt tulajdonságok, közvetlen metódusok vagy felhőből eszközre irányuló üzenetek használatával kapcsolatos további információkért tekintse meg a felhőről eszközre irányuló kommunikációs útmutatót.
Ha meg szeretné tudni, hogyan kapcsolódnak az ikereszközök az Azure IoT Plug and Play-eszköz által használt eszközmodellhez, olvassa el az IoT Plug and Play digitális ikerpéldányainak ismertetése című témakört.
Ikereszközök
Az ikereszközök az alábbi eszközökkel kapcsolatos információkat tárolják:
Az eszközalkalmazások és a háttéralkalmazások az eszközfeltételek és a konfiguráció szinkronizálására használhatók.
A megoldás háttérrendszere hosszú ideig futó műveletek lekérdezésére és megcélzására használható.
Az ikereszköz életciklusa a megfelelő eszközidentitáshoz van kapcsolva. Az ikereszközök implicit módon jönnek létre és törlődnek az IoT Hub eszközidentitásának létrehozásakor vagy törlésekor.
Az ikereszköz egy JSON-dokumentum, amely a következőket tartalmazza:
Címkék. A JSON-dokumentum egy szakasza, amelyből a háttéralkalmazások olvashatnak és írhatnak. A címkék nem láthatók az eszközalkalmazások számára.
Kívánt tulajdonságok. A jelentett tulajdonságokkal együtt az eszköz konfigurációjának vagy feltételeinek szinkronizálására szolgál. A háttéralkalmazások beállíthatják a kívánt tulajdonságokat, és az eszközalkalmazás elolvashatja őket. Az eszközalkalmazás értesítést is kaphat a kívánt tulajdonságok változásairól.
Jelentett tulajdonságok. Az eszközkonfiguráció vagy -feltételek szinkronizálásához a kívánt tulajdonságokkal együtt használható. Az eszközalkalmazás beállíthatja a jelentett tulajdonságokat, a háttéralkalmazások pedig elolvashatják és lekérdezhetik őket.
Eszközidentitás-tulajdonságok. Az ikereszköz JSON-dokumentumának gyökere az identitásjegyzékben tárolt megfelelő eszközidentitás írásvédett tulajdonságait tartalmazza. A
connectionStateUpdatedTime
tulajdonságok ésgenerationId
a tulajdonságok nem szerepelnek benne.
Az alábbi példa egy ikereszköz JSON-dokumentumát mutatja be:
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
A gyökérobjektum tartalmazza az eszközidentitás tulajdonságait, valamint a tárolóobjektumokat mind a tulajdonságokhoz, mind reported
a desired
tulajdonságokhoztags
. A properties
tároló tartalmaz néhány írásvédett elemet ($metadata
és $version
) az ikereszköz metaadataival és az optimista egyidejűséggel kapcsolatos szakaszokban.
Jelentett tulajdonság példa
Az előző példában az ikereszköz egy jelentett tulajdonságot batteryLevel
tartalmaz. Ez a tulajdonság lehetővé teszi az eszközök lekérdezését és üzemeltetését az utolsó jelentett akkumulátorszint alapján. Ilyenek például az eszközalkalmazás jelentéskészítési eszközképességei vagy a csatlakozási lehetőségek.
Feljegyzés
A jelentett tulajdonságok leegyszerűsítik azokat a forgatókönyveket, amelyekben egy tulajdonság utolsó ismert értéke érdekli. Használjon eszközről felhőbe irányuló üzeneteket , ha az eszköz telemetriáját időbélyegzős események, például idősorok formájában szeretné feldolgozni.
Példa a kívánt tulajdonságra
Az előző példában az telemetryConfig
ikereszköz kívánt és jelentett tulajdonságait a megoldás háttérrendszere és az eszközalkalmazás használja az eszköz telemetriai konfigurációjának szinkronizálásához. Példa:
A háttéralkalmazás a kívánt tulajdonságot a kívánt konfigurációs értékkel állítja be. Íme a dokumentum kívánt tulajdonságkészlettel rendelkező része:
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },
Az eszközalkalmazás azonnal értesítést kap a változásról, ha az eszköz csatlakoztatva van. Ha nincs csatlakoztatva, az eszközalkalmazás a csatlakozáskor követi az eszköz újracsatlakozási folyamatát . Az eszközalkalmazás ezután jelenti a frissített konfigurációt (vagy a tulajdonságot használó hibafeltételt
status
). A jelentett tulajdonságok a következők:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }
Egy háttéralkalmazás számos eszközön nyomon követi a konfigurációs művelet eredményeit az ikereszközök lekérdezésével.
Feljegyzés
Az előző kódrészletek az olvashatóságra optimalizált példák az eszközkonfiguráció és állapotának kódolására. Az IoT Hub nem ír elő konkrét sémát az ikereszköz kívánt és jelentett tulajdonságaihoz az ikereszközben.
Fontos
Az IoT Plug and Play egy sémát definiál, amely több további tulajdonsággal szinkronizálja a kívánt és jelentett tulajdonságok módosításait. Ha a megoldás IoT Plug and Play-t használ, az ikertulajdonságok frissítésekor be kell tartania a Plug and Play konvenciót. További információ és példa: Írható tulajdonságok az IoT Plug and Play szolgáltatásban.
Az ikerpéldányokkal szinkronizálhatja a hosszan futó műveleteket, például a belső vezérlőprogram frissítéseit. Ha többet szeretne tudni arról, hogyan szinkronizálhat és nyomon követheti a hosszú ideig futó műveletet az eszközök között, olvassa el a Kívánt tulajdonságok használata az eszközök konfigurálásához című témakört.
Háttérműveletek
A megoldás háttérrendszere az ikereszközön az alábbi, HTTPS-en keresztül elérhető atomi műveletek használatával működik:
Ikereszköz lekérése azonosító szerint. Ez a művelet visszaadja az ikereszköz-dokumentumot, beleértve a címkéket, valamint a kívánt és jelentett rendszertulajdonságokat.
Az ikereszköz részleges frissítése. Ez a művelet részben frissíti a címkéket vagy a kívánt tulajdonságokat egy ikereszközben. A részleges frissítés olyan JSON-dokumentumként van kifejezve, amely bármilyen tulajdonságot hozzáad vagy frissít. A tulajdonságkészlet
null
el lesz távolítva. Az alábbi példa létrehoz egy új, értékekkel rendelkező{"newProperty": "newValue"}
kívánt tulajdonságot, felülírja a meglévő értéketexistingProperty
,"otherNewValue"
és eltávolítjaotherOldProperty
azt. A meglévő kívánt tulajdonságokat vagy címkéket nem módosítja a rendszer:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }
Cserélje le a kívánt tulajdonságokat. Ez a művelet teljesen felülírja az összes meglévő kívánt tulajdonságot, és lecserél egy új JSON-dokumentumot a következőre
properties/desired
: .Címkék cseréje. Ez a művelet teljesen felülírja az összes meglévő címkét, és lecserél egy új JSON-dokumentumot.
tags
Ikerértesítések fogadása. Ez a művelet értesíti az ikerpéldány módosításáról. Az ikereszköz-változási értesítések fogadásához az IoT-megoldásnak létre kell hoznia egy útvonalat, és be kell állítania a twinChangeEventsnek megfelelő adatforrást. Alapértelmezés szerint nem létezik ilyen útvonal, ezért a rendszer nem küld ikerértesítéseket. Ha a változás sebessége túl magas, vagy más okokból, például belső hibák miatt, az IoT Hub csak egy értesítést küldhet, amely az összes módosítást tartalmazza. Ezért ha az alkalmazásnak megbízható naplózásra és naplózásra van szüksége az összes köztes állapothoz, akkor az eszközről a felhőbe irányuló üzeneteket kell használnia. Az ikerértesítési üzenetben visszaadott tulajdonságokról és törzsről további információt a Nem telemetriai eseménysémák című témakörben talál.
Az előző műveletek mindegyike támogatja az optimista egyidejűséget, és a ServiceConnect-engedélyt igényli az IoT Hubhoz való hozzáférés szabályozásában meghatározott módon.
A fenti műveletek mellett a megoldás háttérrendszere a következőket teheti:
Az ikereszközök lekérdezése az SQL-hez hasonló IoT Hub lekérdezési nyelv használatával.
Műveletek végrehajtása nagy méretű ikereszköz-csoportokon feladatok használatával.
Eszközműveletek
Az eszközalkalmazás az ikereszközön a következő atomi műveletek használatával működik:
Ikereszköz lekérése. Ez a művelet visszaadja az ikereszköz-dokumentumot (beleértve a kívánt és jelentett rendszertulajdonságokat) az aktuálisan csatlakoztatott eszközhöz. (A címkék nem láthatók az eszközalkalmazások számára.)
A jelentett tulajdonságok részleges frissítése. Ez a művelet lehetővé teszi az aktuálisan csatlakoztatott eszköz jelentett tulajdonságainak részleges frissítését.
Figyelje meg a kívánt tulajdonságokat. A jelenleg csatlakoztatott eszköz dönthet úgy, hogy értesítést kap a kívánt tulajdonságok frissítéséről, amikor azok történnek.
Az előző műveletekhez a DeviceConnect-engedélyre van szükség az IoT Hub hozzáférésének szabályozása című témakörben meghatározottak szerint.
Az Azure IoT-eszköz SDK-k megkönnyítik az előző műveletek használatát számos nyelvről és platformról. A kívánt tulajdonságok szinkronizálásához szükséges IoT Hub-primitívek részleteiről további információt az eszköz újracsatlakozási folyamatában talál.
Címkék és tulajdonságok formátuma
A címkék, a kívánt tulajdonságok és a jelentett tulajdonságok az alábbi korlátozásokkal rendelkező JSON-objektumok:
Kulcsok: A JSON-objektumok összes kulcsa UTF-8 kódolású, kis- és nagybetűkre érzékeny, és legfeljebb 1 KB hosszúságú. Az engedélyezett karakterek nem tartalmazzák a UNICODE vezérlőkarakterek (C0 és C1 szegmensek), valamint
.
az ,$
és az SP szegmenseket.Értékek: A JSON-objektumok összes értéke a következő JSON-típusok lehetnek: logikai, szám, sztring, objektum. A tömbök is támogatottak.
Az egész számok minimális értéke -4503599627370496 és maximális 4503599627370495 lehet.
A sztringértékek UTF-8 kódolásúak, és legfeljebb 4 KB hosszúságúak lehetnek.
Mélység: A címkékben, a kívánt tulajdonságokban és a jelentett tulajdonságokban lévő JSON-objektumok maximális mélysége 10. Például a következő objektum érvényes:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Ikereszköz mérete
Az IoT Hub egy 8 KB-os méretkorlátot kényszerít ki az értékre tags
, és 32 KB-os méretkorlátot az értékre properties/desired
és properties/reported
a . Ezek az összegek nem tartalmaznak írásvédett elemeket, például $version
és $metadata/$lastUpdated
.
Az ikerpéldány mérete a következőképpen lesz kiszámítva:
Az IoT Hub összegzően kiszámítja és hozzáadja az egyes tulajdonságok kulcsának és értékének hosszát.
A tulajdonságkulcsok UTF8 kódolású sztringeknek minősülnek.
Az egyszerű tulajdonságértékek UTF8 kódolású sztringeknek, numerikus értékeknek (8 bájt) vagy logikai értékeknek (4 bájt) minősülnek.
Az UTF8 kódolású sztringek méretét az összes karakter megszámlálásával számítjuk ki, a UNICODE-vezérlőkarakterek (C0 és C1 szegmensek) kivételével.
Az összetett tulajdonságértékek (beágyazott objektumok) kiszámítása a bennük található tulajdonságkulcsok és tulajdonságértékek összesített mérete alapján történik.
Az IoT Hub egy hibával elutasít minden olyan műveletet, amely növeli a tags
korlát feletti , properties/desired
vagy properties/reported
dokumentumméretet.
Ikereszköz metaadatai
Az IoT Hub fenntartja az ikereszköz által kívánt és jelentett tulajdonságok minden egyes JSON-objektumának utolsó frissítésének időbélyegét. Az időbélyegek UTC-ben vannak, és ISO8601 formátumban YYYY-MM-DDTHH:MM:SS.mmmZ
vannak kódolva.
Példa:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
Ezek az információk minden szinten megmaradnak (nem csak a JSON-struktúra levelei), hogy megőrizzék az objektumkulcsokat eltávolító frissítéseket.
Optimista párhuzamosság
A címkék, a kívánt tulajdonságok és a jelentett tulajdonságok mind támogatják az optimista egyidejűséget. Ha garantálnia kell az ikertulajdonság-frissítések sorrendjét, fontolja meg a szinkronizálás alkalmazását úgy, hogy megvárja a jelentett tulajdonságok visszahívását a következő frissítés elküldése előtt.
Az ikereszközöknek egy ETag tulajdonságuk etag
van RFC7232 szerint, amely az ikerpéldány JSON-ábrázolása. A tulajdonságot a etag
megoldás háttérrendszerének feltételes frissítési műveleteiben használhatja a konzisztencia biztosításához. Ez a tulajdonság az egyetlen lehetőség a tárolót érintő műveletek konzisztenciájának tags
biztosítására.
Az ikereszköz kívánt és jelentett tulajdonságai olyan értékkel is rendelkeznek $version
, amely garantáltan növekményes. Az ETaghez hasonlóan a verziótulajdonság használatával kényszerítheti a frissítések konzisztenciáját. Például egy jelentett tulajdonság eszközalkalmazása vagy egy kívánt tulajdonság háttéralkalmazása.
A verziók akkor is hasznosak, ha egy megfigyelő ügynöknek (például a kívánt tulajdonságokat megfigyelő eszközalkalmazásnak) össze kell egyeztetnie a versenyeket a lekéréses művelet és a frissítési értesítés eredménye között. Az Eszköz újracsatlakozási folyamat szakasza további információkat tartalmaz.
Eszköz újracsatlakozási folyamata
Az IoT Hub nem őrzi meg a leválasztott eszközök kívánt tulajdonságok frissítési értesítéseit. Ebből következik, hogy a csatlakozó eszköznek le kell kérnie a teljes kívánt tulajdonságdokumentumot a frissítési értesítésekre való feliratkozás mellett. Tekintettel a frissítési értesítések és a teljes lekérés közötti versenyre, a következő folyamatot kell biztosítani:
- Az eszközalkalmazás IoT-központhoz csatlakozik.
- Az eszközalkalmazás feliratkozik a kívánt tulajdonságok frissítési értesítésére.
- Az eszközalkalmazás lekéri a teljes dokumentumot a kívánt tulajdonságokhoz.
Az eszközalkalmazás figyelmen kívül hagyhatja az összes olyan értesítést, amely $version
kisebb vagy egyenlő, mint a teljes lekért dokumentum verziója. Ez a megközelítés azért lehetséges, mert az IoT Hub garantálja, hogy a verziók mindig növekednek.
Következő lépések
A cikkben ismertetett fogalmak kipróbálásához tekintse meg az alábbi IoT Hub-cikkeket: