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.

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 és generationId 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.

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

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. 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.

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é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 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.

  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:

• 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 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 egy ETag tulajdonságuk etagvan 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:

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

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

• Oktatóanyag: Eszközök konfigurálása ikereszköz-tulajdonságokkal
• Ikereszközök használata