Principy a používání dvojčat modulů v IoT Hub

Tento článek předpokládá, že jste si přečetli principy a používání dvojčat zařízení v IoT Hub jako první. V IoT Hub můžete pod každou identitou 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, ke kterému se připojíte IoT Hub.

Sady SDK IoT Hub zařízení na straně zařízení umožňují vytvářet moduly, ve kterých každá z nich otevírá nezávislé připojení k IoT Hub. Tato funkce umožňuje používat samostatné obory názvů pro různé komponenty na vašem zařízení. Máte například prodejní automat se třemi různými 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. Tímto způsobem může každé oddělení odesílat úlohy nebo přímé metody pouze do senzoru, který řídí, a vyhnout se tak konfliktům a uživatelským chybám.

Identita modulu a dvojče modulu poskytují stejné funkce jako identita zařízení a dvojče zařízení, ale s jemnější členitostí. Tato jemnější členitost umožňuje zařízením, která jsou schopná, jako jsou zařízení založená na operačním systému nebo zařízení s firmwarem, která spravují více komponent, izolovat konfiguraci a podmínky pro každou z těchto součástí. Identita modulů a dvojčata modulů poskytují oddělení správy při práci se zařízeními IoT, která mají modulární softwarové komponenty. Naším cílem je 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 dostupné jenom na standardní úrovni IoT Hub. Další informace o IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné IoT Hub úrovně 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 zařízení-cloud nebo nahrávání souborů najdete v doprovodných materiálech ke komunikaci zařízení-cloud .

Pokyny k používání požadovaných vlastností, přímých metod nebo zpráv mezi cloudem a zařízením najdete v pokynech ke komunikaci mezi cloudem a zařízením.

Dvojčata modulů

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

  • Moduly na zařízení a IoT Hub můžou používat k synchronizaci podmínek a konfigurace modulu.

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

Ž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 v IoT Hub.

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

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

  • Požadované vlastnosti. Používá se spolu 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 spolu s požadovanými vlastnostmi k synchronizaci konfigurace nebo podmínek modulu. Aplikace modulu může nastavovat ohlášené vlastnosti a back-end řešení je může číst a dotazovat se na ně.

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

Architektonické znázornění dvojčete zařízení

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 objekty kontejneru pro tags a reported vlastnosti a desired . Kontejner properties obsahuje některé prvky jen pro čtení ($metadata a $version) popsané v částech Metadata dvojčete modulu a Optimistická souběžnost .

Příklad ohlášené vlastnosti

V předchozím příkladu obsahuje batteryLevel dvojče modulu vlastnost, kterou hlásí aplikace modulu. Tato vlastnost umožňuje dotazování a provoz modulů na základě poslední hlášené úrovně nabití baterie. Mezi další příklady patří možnosti modulu generování sestav aplikace nebo možnosti připojení.

Poznámka

Hláš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 modulů ve formě posloupností událostí s časovým razítkem, jako jsou časové řady.

Příklad požadované vlastnosti

V předchozím příkladu telemetryConfig používají back-end řešení a aplikace modulu požadované a hlášené vlastnosti dvojčete 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 nastavenou požadovanou vlastností:

    ...
    "desired": {
        "telemetryConfig": {
            "sendFrequency": "5m"
        },
        ...
    },
    ...
    
  2. Aplikace modulu je na změnu upozorněna okamžitě, pokud je modul připojený. Pokud není připojený, aplikace modulu při připojení postupuje podle toku 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, jednoho ze způsobů kódování konfigurace modulu a jejího stavu. IoT Hub neukládá konkrétní schéma pro požadované a hlášené vlastnosti dvojčete modulu ve dvojčatech modulu.

Důležité

IoT 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 Plug and Play, musíte při aktualizaci vlastností dvojčat dodržovat technologie Plug and Play konvence. Další informace a příklad najdete v tématu Zapisovatelné vlastnosti v IoT Plug and Play.

Back-endové operace

Back-end řešení pracuje s dvojčetem modulu pomocí následujících atomických operací, které jsou zveřejněné 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 ohlášených systémových vlastností.

  • Čá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 je vyjádřena jako dokument JSON, který přidává nebo aktualizuje libovolnou vlastnost. Vlastnosti nastavené na hodnotu null se odeberou. Následující příklad vytvoří novou požadovanou vlastnost s hodnotou {"newProperty": "newValue"}, přepíše existující hodnotu existingProperty parametrem "otherNewValue"a odebere otherOldProperty. V existujících požadovaných vlastnostech nebo značkách se neprovedou žádné další změny:

    {
        "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ým dokumentem JSON pro properties/desired.

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

  • Příjem oznámení dvojčete. Tato operace umožňuje, aby byl back-end řešení upozorněn na změnu dvojčete. K tomu musí vaše řešení IoT vytvořit trasu a nastavit zdroj dat na twinChangeEvents. Ve výchozím nastavení žádná taková trasa neexistuje, takže se neposílají žádná oznámení dvojčat. Pokud je četnost změn příliš vysoká nebo z jiných důvodů, jako jsou interní selhání, může IoT Hub odeslat pouze jedno oznámení obsahující 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ě oznámení 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í ServiceConnect, jak je definováno v článku Řízení přístupu k IoT Hub.

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

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 hlášených vlastností systému) pro aktuálně připojený modul.

  • Částečně aktualizovat hláš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 může být upozorněn na aktualizace požadovaných vlastností, když k nim dojde. Modul obdrží stejnou formu aktualizace (částečné nebo úplné nahrazení), kterou provádí back-end řešení.

Všechny předchozí operace vyžadují oprávnění DeviceConnect, jak je definováno v článku Řízení přístupu k 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 mají kódování UTF-8, rozlišují se malá a malá písmena a délku až 1 kB. Povolené znaky nezahrnují řídicí znaky UNICODE (segmenty C0 a C1) a ., $a SP.

  • Hodnoty: Všechny hodnoty v objektech JSON můžou být následujících typů 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 hodnotu properties/desired a properties/reported. Tyto součty jsou bez prvků jen pro čtení, jako jsou $version a $metadata/$lastUpdated.

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

  • Pro každou vlastnost v dokumentu JSON IoT Hub souhrnně vypočítá a sečte délku klíče a hodnoty vlastnosti.

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

  • Hodnoty jednoduchých 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á spočítáním všech znaků s výjimkou řídicích znaků UNICODE (segmentů C0 a C1).

  • Hodnoty komplexních 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ětšily velikost těchto dokumentů nad limit.

Metadata dvojčete modulu

IoT Hub udržuje časové razítko poslední aktualizace pro každý objekt JSON v požadovaných a ohlášených vlastnostech dvojčete modulu. Časová razítka jsou ve formátu UTC a kódovaná 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 objektů.

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

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

Dvojčata modulu mají vlastnost ETag (etag ) podle RFC7232, 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 operací, které zahrnují tags kontejner.

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

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

Tok opětovného připojení modulu

IoT Hub nezachová oznámení o aktualizacích požadovaných vlastností pro odpojené moduly. Z toho vyplývá, že modul, který se připojuje, musí kromě přihlášení k odběru oznámení o aktualizacích načíst celý dokument požadovaných vlastností. Vzhledem k možnému závodu mezi oznámeními o aktualizaci a úplným načtením je nutné zajistit následující tok:

  1. Aplikace modulu se připojuje ke službě IoT Hub.
  2. Aplikace modulu se přihlašuje k odběru oznámení o aktualizacích 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 se verze vždy zvýší.

Další kroky

Pokud chcete vyzkoušet některé z konceptů popsaných v tomto článku, projděte si následující IoT Hub kurzy: