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özök és a háttéralkalmazások á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 hosszan futó munkafolyamatok állapotát az eszközalkalmazás és a háttéralkalmazás között. Ha például a megoldás háttérrendszere 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öz- és háttérrendszerek 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 megoldás háttérrendszere tud olvasni és írni. 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 megoldás háttérrendszere beállíthatja 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, és a megoldás háttérrendszere elolvashatja és lekérdezheti ő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. Tulajdonságok connectionStateUpdatedTime , és generationId nem lesznek belefoglalva.

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 tartalmaz egy batteryLevel tulajdonságot, amelyet az eszközalkalmazás jelent. 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 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 időbélyegekkel ellátott események sorozatai, például idősorok formájában kell feldolgoznia az eszköz telemetriáját.

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:

1. 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"
       },
       ...
   },
   

2. 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"
       }
       ...
   }
   

3. A megoldás háttérrendszere számos eszközön nyomon követheti 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 lehetővé teszi, hogy a megoldás háttérrendszere részben frissítse az ikereszköz címkéinek vagy kívánt tulajdonságainak egy részét. 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éket existingProperty , "otherNewValue"és eltávolítja otherOldPropertyazt. 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/desired

• Cí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.tags

• Ikeré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 összes fenti művelet támogatja az optimista egyidejűséget, és a Szolgáltatás Csatlakozás 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.

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. 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 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 eszköz ugyanazt a frissítést 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ély szükséges, 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.

  Feljegyzés

  Az Üzenet-útválasztásban használt IoT Hub-lekérdezések nem támogatják a szóközt vagy a következő karaktereket a kulcsnév részeként: ()<>@,;:\"/?={}.

• É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/reporteda . 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 tagskorlát feletti , properties/desiredvagy 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.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": {
                        "$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 van egy ETag (etag tulajdonságuk) a 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 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ó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 eszközalkalmazás egy jelentett tulajdonsághoz vagy a megoldás háttérrendszeréhez egy kívánt tulajdonsághoz.

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:

1. Az eszközalkalmazás IoT-központhoz csatlakozik.
2. Az eszközalkalmazás feliratkozik a kívánt tulajdonságok frissítési értesítésére.
3. 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

Most, hogy megismerkedett az ikereszközökkel, az alábbi IoT Hub fejlesztői útmutató témakörök érdekelhetik:

• Modulikrek megismerése és használata az IoT Hubban
• Közvetlen metódus meghívása eszközön
• Feladatok ütemezése több eszközön

A cikkben ismertetett fogalmak kipróbálásához tekintse meg az alábbi IoT Hub-oktatóanyagokat:

• Az ikereszköz használata
• Ikereszköz-tulajdonságok használata
• Eszközkezelés a VS Code Azure IoT Hub-bővítményével