Verstehen und Verwenden von Gerätezwillingen in IoT Hub

Gerätezwillinge sind JSON-Dokumente, in denen Gerätestatusinformationen gespeichert werden, einschließlich Metadaten, Konfigurationen und Bedingungen. Azure IoT Hub pflegt einen Gerätezwilling für jedes Gerät, das Sie mit IoT Hub verbinden.

Dieser Artikel beschreibt Folgendes:

• Die Struktur des Gerätezwillings: Tags, gewünschte Eigenschaften und gemeldete Eigenschaften.
• Die Vorgänge, die Geräte- und Back-End-Anwendungen auf Gerätezwillingen ausführen können.

Verwenden Sie Gerätezwillinge für Folgendes:

• Speichern gerätespezifischer Metadaten in der Cloud – Ein Beispiel ist der Standort eines Automaten.

• Melden aktueller Zustandsinformationen – beispielsweise verfügbare Funktionen und Bedingungen aus Ihrer Geräte-App. Oder beispielsweise, ob ein Gerät per Mobilfunk oder WLAN mit Ihrem IoT-Hub verbunden ist.

• Synchronisieren des Zustands von Workflows mit langer Ausführungsdauer zwischen Geräte-App und Back-End-App. Beispielsweise wenn das Lösungs-Back-End die neu zu installierende Firmwareversion angibt und die Geräte-App die verschiedenen Phasen des Aktualisierungsvorgangs meldet.

• Abfragen von Metadaten, Konfiguration oder Status des Geräts

Weitere Informationen zur Verwendung von gemeldeten Eigenschaften, D2C-Nachrichten oder Dateiupload finden Sie unter Leitfaden zur D2C-Kommunikation.

Weitere Informationen zur Verwendung von gewünschten Eigenschaften, direkten Methoden oder C2D-Nachrichten finden Sie im Leitfaden zur C2D-Kommunikation.

Informationen über das Verhältnis von Gerätezwillingen zu dem Gerätemodell, das von einem Azure IoT Plug & Play-Gerät verwendet wird, finden Sie unter Grundlegendes zu digitalen IoT Plug & Play-Zwillingen.

Gerätezwillinge

Auf Gerätezwillingen werden gerätespezifische Informationen gespeichert, auf die Folgendes zutrifft:

• Geräte und Back-Ends können mit ihnen Gerätezustände und -konfigurationen synchronisieren.

• Das Lösungs-Back-End kann mit ihnen lang andauernde Vorgänge abfragen und als Ziel verwenden.

Der Lebenszyklus eines Gerätezwillings ist mit seiner Geräteidentität verknüpft. Gerätezwillinge werden implizit erstellt und gelöscht, wenn in IoT Hub eine Geräteidentität erstellt oder gelöscht wird.

Ein Gerätezwilling ist ein JSON-Dokument, das Folgendes enthält:

• Tags. Ein Abschnitt des JSON-Dokuments, in dem das Lösungs-Back-End Lese- und Schreibvorgänge ausführen kann. Tags sind für Geräte-Apps nicht sichtbar.

• Gewünschte Eigenschaften Werden in Verbindung mit gemeldeten Eigenschaften zum Synchronisieren von Gerätekonfigurationen oder -zuständen verwendet. Das Lösungs-Back-End kann gewünschte Eigenschaften festlegen, die von der Geräte-App gelesen werden können. Die Geräte-App kann auch Benachrichtigungen über Änderungen an den gewünschten Eigenschaften erhalten.

• Gemeldete Eigenschaften Werden in Verbindung mit gewünschten Eigenschaften zum Synchronisieren von Gerätekonfigurationen oder -zuständen verwendet. Die Geräte-App kann gemeldete Eigenschaften festlegen, die vom Lösungs-Back-End gelesen und abgefragt werden können.

• Geräteidentitätseigenschaften. Der Stamm des JSON-Dokuments für einen Gerätezwilling enthält die schreibgeschützten Eigenschaften der zugehörigen Geräteidentität aus der Identitätsregistrierung. Die Eigenschaften connectionStateUpdatedTime und generationId sind nicht eingeschlossen.

Das folgende Beispiel zeigt das JSON-Dokument für einen Gerätezwilling:

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

Im Stammobjekt sind die Geräteidentitätseigenschaften und Containerobjekte für tags sowie die reported- und desired-Eigenschaft enthalten. Der Container properties enthält einige schreibgeschützte Elemente ($metadata und $version), die in den Abschnitten Metadaten des Gerätezwillings und Optimistische Parallelität beschrieben werden.

Beispiel für eine gemeldete Eigenschaft

Im vorherigen Beispiel enthält der Gerätezwilling eine batteryLevel-Eigenschaft, die von der Geräte-App gemeldet wird. Mit dieser Eigenschaft können Geräte anhand des letzten gemeldeten Akkustands abgefragt und Aktionen auf ihnen ausgeführt werden. Ein weiteres Beispiel wäre das Melden von Gerätefunktionen oder Verbindungsoptionen durch das Gerät.

Beispiel für eine gewünschte Eigenschaft

Im vorherigen Beispiel werden die gewünschten und gemeldeten Eigenschaften des telemetryConfig-Gerätezwillings vom Lösungs-Back-End und von der Geräte-App verwendet, um die Telemetriekonfiguration für dieses Gerät zu synchronisieren. Beispiel:

1. Das Lösungs-Back-End legt die gewünschte Eigenschaft mit dem gewünschten Konfigurationswert fest. Hier sehen Sie den Teil des Dokuments mit der festgelegten gewünschten Eigenschaft:

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

2. Die Geräte-App wird sofort über die Änderung benachrichtigt, wenn das Gerät verbunden ist. Wenn es nicht verbunden ist, folgt die Geräte-App beim Herstellen der Verbindung dem Ablauf zur Wiederherstellung der Geräteverbindung. Anschließend meldet die Geräte-App die aktualisierte Konfiguration (oder einen Fehler über die status-Eigenschaft). Dies ist der Teil mit den gemeldeten Eigenschaften:

   "reported": {
       "telemetryConfig": {
           "sendFrequency": "5m",
           "status": "success"
       }
       ...
   }
   

3. Das Lösungs-Back-End verfolgt die Ergebnisse des Konfigurationsvorgangs auf vielen Geräten durch Abfragen von Gerätezwillingen nach.

Mithilfe von Zwillingen können Sie Vorgänge mit langer Ausführungsdauer (beispielsweise Firmwareupdates) synchronisieren. Weitere Informationen zur Verwendung von Eigenschaften zum geräteübergreifenden Synchronisieren und Verfolgen von Vorgängen mit langer Ausführungsdauer finden Sie unter Verwenden von gewünschten Eigenschaften zum Konfigurieren von Geräten.

Back-End-Vorgänge

Das Lösungs-Back-End greift mithilfe folgender atomischer Vorgänge, die über HTTPS verfügbar gemacht werden, auf den Gerätezwilling zu:

• Abrufen des Gerätezwillings mittels ID. Dieser Vorgang gibt das Dokument für den Gerätezwilling zurück – einschließlich Tags sowie gewünschter und gemeldeter Systemeigenschaften.

• Partielles Aktualisieren des Gerätezwillings. Dieser Vorgang ermöglicht es dem Lösungs-Back-End, die Tags oder gewünschten Eigenschaften in einem Gerätezwilling teilweise zu aktualisieren. Bei der partiellen Aktualisierung handelt es sich um ein JSON-Dokument, das eine beliebige Eigenschaft hinzufügt oder aktualisiert. Auf null festgelegte Eigenschaften werden entfernt. Im folgenden Beispiel wird eine neue gewünschte Eigenschaft mit dem Wert {"newProperty": "newValue"} erstellt, der vorhandene Wert von existingProperty wird mit "otherNewValue" überschrieben, und otherOldProperty wird entfernt. Ansonsten werden an vorhandenen Eigenschaften oder Tags keine weiteren Änderungen vorgenommen:

  {
       "properties": {
           "desired": {
               "newProperty": {
                   "nestedProperty": "newValue"
               },
               "existingProperty": "otherNewValue",
               "otherOldProperty": null
           }
       }
  }
  

• Ersetzen gewünschter Eigenschaften. Dieser Vorgang ermöglicht dem Lösungs-Back-End, alle vorhandenen gewünschten Eigenschaften vollständig zu überschreiben und ein neues JSON-Dokument für properties/desired bereitzustellen.

• Ersetzen von Tags. Dieser Vorgang ermöglicht es dem Lösungs-Back-End, alle vorhandenen Tags vollständig zu überschreiben und ein neues JSON-Dokument für tags bereitzustellen.

• Zwillingsbenachrichtigungen empfangen. Mit diesem Vorgang kann das Lösungs-Back-End benachrichtigt werden, wenn der Zwilling geändert wird. Zu diesem Zweck muss Ihre IoT-Lösung eine Route erstellen die Datenquelle auf twinChangeEvents festlegen. Weil es solche Routen standardmäßig nicht gibt, werden keine Zwillingsbenachrichtigungen gesendet. Wenn die Änderungsrate zu hoch ist, oder andere Gründe wie interne Fehler vorliegen, sendet der IoT Hub möglicherweise nur eine Benachrichtigung, die alle Änderungen enthält. Wenn Ihre Anwendung zuverlässige Prüfungen und Protokolle aller Zwischenzustände benötigt, sollten Sie D2C-Nachrichten verwenden. Weitere Informationen zu den Eigenschaften und den Texten, die in der Zwillingsbenachrichtigungsmeldung zurückgegeben werden, finden Sie unter Schemas für nicht telemetriebezogene Ereignisse.

Alle oben genannten Vorgänge unterstützen die optimistische Nebenläufigkeit und erfordern die Berechtigung ServiceConnect, wie im Artikel Steuern des Zugriffs auf IoT Hub definiert.

Neben diesen Vorgängen kann das Lösungs-Back-End auch folgende Aktionen ausführen:

• Abfragen der Gerätezwillinge mithilfe der SQL-ähnlichen IoT Hub-Abfragesprache

• Ausführen von Vorgängen für große Mengen von Gerätezwillingen mithilfe von Aufträgen

Gerätevorgänge

Die Geräte-App greift mithilfe folgender atomarer Vorgänge auf den Gerätezwilling zu:

• Abrufen des Gerätezwillings. Dieser Vorgang gibt das Dokument für den Gerätezwilling (einschließlich gewünschter und gemeldeter Systemeigenschaften) für das derzeit verbundene Gerät zurück. (Tags sind für Geräte-Apps nicht sichtbar.)

• Teilweises Aktualisieren gemeldeter Eigenschaften. Dieser Vorgang ermöglicht die teilweise Aktualisierung der gemeldeten Eigenschaften des derzeit verbundenen Geräts. Dabei wird das gleiche JSON-Updateformat wie bei der partiellen Aktualisierung der gewünschten Eigenschaften durch das Lösungs-Back-End verwendet.

• Beobachten gewünschter Eigenschaften. Das derzeit verbundene Gerät kann benachrichtigt werden, sobald die gewünschten Eigenschaften aktualisiert werden. Das Gerät erhält die gleiche Form der Aktualisierung (partielle oder vollständige Ersetzung), die durch das Lösungs-Back-End ausgeführt wird.

Alle oben genannten Vorgänge erfordern die Berechtigung DeviceConnect, wie im Artikel Steuern des Zugriffs auf IoT Hub definiert.

Die Azure IoT-Geräte-SDKs vereinfachen die Verwendung der oben beschriebenen Vorgänge, die mit vielen Sprachen und Plattformen erstellt wurden. Weitere Informationen zu den Details der IoT Hub-Grundtypen für die Synchronisierung gewünschter Eigenschaften finden Sie im Ablauf zur Wiederherstellung der Geräteverbindung.

Format von Tags und Eigenschaften

Tags, gewünschte Eigenschaften und gemeldete Eigenschaften sind JSON-Objekte mit den folgenden Einschränkungen:

• Schlüssel: Alle Schlüssel in JSON-Objekten sind UTF-8-codiert, die Groß-/Kleinschreibung muss beachtet werden, und ihre Länge beträgt bis zu 1 KB. UNICODE-Steuerzeichen (Segmente C0 und C1) sowie ., $ und „SP“ gehören nicht zu den zulässigen Zeichen.

  Hinweis

  IoT Hub-Abfragen, die beim Nachrichtenrouting verwendet werden, unterstützen keine Leerzeichen und keins der folgenden Zeichen als Teil eines Schlüsselnamens: ()<>@,;:\"/?={}.

• Werte: Alle Werte in JSON-Objekten können die folgenden JSON-Typen aufweisen: boolescher Wert, Zahl, Zeichenfolge, Objekt. Arrays werden ebenfalls unterstützt.

  • Ganze Zahlen können den Minimalwert „-4503599627370496“ und den Maximalwert „4503599627370495“ haben.

  • Zeichenfolgenwerte sind UTF-8-codiert und können eine maximale Länge von 4 Bytes haben.

• Tiefe: Die maximale Tiefe von JSON-Objekten in Tags, gewünschten Eigenschaften und gemeldeten Eigenschaften ist „10“. Das folgende Objekt beispielsweise ist gültig:

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

Größe des Gerätezwillings

IoT Hub erzwingt eine Größenbeschränkung von 8 KB auf den Wert von tags und eine Größenbeschränkung von jeweils 32 KB auf die Werte von properties/desired und properties/reported. In diesen Summen sind keine schreibgeschützten Elemente wie $version und $metadata/$lastUpdated enthalten.

Die Größe von Zwillingen wird folgendermaßen berechnet:

• Für jede Eigenschaft im JSON-Dokument berechnet IoT Hub kumulativ und addiert die Länge des Eigenschaftenschlüssels und Eigenschaftswerts.

• Eigenschaftenschlüssel werden als UTF8-codierte Zeichenfolgen betrachtet.

• Einfache Eigenschaftswerte werden als UTF8-codierte Zeichenfolgen, numerische Werte (8 Bytes) oder boolesche Werte (4 Bytes) betrachtet.

• Die Größe der UTF8-codierten Zeichenfolgen wird berechnet, indem alle Zeichen gezählt werden – ausgenommen UNICODE-Steuerzeichen (Segmente C0 und C1).

• Komplexe Eigenschaftswerte (geschachtelte Objekte) werden basierend auf der Aggregatgröße der darin enthaltenen Eigenschaftenschlüssel und Eigenschaftswerte berechnet.

IoT Hub gibt für alle Vorgänge, die die Größe der Dokumente tags, properties/desired und properties/reported über den Grenzwert hinaus erhöhen würden, einen Fehler zurück.

Metadaten des Gerätezwillings

IoT Hub verwaltet den Zeitstempel der letzten Aktualisierung für jedes JSON-Objekt in den gewünschten und gemeldeten Eigenschaften des Gerätezwillings. Zeitstempel verwenden UTC und sind im ISO8601-Format codiert: YYYY-MM-DDTHH:MM:SS.mmmZ.

Beispiel:

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

Diese Informationen werden auf jeder Ebene (nicht nur die Zweige der JSON-Struktur) gespeichert, um Aktualisierungen beizubehalten, bei denen Objektschlüssel entfernt werden.

Optimistische Parallelität

Tags, gewünschte Eigenschaften und gemeldete Eigenschaften unterstützen die optimistische Parallelität. Wenn Sie die Reihenfolge von Updates der Zwillingseigenschaften garantieren müssen, sollten Sie eine Synchronisierung auf Anwendungsebene implementieren, indem Sie auf den Rückruf von gemeldeten Eigenschaften warten, bevor Sie das nächste Update senden.

Gerätezwillinge haben eine ETag-Eigenschaft etag gemäß RFC7232, das für die JSON-Darstellung des Zwillings steht. Sie können die Eigenschaft etag bei bedingten Aktualisierungsvorgängen über das Lösungs-Back-End verwenden, um Konsistenz sicherzustellen. Diese Eigenschaft ist die einzige Option zur Sicherstellung der Konsistenz bei Vorgängen, die den Container tags umfassen.

Gewünschte und gemeldete Eigenschaften des Gerätezwillings enthalten außerdem einen $version-Wert, der garantiert inkrementell ist. Zur Gewährleistung der Konsistenz von Updates kann von der aktualisierenden Partei die Version genutzt werden (ähnlich wie ein ETag). Beispiele wären etwa eine Geräte-App für eine gemeldete Eigenschaft oder das Lösungs-Back-End für eine gewünschte Eigenschaft.

Versionen sind auch nützlich, wenn ein beobachtender Agent (beispielsweise die Geräte-App, die die gewünschten Eigenschaften beobachtet) Racebedingungen zwischen dem Ergebnis eines Abrufvorgangs und einer Aktualisierungsbenachrichtigung beheben muss. Im Abschnitt Ablauf zur Wiederherstellung der Geräteverbindung finden Sie weitere Informationen.

Ablauf zur Wiederherstellung der Geräteverbindung

IoT Hub behält keine Aktualisierungsbenachrichtigungen für gewünschte Eigenschaften für nicht verbundene Geräte bei. Ein Gerät, das eine Verbindung herstellt, muss daher zusätzlich zum Abonnieren von Aktualisierungsbenachrichtigungen das gesamte Dokument der gewünschten Eigenschaften abrufen. Wenn die Gefahr von Racebedingungen zwischen Aktualisierungsbenachrichtigungen und dem vollständigen Abruf besteht, muss der folgende Ablauf sichergestellt werden:

1. Geräte-App stellt eine Verbindung mit einem IoT Hub her.
2. Geräte-App abonniert Aktualisierungsbenachrichtigungen für gewünschte Eigenschaften.
3. Geräte-App ruft das vollständige Dokument für gewünschte Eigenschaften ab.

Die Geräte-App kann alle Benachrichtigungen ignorieren, bei denen $version kleiner oder gleich der Version des vollständigen abgerufenen Dokuments ist. Diese Herangehensweise ist möglich, da IoT Hub sicherstellt, dass die Versionsnummern immer erhöht werden.

Nächste Schritte

Um einige der in diesem Artikel beschriebenen Konzepte auszuprobieren, lesen Sie die folgenden IoT Hub-Artikel:

• Tutorial: Konfigurieren Ihrer Geräte mit Gerätezwillingseigenschaften
• Verwenden von Gerätezwillingen