Understand and use device twins in IoT Hub

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 Basic a Standard/Free IoT Hub najdete v tématu Volba správné úrovně a velikosti služby IoT Hub pro vaše řešení.

Tento článek popisuje:

• Struktura dvojčete zařízení: značky, požadované vlastnosti a ohlášené vlastnosti.
• The operations that device applications and the solution back end can perform on device twins.

Use device twins to:

• Ukládejte metadata specifická pro zařízení v cloudu. Například umístění prodejního automatu.

• 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-endovými aplikacemi. Pokud například back-endová aplikace 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 se dvojčata zařízení týkají modelu zařízení používaného zařízeními Azure IoT Plug and Play, najdete v tématu Porozumění digitálním dvojčatům technologie IoT Plug and Play.

Device twins

Device twins store device-related information that:

• Aplikace zařízení a back-endové aplikace mohou být použity k synchronizaci podmínek a konfiguraci 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í.

A device twin is a JSON document that includes:

• Značky. Část dokumentu JSON, do kterého můžou back-endové aplikace čí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-endové aplikace můžou 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-endové aplikace je mohou číst a dotazovat.

• Identitní vlastnosti zařízení. The root of the device twin JSON document contains the read-only properties from the corresponding device identity stored in the identity registry. connectionStateUpdatedTime a generationId vlastnosti nejsou zahrnuty.

The following example shows a device twin JSON document:

{
    "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 a také pro vlastnosti reported a desired. The properties container contains some read-only elements ($metadata and $version) described in the Device twin metadata and Optimistic concurrency sections.

Příklad ohlášené vlastnosti

In the previous example, the device twin contains a batteryLevel reported property. 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ří aplikace zařízení, která hlásí možnosti zařízení nebo možnosti připojení.

Poznámka:

Ohlášené vlastnosti zjednodušují scénáře, ve kterých vás zajímá poslední známá hodnota vlastnosti. Use device-to-cloud messages if you want to process device telemetry in the form of sequences of timestamped events, such as time series.

Příklad požadované vlastnosti

In the previous example, the telemetryConfig device twin desired and reported properties are used by the solution back end and the device app to synchronize the telemetry configuration for this device. Příklad:

1. Back-endová aplikace nastaví požadovanou vlastnost s požadovanou hodnotou konfigurace. Zde je část dokumentu s požadovanou vlastností nastavenou:

   "desired": {
       "telemetryConfig": {
           "sendFrequency": "5m"
       },
       ...
   },
   

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

3. A back-end app tracks the results of the configuration operation across many devices by querying device twins.

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 does not impose a specific schema for the device twin desired and reported properties in the device twins.

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

Operace na pozadí

The solution back end operates on the device twin using the following atomic operations, exposed through HTTPS:

• Retrieve device twin by ID. This operation returns the device twin document, including tags and desired and reported system properties.

• Partially update device twin. This operation partially updates the tags or desired properties in a device twin. Částečná aktualizace se vyjadřuje jako dokument JSON, který přidává nebo aktualizuje libovolnou vlastnost. Vlastnosti nastavené na null jsou odstraněny. 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 zcela přepíše všechny existující požadované vlastnosti a nahradí nový dokument JSON .properties/desired

• Replace tags. Tato operace zcela přepíše všechny existující značky a nahradí je novým dokumentem JSON pro tags.

• Receive twin notifications. This operation notifies when the twin is modified. Pokud chcete dostávat oznámení o změnách dvojčat zařízení, musí vaše řešení IoT vytvořit trasu a nastavit zdroj dat na hodnotu twinChangeEvents. Ve výchozím nastavení taková trasa neexistuje, takže se neposílají žádná dvojitá oznámení. 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. To learn more about the properties and body returned in the twin notification message, see Nontelemetry event schemas.

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

Kromě těchto operací může backend řešení:

• Query the device twins using the SQL-like IoT Hub query language.

• Perform operations on large sets of device twins using jobs.

Operace zařízení

The device app operates on the device twin using the following atomic operations:

• Retrieve device twin. 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í.

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

Všechny předchozí operace vyžadují oprávnění DeviceConnect , jak je definováno 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 také ., $ 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. Arrays are also supported.

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

Device twin size

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

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

• IoT Hub počítá kumulativně a sčítá délku klíče a hodnoty každé 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.

Device twin metadata

IoT Hub maintains the timestamp of the last update for each JSON object in device twin desired and reported properties. Časová razítka jsou ve formátu UTC a kódována ve .

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.

Optimistic concurrency

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.

Device twins have an ETag property etag, as per RFC7232, that represents the twin's JSON representation. Abyste zajistili konzistenci, můžete použít vlastnost etag v operacích podmíněné aktualizace z back-endu řešení. Tato vlastnost je jedinou možností pro zajištění konzistence v operacích, které zahrnují tags kontejner.

Device twin desired and reported properties also have a $version value that is guaranteed to be incremental. Podobně jako u značky ETag můžete použít vlastnost verze k vynucení konzistence aktualizací. Například aplikace zařízení pro ohlášenou vlastnost nebo back-endovou aplikaci pro požadovanou vlastnost.

Verze jsou také užitečné, když pozorující agent (například aplikace zařízení sledující požadované vlastnosti) musí řešit konflikty 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 konkurence mezi oznámeními o aktualizaci a kompletním načtením je nutné zajistit následující tok:

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

The device app can ignore all notifications with $version less or equal than the version of the full retrieved document. Tento přístup je možný, protože IoT Hub zaručuje, že verze se vždy zvyšují.

Další kroky

Pokud si chcete vyzkoušet některé koncepty popsané v tomto článku, přečtěte si následující články o službě IoT Hub:

• Kurz: Konfigurace zařízení pomocí vlastností dvojčete zařízení
• Jak používat digitální dvojčata