Principy a používání dvojčat modulů ve službě IoT Hub

Tento článek předpokládá, že jste napřed četli principy a používání dvojčat zařízení ve službě IoT Hub . V IoT Hubu můžete v rámci každé identity zařízení vytvořit až 50 identit modulů. Každá identita modulu implicitně generuje dvojče modulu. Podobně jako dvojčata zařízení jsou dvojčata modulů dokumenty JSON, které ukládají informace o stavu modulu, včetně metadat, konfigurací a podmínek. Azure IoT Hub udržuje dvojče modulu pro každý modul, který se připojujete ke službě IoT Hub.

Na straně zařízení umožňují sady SDK pro zařízení ioT Hub vytvářet moduly, ve kterých každý otevře nezávislé připojení ke službě IoT Hub. Tato funkce umožňuje používat samostatné obory názvů pro různé komponenty ve vašem zařízení. Máte například prodejní stroj, který má tři různé senzory. Každý senzor je řízen různými odděleními ve vaší společnosti. Pro každý senzor můžete vytvořit modul. Díky tomu může každé oddělení odesílat úlohy nebo přímé metody jenom senzoru, který řídí, vyhnout se konfliktům a chybám uživatelů.

Identita modulu a dvojče modulu poskytují stejné funkce jako identita zařízení a dvojče zařízení, ale s jemně členitostí. Tato jemně členitost umožňuje zařízením podporujícím, jako jsou zařízení založená na operačním systému nebo zařízení firmwaru, která spravují více komponent, izolovat konfiguraci a podmínky pro každou z těchto komponent. Identita modulů a dvojčata modulů poskytují oddělení problémů správy při práci se zařízeními IoT, která mají modulární softwarové komponenty. Snažíme se podporovat všechny funkce dvojčete zařízení na úrovni dvojčete modulu podle obecné dostupnosti dvojčete modulu.

Poznámka:

Funkce popsané v tomto článku jsou k dispozici pouze na úrovni Standard služby IoT Hub. Další informace o úrovních Služby IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné úrovně IoT Hubu pro vaše řešení.

Tento článek popisuje:

  • Struktura dvojčete modulu: značky, požadované a hlášené vlastnosti.
  • Operace, které moduly a back-endy můžou provádět s dvojčaty modulů.

Pokyny k používání ohlášených vlastností, zpráv typu zařízení-cloud nebo nahrávání souborů najdete v doprovodných materiálech ke komunikaci typu zařízení-cloud.

Pokyny k používání požadovaných vlastností, přímých metod nebo zpráv typu cloud-zařízení najdete v doprovodných materiálech ke komunikaci typu Cloud-zařízení.

Dvojčata modulů

Dvojčata modulů ukládají informace související s modulem, které:

  • Moduly na zařízení a IoT Hubu můžou použít k synchronizaci podmínek a konfigurace modulů.

  • Back-end řešení může použít k dotazování a cílení dlouhotrvajících operací.

Životní cyklus dvojčete modulu je propojený s odpovídající identitou modulu. Dvojčata modulů se implicitně vytvářejí a odstraňují při vytvoření nebo odstranění identity modulu ve službě IoT Hub.

Dvojče modulu je dokument JSON, který obsahuje:

  • Značky. Část dokumentu JSON, do kterého může back-end řešení číst a zapisovat do. Značky nejsou viditelné pro moduly v zařízení. Značky jsou nastavené pro účely dotazování.

  • Požadované vlastnosti. Používá se společně s ohlášenými vlastnostmi k synchronizaci konfigurace nebo podmínek modulu. Back-end řešení může nastavit požadované vlastnosti a aplikace modulu je může číst. Aplikace modulu může také přijímat oznámení o změnách požadovaných vlastností.

  • Ohlášené vlastnosti Používá se společně s požadovanými vlastnostmi k synchronizaci konfigurace nebo podmínek modulu. Aplikace modulu může nastavit ohlášené vlastnosti a back-end řešení je může číst a dotazovat.

  • Vlastnosti identity modulu Kořen dokumentu JSON dvojčete modulu obsahuje vlastnosti jen pro čtení z odpovídající identity modulu uložené v registru identit.

Architectural representation of device twin

Následující příklad ukazuje dokument JSON dvojčete modulu:

{
    "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
        }
    }
}

V kořenovém objektu jsou vlastnosti identity modulu a kontejnerové objekty pro tags a obě reported i desired vlastnosti. Kontejner properties obsahuje některé prvky jen pro čtení ($metadata a $version) popsané v metadatech dvojčat modulů a v částech Optimistická souběžnost .

Příklad ohlášené vlastnosti

V předchozím příkladu obsahuje batteryLevel dvojče modulu vlastnost, která je hlášena aplikací modulu. Tato vlastnost umožňuje dotazovat se na moduly a pracovat s ním na základě poslední hlášené úrovně baterie. Mezi další příklady patří možnosti modulu generování sestav nebo možnosti připojení.

Poznámka:

Ohlášené vlastnosti zjednodušují scénáře, ve kterých se back-end řešení zajímá o poslední známou hodnotu vlastnosti. Zprávy typu zařízení-cloud použijte, pokud back-end řešení potřebuje zpracovávat telemetrii modulu ve formě sekvencí událostí s časovým razítkem, jako jsou časové řady.

Příklad požadované vlastnosti

V předchozím příkladu telemetryConfig se požadované a ohlášené vlastnosti dvojčete modulu používají back-end řešení a aplikace modulu k synchronizaci konfigurace telemetrie pro tento modul. Příklad:

  1. Back-end řešení nastaví požadovanou vlastnost s požadovanou hodnotou konfigurace. Tady je část dokumentu s požadovanou sadou vlastností:

    ...
    "desired": {
        "telemetryConfig": {
            "sendFrequency": "5m"
        },
        ...
    },
    ...
    
  2. Aplikace modulu obdrží oznámení o změně okamžitě, pokud je modul připojený. Pokud není připojený, aplikace modulu se při připojení řídí tokem opětovného připojení modulu. Aplikace modulu pak hlásí aktualizovanou konfiguraci (nebo chybový stav pomocí status vlastnosti). Tady je část ohlášených vlastností:

    "reported": {
        "telemetryConfig": {
            "sendFrequency": "5m",
            "status": "success"
        }
        ...
    }
    
  3. Back-end řešení může sledovat výsledky operace konfigurace napříč mnoha moduly dotazováním dvojčat modulů.

Poznámka:

Předchozí fragmenty kódu jsou příklady, optimalizované pro čitelnost, jedním ze způsobů, jak zakódovat konfiguraci modulu a její stav. IoT Hub neukládá konkrétní schéma požadovaného dvojčete modulu a ohlášené vlastnosti ve dvojčatech modulu.

Důležité

IoT technologie Plug and Play definuje schéma, které používá několik dalších vlastností k synchronizaci změn požadovaných a ohlášených vlastností. Pokud vaše řešení používá ioT technologie Plug and Play, musíte při aktualizaci vlastností dvojčete dodržovat technologie Plug and Play konvence. Další informace a příklad najdete v tématu Zapisovatelné vlastnosti ve službě IoT technologie Plug and Play.

Back-endové operace

Back-end řešení pracuje s dvojčetem modulu pomocí následujících atomických operací vystavených prostřednictvím protokolu HTTPS:

  • Načtení dvojčete modulu podle ID Tato operace vrátí dokument dvojčete modulu, včetně značek a požadovaných a hlášených vlastností systému.

  • Částečné aktualizace dvojčete modulu Tato operace umožňuje back-endu řešení částečně aktualizovat značky nebo požadované vlastnosti ve dvojčeti modulu. Částečná aktualizace se vyjadřuje jako dokument JSON, který přidává nebo aktualizuje libovolnou vlastnost. Vlastnosti nastavené na odebrání null . Následující příklad vytvoří novou požadovanou vlastnost s hodnotou {"newProperty": "newValue"}, přepíše existující hodnotu existingProperty pomocí "otherNewValue"a odebere otherOldProperty. Žádné další změny stávajících požadovaných vlastností nebo značek:

    {
        "properties": {
            "desired": {
                "newProperty": {
                    "nestedProperty": "newValue"
                },
                "existingProperty": "otherNewValue",
                "otherOldProperty": null
            }
        }
    }
    
  • Nahraďte požadované vlastnosti. Tato operace umožňuje back-endu řešení zcela přepsat všechny existující požadované vlastnosti a nahradit nový dokument properties/desiredJSON .

  • Nahradit značky Tato operace umožňuje back-endu řešení zcela přepsat všechny existující značky a nahradit nový dokument JSON .tags

  • Příjem oznámení dvojčete Tato operace umožňuje, aby back-end řešení byl upozorněn při úpravě dvojčete. K tomu musí vaše řešení IoT vytvořit trasu a nastavit zdroj dat na hodnotu twinChangeEvents. Ve výchozím nastavení neexistuje žádná taková trasa, takže se neposílají žádná oznámení dvojčete. Pokud je míra změn příliš vysoká nebo z jiných důvodů, například z interních selhání, může IoT Hub odeslat pouze jedno oznámení, které obsahuje všechny změny. Proto pokud vaše aplikace potřebuje spolehlivé auditování a protokolování všech přechodných stavů, měli byste použít zprávy typu zařízení-cloud. Další informace o vlastnostech a textu vrácených ve zprávě s oznámením dvojčete najdete v tématu Schémata událostí bez telemetrie.

Všechny předchozí operace podporují optimistickou souběžnost a vyžadují oprávnění ke službě Připojení, jak je definováno v článku Řízení přístupu ke službě IoT Hub.

Kromě těchto operací může back-end řešení dotazovat dvojčata modulu pomocí dotazovacího jazyka IoT Hub podobného SQL.

Operace modulů

Aplikace modulu pracuje s dvojčetem modulu pomocí následujících atomických operací:

  • Načtení dvojčete modulu Tato operace vrátí dokument dvojčete modulu (včetně požadovaných a ohlášených vlastností systému) pro aktuálně připojený modul.

  • Částečně aktualizujte ohlášené vlastnosti. Tato operace umožňuje částečnou aktualizaci ohlášených vlastností aktuálně připojeného modulu. Tato operace používá stejný formát aktualizace JSON, který back-end řešení používá pro částečnou aktualizaci požadovaných vlastností.

  • Sledujte požadované vlastnosti. Aktuálně připojený modul se může rozhodnout dostávat oznámení o aktualizacích požadovaných vlastností, když k nim dojde. Modul obdrží stejnou formu aktualizace (částečné nebo úplné nahrazení) spuštěnou back-endem řešení.

Všechny předchozí operace vyžadují oprávnění Zařízení Připojení definované v článku Řízení přístupu ke službě IoT Hub.

Sady SDK pro zařízení Azure IoT usnadňují používání předchozích operací z mnoha jazyků a platforem.

Formát značek a vlastností

Značky, požadované vlastnosti a ohlášené vlastnosti jsou objekty JSON s následujícími omezeními:

  • Klíče: Všechny klíče v objektech JSON jsou kódované UTF-8, rozlišují velká a malá písmena a mají délku až 1 kB. Povolené znaky vylučují řídicí znaky UNICODE (segmenty C0 a C1) a ., $a , a SP.

  • Hodnoty: Všechny hodnoty v objektech JSON můžou být následující typy JSON: logická hodnota, číslo, řetězec, objekt. Podporují se také pole.

    • Celá čísla můžou mít minimální hodnotu -4503599627370496 a maximální hodnotu 4503599627370495.

    • Řetězcové hodnoty jsou kódované UTF-8 a mohou mít maximální délku 4 kB.

  • Hloubka: Maximální hloubka objektů JSON ve značkách, požadovaných vlastnostech a ohlášených vlastnostech je 10. Například následující objekt je platný:

    {
         ...
         "tags": {
             "one": {
                 "two": {
                     "three": {
                         "four": {
                             "five": {
                                 "six": {
                                     "seven": {
                                         "eight": {
                                             "nine": {
                                                 "ten": {
                                                     "property": "value"
                                                 }
                                             }
                                         }
                                     }
                                 }
                             }
                         }
                     }
                 }
             }
         },
         ...
    }
    

Velikost dvojčete modulu

IoT Hub vynucuje limit velikosti 8 kB pro hodnotu tagsa limit velikosti 32 kB pro každou hodnotu a properties/desiredproperties/reported. Tyto součty jsou exkluzivní pro prvky jen pro čtení jako $version a $metadata/$lastUpdated.

Velikost dvojčete se vypočítá takto:

  • Pro každou vlastnost v dokumentu JSON služba IoT Hub souhrnně vypočítá a přidá délku klíče a hodnoty vlastnosti.

  • Klíče vlastností se považují za řetězce s kódováním UTF8.

  • Jednoduché hodnoty vlastností se považují za řetězce s kódováním UTF8, číselné hodnoty (8 bajtů) nebo logické hodnoty (4 bajty).

  • Velikost řetězců s kódováním UTF8 se vypočítá počítá počítáním všech znaků s výjimkou řídicích znaků UNICODE (segmenty C0 a C1).

  • Komplexní hodnoty vlastností (vnořené objekty) se počítají na základě agregované velikosti klíčů vlastností a hodnot vlastností, které obsahují.

IoT Hub odmítne s chybou všechny operace, které by zvýšily velikost těchto dokumentů nad limit.

Metadata dvojčat modulů

IoT Hub udržuje časové razítko poslední aktualizace každého objektu JSON v požadovaných a ohlášených vlastnostech dvojčete modulu. Časová razítka jsou ve formátu UTC a kódována ve formátu YYYY-MM-DDTHH:MM:SS.mmmZISO8601 . Příklad:

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

Tyto informace se uchovávají na všech úrovních (nejen na listech struktury JSON), aby se zachovaly aktualizace, které odeberou klíče objektu.

Optimistická metoda souběžného zpracování

Značky, požadované vlastnosti a ohlášené vlastnosti podporují optimistickou souběžnost. Pokud potřebujete zaručit pořadí aktualizací vlastností dvojčete, zvažte implementaci synchronizace na úrovni aplikace čekáním na zpětné volání ohlášených vlastností před odesláním další aktualizace.

Dvojčata modulů mají podle RFC7232 ETag (etagvlastnost), která představuje reprezentaci JSON dvojčete. Vlastnost můžete použít etag v operacích podmíněné aktualizace z back-endu řešení, abyste zajistili konzistenci. Toto je jediná možnost pro zajištění konzistence v operacích, které zahrnují tags kontejner.

Požadované a hlášené vlastnosti dvojčete modulu mají $version také hodnotu, která je zaručená jako přírůstková. Podobně jako u značky ETag může verze používat strana aktualizace k vynucení konzistence aktualizací. Například aplikace modulu pro ohlášenou vlastnost nebo back-end řešení požadované vlastnosti.

Verze jsou užitečné také v případě, že pozorující agent (například aplikace modulu pozorující požadované vlastnosti) musí odsouhlasit časy mezi výsledkem operace načtení a oznámením o aktualizaci. Další informace najdete v části Modul opětovného připojení.

Tok opětovného připojení modulu

IoT Hub nezachová oznámení o aktualizaci požadovaných vlastností pro odpojené moduly. Následuje, že modul, který se připojuje, musí kromě odběru oznámení o aktualizacích načíst celý dokument požadovaných vlastností. Vzhledem k možnosti rasy mezi oznámeními o aktualizaci a úplným načítáním musí být zajištěn následující tok:

  1. Aplikace modulu se připojuje ke službě IoT Hub.
  2. Aplikace modulu se přihlásí k odběru oznámení o aktualizaci požadovaných vlastností.
  3. Aplikace modulu načte celý dokument pro požadované vlastnosti.

Aplikace modulu může ignorovat všechna oznámení s $version menší nebo rovnou verzi úplného načteného dokumentu. Tento přístup je možný, protože IoT Hub zaručuje, že verze se vždy zvýší.

Další kroky

Pokud si chcete vyzkoušet některé koncepty popsané v tomto článku, projděte si následující kurzy ke službě IoT Hub: