Modulikrek megismerése és használata az IoT Hubban
Ez a cikk feltételezi, hogy elolvasta az IoT Hubban az ikereszközök megértését és használatát. Az IoT Hubban az egyes eszközidentitások alatt legfeljebb 50 modulidentitás hozható létre. Minden modulidentitás implicit módon létrehoz egy modul ikerpéldányt. Az ikereszközökhöz hasonlóan a modul ikerpéldányai olyan JSON-dokumentumok, amelyek modulállapot-információkat tárolnak, beleértve a metaadatokat, a konfigurációkat és a feltételeket. Az Azure IoT Hub minden IoT Hubhoz csatlakozó modulhoz fenntart egy ikermodult.
Az eszközoldalon az IoT Hub eszközoldali SDK-jai lehetővé teszik olyan modulok létrehozását, amelyek mindegyike független kapcsolatot nyit meg az IoT Hubbal. Ez a funkció lehetővé teszi, hogy külön névtereket használjon az eszköz különböző összetevőihez. Például egy automatával rendelkezik, amely három különböző érzékelővel rendelkezik. Minden érzékelőt a vállalat különböző részlegei vezérelnek. Minden érzékelőhöz létrehozhat egy modult. Így minden részleg csak az általuk vezérelt érzékelőnek küldhet feladatokat vagy közvetlen metódusokat, elkerülve az ütközéseket és a felhasználói hibákat.
A modulidentitás és a modul ikerpéldánya ugyanazokat a képességeket biztosítja, mint az eszközidentitás és az ikereszköz, de részletesebben. Ez a finomabb részletesség lehetővé teszi a képes eszközök, például az operációsrendszer-alapú eszközök vagy a több összetevőt kezelő belső vezérlőprogram-eszközök számára, hogy elkülönítsék az egyes összetevők konfigurációját és feltételeit. A modulidentitás és a modul ikerpéldányai felügyeleti elkülönítést biztosítanak a moduláris szoftverösszetevőkkel rendelkező IoT-eszközök használatakor. Célunk, hogy az ikereszköz minden funkcióját a modul ikerszintjén, a modul ikerpéldányainak általános elérhetősége alapján támogassuk.
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:
- A modul ikerszerkezete: címkék, kívánt és jelentett tulajdonságok.
- Azok a műveletek, amelyeket a modulok és a háttérrendszer képes végrehajtani a modulikreken.
Ikermodulok
A modul ikerpéldányai a következő modulokkal kapcsolatos információkat tárolják:
Az eszközön és az IoT Hubon található modulok a modulfelté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ó.
A modul ikerpéldányának életciklusa a megfelelő modulidentitáshoz van kapcsolva. A modulok ikerpéldányai implicit módon jönnek létre és törlődnek az IoT Hubban létrehozott vagy törölt modulidentitások esetén.
A modul ikerpéldánya egy JSON-dokumentum, amely a következőket tartalmazza:
Címkék. A JSON-dokumentum egy szakasza, amelyből a megoldás háttérrendszere tud olvasni és írni. A címkék nem láthatók az eszközön lévő modulok számára. A címkék lekérdezési célra vannak beállítva.
Kívánt tulajdonságok. A jelentett tulajdonságok mellett a modul konfigurációjának vagy feltételeinek szinkronizálására is használható. A megoldás háttérrendszere beállíthatja a kívánt tulajdonságokat, és a modulalkalmazás elolvashatja őket. A modulalkalmazás értesítést is kaphat a kívánt tulajdonságok változásairól.
Jelentett tulajdonságok. A modulkonfiguráció vagy -feltételek szinkronizálásához a kívánt tulajdonságokkal együtt használható. A modulalkalmazás beállíthatja a jelentett tulajdonságokat, és a megoldás háttérrendszere elolvashatja és lekérdezheti őket.
A modul identitástulajdonságai. A modul iker JSON-dokumentumának gyökere az identitásjegyzékben tárolt megfelelő modulidentitás írásvédett tulajdonságait tartalmazza.
Az alábbi példa egy ikermodul JSON-dokumentumát mutatja be:
{
"deviceId": "devA",
"moduleId": "moduleA",
"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érobjektumban a modul identitástulajdonságai, valamint a tárolóobjektumok mind a tulajdonságok, tags mind pedig desired a reported tulajdonságok. A properties tároló tartalmaz néhány írásvédett elemet ($metadataés $version) a Modul iker metaadatai és az Optimista egyidejűség szakaszában leírtak szerint.
Jelentett tulajdonság példa
Az előző példában a modul ikerpéldánya tartalmaz egy batteryLevel tulajdonságot, amelyet a modulalkalmazás jelent. Ez a tulajdonság lehetővé teszi a modulok lekérdezését és üzemeltetését az utolsó jelentett akkumulátorszint alapján. További példák a modulalkalmazás jelentéskészítési modul képességeire vagy a csatlakozási lehetőségekre.
Feljegyzés
A jelentett tulajdonságok leegyszerűsítik azokat a forgatókönyveket, amelyekben a megoldás háttérrendszere érdekli egy tulajdonság utolsó ismert értékét. Használjon eszközről felhőbe irányuló üzeneteket , ha a megoldás háttérrendszerének modultelemetria-telemetria feldolgozására van szükség időbélyegekkel ellátott események sorozatai, például idősorok formájában.
Példa a kívánt tulajdonságra
Az előző példában a telemetryConfig modul háttérrendszere és a modulalkalmazás a kívánt és jelentett tulajdonságokat használja a modul telemetriai konfigurációjának szinkronizálásához. Példa:
A megoldás háttérrendszere 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" }, ... }, ...A modulalkalmazás azonnal értesítést kap a változásról, ha a modul csatlakoztatva van. Ha nincs csatlakoztatva, a modulalkalmazás a modul újracsatlakozási folyamatát követi, amikor csatlakozik. A modulalkalmazá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" } ... }A megoldás háttérrendszere számos modulban nyomon követheti a konfigurációs művelet eredményeit a modul ikerpéldányainak lekérdezésével.
Feljegyzés
Az előző kódrészletek az olvashatóságra optimalizált példák egy modulkonfiguráció és állapotának kódolására. Az IoT Hub nem ír elő konkrét sémát az ikermodul kívánt és jelentett tulajdonságaihoz a modul ikerpéldányaiban.
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.
Háttérműveletek
A megoldás háttérrendszere a modul ikerpéldányán működik az alábbi, HTTPS-en keresztül elérhető atomi műveletek használatával:
Modul ikerpéldányának lekérése azonosító szerint. Ez a művelet visszaadja a modul ikerdokumentumát, beleértve a címkéket, valamint a kívánt és jelentett rendszertulajdonságokat.
Részben frissítse a modul ikerpéldányát. Ez a művelet lehetővé teszi, hogy a megoldás háttérrendszere részben frissítse a címkéket vagy a kívánt tulajdonságokat egy modul ikerpéldányában. 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
nullel 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ítjaotherOldPropertyazt. 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 lehetővé teszi, hogy a megoldás háttérrendszere teljesen felülírja az összes meglévő kívánt tulajdonságot, és helyettesítsen egy új JSON-dokumentumot.
properties/desiredCímkék cseréje. Ez a művelet lehetővé teszi, hogy a megoldás háttérrendszere teljesen felülírja az összes meglévő címkét, és helyettesítsen egy új JSON-dokumentumot.
tagsIkerértesítések fogadása. Ez a művelet lehetővé teszi a megoldás háttérrendszerének értesítését az ikerpéldány módosításakor. Ehhez 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 támogatják az optimista egyidejűséget, és a Szolgáltatás Csatlakozás engedélyre van szükségük az IoT Hubhoz való hozzáférés szabályozásáról szóló cikkben meghatározottak szerint.
Ezen műveletek mellett a megoldás háttérrendszere az SQL-hez hasonló IoT Hub lekérdezési nyelv használatával is lekérdezheti a modul ikerpéldányait.
Modulműveletek
A modulalkalmazás a modul ikerpéldányán a következő atomi műveletek használatával működik:
Modul ikerpéldányának lekérése. Ez a művelet visszaadja a modul ikerdokumentumát (beleértve a kívánt és jelentett rendszertulajdonságokat) az aktuálisan csatlakoztatott modulhoz.
A jelentett tulajdonságok részleges frissítése. Ez a művelet lehetővé teszi az aktuálisan csatlakoztatott modul jelentett tulajdonságainak részleges frissítését. Ez a művelet ugyanazt a JSON-frissítési formátumot használja, amelyet a megoldás háttérrendszere a kívánt tulajdonságok részleges frissítéséhez használ.
Figyelje meg a kívánt tulajdonságokat. A jelenleg csatlakoztatott modul dönthet úgy, hogy értesítést kap a kívánt tulajdonságok frissítéséről, amikor azok történnek. A modul ugyanazt a frissítési formát kapja (részleges vagy teljes cserét), amelyet a megoldás háttérrendszere hajt végre.
Az előző műveletekhez az Eszköz Csatlakozás engedélyre van szükség az IoT Hubhoz való hozzáférés szabályozása című cikkben 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.
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" } } } } } } } } } } }, ... }
Modul ikermérete
Az IoT Hub 8 KB-os méretkorlátot kényszerít ki az értékretags, és egy 32 KB-os méretkorlátot az és properties/reporteda properties/desired . 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:
A JSON-dokumentum minden tulajdonságához az IoT Hub kumulatívan kiszámítja és hozzáadja a tulajdonság 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 dokumentumok méretét a korlát felett.
Ikermodul metaadatai
Az IoT Hub fenntartja az ikermodul kívánt és jelentett tulajdonságai között az egyes JSON-objektumok 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.mmmZvannak 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": "5m",
"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.
A modul ikerpéldányai rendelkeznek egy ETag (etag tulajdonság) tulajdonságkal, amely RFC7232 szerint 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 az egyetlen lehetőség a tárolót érintő műveletek konzisztenciájának tags biztosítására.
Az ikermodul kívánt és jelentett tulajdonságainak értéke garantáltan $version növekményes. Az ETaghez hasonlóan a verziót a frissítési fél is használhatja a frissítések konzisztenciájának kikényszerítéséhez. Például egy modulalkalmazás egy jelentett tulajdonsághoz vagy egy kívánt tulajdonság megoldásháttéréhez.
A verziók akkor is hasznosak, ha egy megfigyelő ügynöknek (például a kívánt tulajdonságokat megfigyelő modulalkalmazá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. A modul újracsatlakozási folyamata további információkat tartalmaz.
Modul újracsatlakozási folyamata
Az IoT Hub nem őrzi meg a leválasztott modulok kívánt tulajdonságok frissítési értesítéseit. Ebből következik, hogy a csatlakozó modulnak 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:
- A modulalkalmazás egy IoT Hubhoz csatlakozik.
- A modulalkalmazás feliratkozik a kívánt tulajdonságok frissítési értesítésére.
- A modulalkalmazás lekéri a teljes dokumentumot a kívánt tulajdonságokhoz.
A modulalkalmazá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-oktatóanyagokat: