Principy a používání dvojčat zařízení ve službě IoT Hub

Článek
02/28/2024

Dvojčata zařízení jsou dokumenty JSON, které ukládají informace o stavu zařízení, včetně metadat, konfigurací a podmínek. Azure IoT Hub udržuje takové dvojče pro každé zařízení, které připojíte k IoT Hubu.

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 zařízení: značky, požadované vlastnosti a ohlášené vlastnosti.
Operace, které zařízení a back-endové aplikace můžou provádět s dvojčaty zařízení.

Dvojčata zařízení použijte k:

Ukládejte metadata specifická pro zařízení v cloudu. Například umístění prodejního počítače.
Nahlašujte aktuální informace o stavu, jako jsou dostupné možnosti a podmínky z aplikace zařízení. Například jestli je zařízení připojené k centru IoT přes mobilní síť nebo Wi-Fi.
Synchronizujte stav dlouhotrvajících pracovních postupů mezi aplikací zařízení a back-endovou aplikací. Pokud například back-end řešení určuje novou verzi firmwaru, která se má nainstalovat, a aplikace zařízení hlásí různé fáze procesu aktualizace.
Zadejte dotaz na metadata, konfiguraci nebo stav zařízení.

Další informace o 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.

Další informace o 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í.

Informace o tom, jak dvojčata zařízení souvisejí s modelem zařízení používaným zařízením Azure IoT technologie Plug and Play, najdete v tématu Vysvětlení technologie Plug and Play digitálních dvojčat IoT.

Dvojčata zařízení

Dvojčata zařízení ukládají informace týkající se zařízení, které:

Zařízení a back-endy můžou používat k synchronizaci podmínek a konfigurace zařízení.
Back-end řešení může použít k dotazování a cílení dlouhotrvajících operací.

Životní cyklus dvojčete zařízení je propojený s odpovídající identitou zařízení. Dvojčata zařízení se implicitně vytvářejí a odstraňují, když se v IoT Hubu vytvoří nebo odstraní identita zařízení.

Dvojče zařízení 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 aplikace zařízení.
Požadované vlastnosti. Používá se spolu s ohlášenými vlastnostmi k synchronizaci konfigurace nebo podmínek zařízení. Back-end řešení může nastavit požadované vlastnosti a aplikace zařízení je může číst. Aplikace zařízení 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 zařízení. Aplikace zařízení může nastavit ohlášené vlastnosti a back-end řešení je může číst a dotazovat.
Vlastnosti identity zařízení. Kořen dokumentu JSON dvojčete zařízení obsahuje vlastnosti jen pro čtení z odpovídající identity zařízení uložené v registru identit. Vlastnosti connectionStateUpdatedTime a generationId nebudou zahrnuty.

Diagram that shows which applications interact with which device twin properties.

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

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

Kořenový objekt obsahuje vlastnosti identity zařízení a kontejnerové objekty pro tags i reported vlastnosti a desired vlastnosti. Kontejner properties obsahuje některé prvky jen pro čtení ($metadata a $version) popsané v částech metadat dvojčat zařízení a optimistické souběžnosti .

Příklad ohlášené vlastnosti

V předchozím příkladu obsahuje batteryLevel dvojče zařízení vlastnost, která je hlášena aplikací zařízení. Tato vlastnost umožňuje dotazování a provoz na zařízeních na základě poslední hlášené úrovně baterie. Mezi další příklady patří možnosti zařízení, které hlásí aplikace zařízení, 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 zařízení 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 se požadované a ohlášené vlastnosti dvojčete zařízení používají back-end řešení a aplikace zařízení k synchronizaci konfigurace telemetrie pro toto zařízení. Příklad:

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"
    },
    ...
},
```
Aplikace zařízení se na změnu upozorní okamžitě, pokud je zařízení připojené. Pokud není připojená, aplikace zařízení se při připojení řídí tokem opětovného připojení zařízení. Aplikace zařízení pak hlásí aktualizovanou konfiguraci (nebo chybový stav pomocí status vlastnosti). Tady je část ohlášených vlastností:
```
"reported": {
    "telemetryConfig": {
        "sendFrequency": "5m",
        "status": "success"
    }
    ...
}
```
Back-end řešení může sledovat výsledky operace konfigurace na mnoha zařízeních dotazováním dvojčat zařízení.

Poznámka:

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

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.

Dvojčata můžete použít k synchronizaci dlouhotrvajících operací, jako jsou aktualizace firmwaru. Další informace o použití vlastností k synchronizaci a sledování dlouhotrvající operace napříč zařízeními naleznete v tématu Použití požadovaných vlastností ke konfiguraci zařízení.

Back-endové operace

Back-end řešení funguje na dvojčeti zařízení pomocí následujících atomických operací vystavených prostřednictvím protokolu HTTPS:

Načtěte dvojče zařízení podle ID. Tato operace vrátí dokument dvojčete zařízení, včetně značek a požadovaných a hlášených vlastností systému.
Částečné aktualizace dvojčete zařízení Tato operace umožňuje back-endu řešení částečně aktualizovat značky nebo požadované vlastnosti dvojčete zařízení. Čá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í Nontelemetry.

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 řízení přístupu ke službě IoT Hub.

Kromě těchto operací může back-end řešení:

Dotazování dvojčat zařízení pomocí dotazovacího jazyka IoT Hubu podobného SQL
Provádění operací s velkými sadami dvojčat zařízení pomocí úloh.

Operace zařízení

Aplikace zařízení funguje ve dvojčeti zařízení pomocí následujících atomických operací:

Načtení dvojčete zařízení Tato operace vrátí dokument dvojčete zařízení (včetně požadovaných a ohlášených vlastností systému) pro aktuálně připojené zařízení. (Značky nejsou viditelné pro aplikace zařízení.)
Částečně aktualizujte ohlášené vlastnosti. Tato operace umožňuje částečnou aktualizaci ohlášených vlastností aktuálně připojeného zařízení. 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é zařízení se může rozhodnout dostávat oznámení o aktualizacích požadovaných vlastností, když k nim dojde. Zařízení 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 ří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. Další informace o podrobnostech primitiv IoT Hubu pro synchronizaci požadovaných vlastností najdete v tématu Tok opětovného připojení zařízení.

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.

Poznámka:

Dotazy ioT Hubu používané ve směrování zpráv nepodporují prázdné znaky ani žádný z následujících znaků jako součást názvu klíče: ()<>@,;:\"/?={}.
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 zařízení

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ětšily velikost tags, properties/desirednebo properties/reported dokumenty nad limit.

Metadata dvojčat zařízení

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 zařízení. Č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": {
                        "$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
        }
    }
    ...
}

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 zařízení 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 zařízení mají $version také hodnotu, která je zaručená, že bude přírůstková. Podobně jako u značky ETag může verze používat strana aktualizace k vynucení konzistence aktualizací. Například aplikace zařízení pro ohlášenou vlastnost nebo back-end řešení požadované vlastnosti.

Verze jsou také užitečné, když pozorující agent (například aplikace zařízení 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 Tok opětovného připojení zařízení.

Tok opětovného připojení zařízení

IoT Hub nezachová oznámení o aktualizaci požadovaných vlastností pro odpojená zařízení. Z toho vyplývá, že zařízení, 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:

Aplikace zařízení se připojuje k centru IoT.
Aplikace zařízení se přihlásí k odběru oznámení o aktualizaci požadovaných vlastností.
Aplikace zařízení načte celý dokument pro požadované vlastnosti.

Aplikace zařízení může ignorovat všechna oznámení s $version menší nebo stejnou verzí celé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

Teď jste se dozvěděli o dvojčatech zařízení, možná vás zajímají následující témata příručky pro vývojáře ioT Hubu:

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:

Principy a používání dvojčat zařízení ve službě IoT Hub

Dvojčata zařízení

Příklad ohlášené vlastnosti

Příklad požadované vlastnosti

Back-endové operace

Operace zařízení

Formát značek a vlastností

Velikost dvojčete zařízení

Metadata dvojčat zařízení

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

Tok opětovného připojení zařízení

Další kroky

Další materiály