Verstehen und Verwenden von Gerätezwillingen in IoT HubUnderstand and use device twins in IoT Hub

Gerätezwillinge sind JSON-Dokumente, in denen Gerätestatusinformationen gespeichert werden, einschließlich Metadaten, Konfigurationen und Bedingungen.Device twins are JSON documents that store device state information including metadata, configurations, and conditions. Azure IoT Hub pflegt einen Gerätezwilling für jedes Gerät, das Sie mit IoT Hub verbinden.Azure IoT Hub maintains a device twin for each device that you connect to IoT Hub.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung.The features described in this article are available only in the standard tier of IoT Hub. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier.

Dieser Artikel beschreibt Folgendes:This article describes:

  • Die Struktur des Gerätezwillings: Tags, gewünschte Eigenschaften und gemeldete Eigenschaften.The structure of the device twin: tags, desired and reported properties.
  • Die Vorgänge, die Geräte-Apps und Back-Ends auf Gerätezwillingen ausführen könnenThe operations that device apps and back ends can perform on device twins.

Verwenden Sie Gerätezwillinge für Folgendes:Use device twins to:

  • Speichern gerätespezifischer Metadaten in der Cloud –Store device-specific metadata in the cloud. beispielsweise den Aufstellungsort eines Automaten.For example, the deployment location of a vending machine.

  • Melden aktueller Zustandsinformationen – beispielsweise verfügbare Funktionen und Bedingungen aus Ihrer Geräte-App.Report current state information such as available capabilities and conditions from your device app. Beispiel: Ein Gerät ist per Mobilfunk oder WLAN mit Ihrem IoT Hub verbunden.For example, a device is connected to your IoT hub over cellular or WiFi.

  • Synchronisieren des Zustands von Workflows mit langer Ausführungsdauer zwischen Geräte-App und Back-End-App.Synchronize the state of long-running workflows between device app and 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.For example, when the solution back end specifies the new firmware version to install, and the device app reports the various stages of the update process.

  • Abfragen von Metadaten, Konfiguration oder Status des GerätsQuery your device metadata, configuration, or state.

Weitere Informationen zur Verwendung von gemeldeten Eigenschaften, D2C-Nachrichten und Dateiuploads finden Sie bei Bedarf im Leitfaden zur D2C-Kommunikation.Refer to Device-to-cloud communication guidance for guidance on using reported properties, device-to-cloud messages, or file upload.

Weitere Informationen zu gewünschten Eigenschaften, direkten Methoden und C2D-Nachrichten finden Sie im Leitfaden zur C2D-Kommunikation.Refer to Cloud-to-device communication guidance for guidance on using desired properties, direct methods, or cloud-to-device messages.

GerätezwillingeDevice twins

Auf Gerätezwillingen werden gerätespezifische Informationen gespeichert, auf die Folgendes zutrifft:Device twins store device-related information that:

  • Geräte und Back-Ends können mit ihnen Gerätezustände und -konfigurationen synchronisieren.Device and back ends can use to synchronize device conditions and configuration.

  • Das Lösungs-Back-End kann mit ihnen lang andauernde Vorgänge abfragen und als Ziel verwenden.The solution back end can use to query and target long-running operations.

Der Lebenszyklus eines Gerätezwillings ist mit der entsprechenden Geräteidentität verknüpft.The lifecycle of a device twin is linked to the corresponding device identity. Gerätezwillinge werden implizit erstellt und gelöscht, wenn in IoT Hub eine Geräteidentität erstellt oder gelöscht wird.Device twins are implicitly created and deleted when a device identity is created or deleted in IoT Hub.

Ein Gerätezwilling ist ein JSON-Dokument, das Folgendes enthält:A device twin is a JSON document that includes:

  • Tags:Tags. Ein Abschnitt des JSON-Dokuments, in dem das Lösungs-Back-End Lese- und Schreibvorgänge ausführen kann.A section of the JSON document that the solution back end can read from and write to. Tags sind für Geräte-Apps nicht sichtbar.Tags are not visible to device apps.

  • Gewünschte Eigenschaften:Desired properties. Werden in Verbindung mit gemeldeten Eigenschaften zum Synchronisieren von Gerätekonfigurationen oder -zuständen verwendet.Used along with reported properties to synchronize device configuration or conditions. Das Lösungs-Back-End kann gewünschte Eigenschaften festlegen, die von der Geräte-App gelesen werden können.The solution back end can set desired properties, and the device app can read them. Die Geräte-App kann auch Benachrichtigungen über Änderungen an den gewünschten Eigenschaften erhalten.The device app can also receive notifications of changes in the desired properties.

  • Gemeldete EigenschaftenReported properties. Werden in Verbindung mit gewünschten Eigenschaften zum Synchronisieren von Gerätekonfigurationen oder -zuständen verwendet.Used along with desired properties to synchronize device configuration or conditions. Die Geräte-App kann gemeldete Eigenschaften festlegen, die vom Lösungs-Back-End gelesen und abgefragt werden können.The device app can set reported properties, and the solution back end can read and query them.

  • Geräteidentitätseigenschaften.Device identity properties. 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.The root of the device twin JSON document contains the read-only properties from the corresponding device identity stored in the identity registry.

Screenshot: Eigenschaften von Gerätezwillingen

Das folgende Beispiel zeigt das JSON-Dokument für einen Gerätezwilling: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": {
        "$etag": "123",
        "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 befinden sich die Geräteidentitätseigenschaften und Containerobjekte für tags sowie die reported- und desired-Eigenschaften.In the root object are the device identity properties, and container objects for tags and both reported and desired properties. Der Container properties enthält einige schreibgeschützte Elemente ($metadata, $etag und $version), die in den Abschnitten zu den Metadaten des Gerätezwillings und zur optimistischen Nebenläufigkeit beschrieben sind.The properties container contains some read-only elements ($metadata, $etag, and $version) described in the Device twin metadata and Optimistic concurrency sections.

Beispiel für eine gemeldete EigenschaftReported property example

Im vorherigen Beispiel enthält der Gerätezwilling eine batteryLevel-Eigenschaft, die von der Geräte-App gemeldet wird.In the previous example, the device twin contains a batteryLevel property that is reported by the device app. Mit dieser Eigenschaft können Geräte anhand des letzten gemeldeten Akkustands abgefragt und Aktionen auf ihnen ausgeführt werden.This property makes it possible to query and operate on devices based on the last reported battery level. Ein weiteres Beispiel wäre das Melden von Gerätefunktionen oder Verbindungsoptionen durch das Gerät.Other examples include the device app reporting device capabilities or connectivity options.

Hinweis

Gemeldete Eigenschaften tragen zur Vereinfachung von Szenarien bei, in denen das Lösungs-Back-End den letzten bekannten Wert einer Eigenschaft abfragen soll.Reported properties simplify scenarios where the solution back end is interested in the last known value of a property. Verwenden Sie Gerät-zu-Cloud-Nachrichten, wenn das Lösungs-Back-End Gerätetelemetriedaten in Form von Folgen von Ereignissen mit Zeitstempeln abfragen muss, beispielsweise als Zeitreihe.Use device-to-cloud messages if the solution back end needs to process device telemetry in the form of sequences of timestamped events, such as time series.

Beispiel für eine gewünschte EigenschaftDesired property example

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.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. Beispiel:For example:

  1. Das Lösungs-Back-End legt die gewünschte Eigenschaft mit dem gewünschten Konfigurationswert fest.The solution back end sets the desired property with the desired configuration value. Hier sehen Sie den Teil des Dokuments mit der festgelegten gewünschten Eigenschaft:Here is the portion of the document with the desired property set:

    "desired": {
        "telemetryConfig": {
            "sendFrequency": "5m"
        },
        ...
    },
    
  2. Die Geräte-App wird sofort über die Änderung benachrichtigt, wenn sie verbunden ist oder später eine Verbindung herstellt.The device app is notified of the change immediately if connected, or at the first reconnect. Anschließend meldet die Geräte-App die aktualisierte Konfiguration (oder einen Fehler über die status-Eigenschaft).The device app then reports the updated configuration (or an error condition using the status property). Dies ist der Teil mit den gemeldeten Eigenschaften:Here is the portion of the reported properties:

    "reported": {
        "telemetryConfig": {
            "sendFrequency": "5m",
            "status": "success"
        }
        ...
    }
    
  3. Das Lösungs-Back-End kann die Ergebnisse des Konfigurationsvorgangs auf vielen Geräten durch Abfragen von Gerätezwillingen nachverfolgen.The solution back end can track the results of the configuration operation across many devices by querying device twins.

Hinweis

Die obigen Codeausschnitte sind Beispiele mit optimierter Lesbarkeit und stellen eine Möglichkeit zum Codieren einer Konfiguration und des Status eines Geräts dar.The preceding snippets are examples, optimized for readability, of one way to encode a device configuration and its status. IoT Hub setzt kein bestimmtes Schema für die gewünschten und gemeldeten Eigenschaften in den Gerätezwillingen voraus.IoT Hub does not impose a specific schema for the device twin desired and reported properties in the device twins.

Mithilfe von Zwillingen können Sie Vorgänge mit langer Ausführungsdauer (beispielsweise Firmwareupdates) synchronisieren.You can use twins to synchronize long-running operations such as firmware updates. 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.For more information on how to use properties to synchronize and track a long running operation across devices, see Use desired properties to configure devices.

Back-End-VorgängeBack-end operations

Das Lösungs-Back-End greift mithilfe folgender atomischer Vorgänge, die über HTTPS verfügbar gemacht werden, auf den Gerätezwilling zu:The solution back end operates on the device twin using the following atomic operations, exposed through HTTPS:

  • Abrufen des Gerätezwillings mittels ID.Retrieve device twin by ID. Dieser Vorgang gibt das Dokument für den Gerätezwilling zurück – einschließlich Tags sowie gewünschter und gemeldeter Systemeigenschaften.This operation returns the device twin document, including tags and desired and reported system properties.

  • Partielles Aktualisieren des Gerätezwillings.Partially update device twin. Dieser Vorgang ermöglicht es dem Lösungs-Back-End, die Tags oder gewünschten Eigenschaften in einem Gerätezwilling teilweise zu aktualisieren.This operation enables the solution back end to partially update the tags or desired properties in a device twin. Bei der partiellen Aktualisierung handelt es sich um ein JSON-Dokument, das eine beliebige Eigenschaft hinzufügt oder aktualisiert.The partial update is expressed as a JSON document that adds or updates any property. Auf null festgelegte Eigenschaften werden entfernt.Properties set to null are removed. 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.The following example creates a new desired property with value {"newProperty": "newValue"}, overwrites the existing value of existingProperty with "otherNewValue", and removes otherOldProperty. Ansonsten werden an vorhandenen Eigenschaften oder Tags keine weiteren Änderungen vorgenommen:No other changes are made to existing desired properties or tags:

    {
         "properties": {
             "desired": {
                 "newProperty": {
                     "nestedProperty": "newValue"
                 },
                 "existingProperty": "otherNewValue",
                 "otherOldProperty": null
             }
         }
    }
    
  • Ersetzen gewünschter Eigenschaften.Replace desired properties. 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.This operation enables the solution back end to completely overwrite all existing desired properties and substitute a new JSON document for properties/desired.

  • Ersetzen von Tags.Replace 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.This operation enables the solution back end to completely overwrite all existing tags and substitute a new JSON document for tags.

  • Zwillingsbenachrichtigungen empfangen.Receive twin notifications. Mit diesem Vorgang kann das Lösungs-Back-End benachrichtigt werden, wenn der Zwilling geändert wird.This operation allows the solution back end to be notified when the twin is modified. Zu diesem Zweck muss Ihre IoT-Lösung eine Route erstellen die Datenquelle auf twinChangeEvents festlegen.To do so, your IoT solution needs to create a route and to set the Data Source equal to twinChangeEvents. Standardmäßig existieren keine solchen Routen, daher werden keine Zwillingsbenachrichtigungen gesendet.By default, no such routes pre-exist, so no twin notifications are sent. 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.If the rate of change is too high, or for other reasons such as internal failures, the IoT Hub might send only one notification that contains all changes. Wenn Ihre Anwendung zuverlässige Prüfungen und Protokolle aller Zwischenzustände benötigt, sollten Sie D2C-Nachrichten verwenden.Therefore, if your application needs reliable auditing and logging of all intermediate states, you should use device-to-cloud messages. Die Zwillingsbenachrichtung umfasst Eigenschaften und einen Textkörper.The twin notification message includes properties and body.

    • EigenschaftenProperties

      NAMEName WertValue
      $content-type$content-type Anwendung/jsonapplication/json
      $iothub-enqueuedtime$iothub-enqueuedtime Uhrzeit, zu der die Benachrichtigung gesendet wurdeTime when the notification was sent
      $iothub-message-source$iothub-message-source twinChangeEventstwinChangeEvents
      $content-encoding$content-encoding UTF-8utf-8
      deviceIddeviceId ID des GerätsID of the device
      hubNamehubName Name des IoT HubName of IoT Hub
      operationTimestampoperationTimestamp ISO8601-Zeitstempel des VorgangsISO8601 timestamp of operation
      iothub-message-schemaiothub-message-schema twinChangeNotificationtwinChangeNotification
      opTypeopType "replaceTwin" oder "updateTwin""replaceTwin" or "updateTwin"

      Nachrichtensystemeigenschaften ist das Symbol $ vorangestellt.Message system properties are prefixed with the $ symbol.

    • BodyBody

      Dieser Abschnitt enthält alle Zwillingsänderungen in einem JSON-Format.This section includes all the twin changes in a JSON format. Er verwendet das gleiche Format wie ein Patch, jedoch mit dem Unterschied, dass alle Zwillingsabschnitte enthalten sein können (Tags, properties.reported, properties.desired) und dass die $metadata-Elemente enthalten sind.It uses the same format as a patch, with the difference that it can contain all twin sections: tags, properties.reported, properties.desired, and that it contains the “$metadata” elements. Beispiel:For example,

      {
        "properties": {
            "desired": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            },
            "reported": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            }
        }
      }
      

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.All the preceding operations support Optimistic concurrency and require the ServiceConnect permission, as defined in Control access to IoT Hub.

Neben diesen Vorgängen kann das Lösungs-Back-End auch folgende Aktionen ausführen:In addition to these operations, the solution back end can:

  • Abfragen der Gerätezwillinge mithilfe der SQL-ähnlichen IoT Hub-AbfragespracheQuery the device twins using the SQL-like IoT Hub query language.

  • Ausführen von Vorgängen für große Mengen von Gerätezwillingen mithilfe von AufträgenPerform operations on large sets of device twins using jobs.

GerätevorgängeDevice operations

Die Geräte-App greift mithilfe folgender atomarer Vorgänge auf den Gerätezwilling zu:The device app operates on the device twin using the following atomic operations:

  • Abrufen des Gerätezwillings.Retrieve device twin. 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.This operation returns the device twin document (including desired and reported system properties) for the currently connected device. (Tags sind für Geräte-Apps nicht sichtbar.)(Tags are not visible to device apps.)

  • Teilweises Aktualisieren gemeldeter Eigenschaften.Partially update reported properties. Dieser Vorgang ermöglicht die teilweise Aktualisierung der gemeldeten Eigenschaften des derzeit verbundenen Geräts.This operation enables the partial update of the reported properties of the currently connected device. Dabei wird das gleiche JSON-Updateformat wie bei der partiellen Aktualisierung der gewünschten Eigenschaften durch das Lösungs-Back-End verwendet.This operation uses the same JSON update format that the solution back end uses for a partial update of desired properties.

  • Beobachten gewünschter Eigenschaften.Observe desired properties. Das derzeit verbundene Gerät kann benachrichtigt werden, sobald die gewünschten Eigenschaften aktualisiert werden.The currently connected device can choose to be notified of updates to the desired properties when they happen. 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.The device receives the same form of update (partial or full replacement) executed by the solution back end.

Alle oben genannten Vorgänge erfordern die Berechtigung DeviceConnect, wie im Artikel Steuern des Zugriffs auf IoT Hub definiert.All the preceding operations require the DeviceConnect permission, as defined in Control Access to IoT Hub.

Die Azure IoT-Geräte-SDKs vereinfachen die Verwendung der oben beschriebenen Vorgänge, die mit vielen Sprachen und Plattformen erstellt wurden.The Azure IoT device SDKs make it easy to use the preceding operations from many languages and platforms. 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.For more information on the details of IoT Hub primitives for desired properties synchronization, see Device reconnection flow.

Format von Tags und EigenschaftenTags and properties format

Tags, gewünschte Eigenschaften und gemeldete Eigenschaften sind JSON-Objekte mit den folgenden Einschränkungen:Tags, desired properties, and reported properties are JSON objects with the following restrictions:

  • 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.All keys in JSON objects are UTF-8 encoded, case-sensitive, and up-to 1 KB in length. UNICODE-Steuerzeichen (Segmente C0 und C1) sowie ., $ und „SP“ gehören nicht zu den zulässigen Zeichen.Allowed characters exclude UNICODE control characters (segments C0 and C1), and ., $, and SP.

  • Alle Werte in JSON-Objekten können die folgenden JSON-Typen aufweisen: boolescher Wert, Zahl, Zeichenfolge, Objekt.All values in JSON objects can be of the following JSON types: boolean, number, string, object. Arrays sind nicht zulässig.Arrays are not allowed. Der maximale Wert für ganze Zahlen ist 4503599627370495 und der minimale Wert für ganze Zahlen ist -4503599627370496.The maximum value for integers is 4503599627370495 and the minimum value for integers is -4503599627370496.

  • Alle JSON-Objekte in Tags, gewünschten und gemeldeten Eigenschaften können eine maximale Tiefe von 10 haben.All JSON objects in tags, desired, and reported properties can have a maximum depth of 10. Das folgende Objekt ist z.B. gültig:For instance, the following object is valid:

    {
         ...
         "tags": {
             "one": {
                 "two": {
                     "three": {
                         "four": {
                             "five": {
                                 "six": {
                                     "seven": {
                                         "eight": {
                                             "nine": {
                                                 "ten": {
                                                     "property": "value"
                                                 }
                                             }
                                         }
                                     }
                                 }
                             }
                         }
                     }
                 }
             }
         },
         ...
    }
    
  • Alle Zeichenfolgenwerte können höchstens 4 KB lang sein.All string values can be at most 4 KB in length.

Größe des GerätezwillingsDevice twin size

IoT Hub erzwingt eine Größenbeschränkung von 8 KB für den Wert tags und eine Größenbeschränkung von jeweils 32 KB für die Werte properties/desired und properties/reported.IoT Hub enforces an 8 KB size limit on the value of tags, and a 32 KB size limit each on the value of properties/desired and properties/reported. Diese Summen schließen keine schreibgeschützten Elemente ein.These totals are exclusive of read-only elements.

Die Größe wird durch Zusammenzählen aller Zeichen mit Ausnahme von UNICODE-Steuerzeichen (Segmente C0 und C1) und Leerzeichen außerhalb von Zeichenfolgenkonstanten berechnet.The size is computed by counting all characters, excluding UNICODE control characters (segments C0 and C1) and spaces that are outside of string constants.

IoT Hub gibt für alle Vorgänge, die die Größe dieser Dokumente über den Grenzwert hinaus erhöhen würden, einen Fehler zurück.IoT Hub rejects with an error all operations that would increase the size of those documents above the limit.

Metadaten des GerätezwillingsDevice twin metadata

IoT Hub verwaltet den Zeitstempel der letzten Aktualisierung für jedes JSON-Objekt in den gewünschten und gemeldeten Eigenschaften des Gerätezwillings.IoT Hub maintains the timestamp of the last update for each JSON object in device twin desired and reported properties. Zeitstempel verwenden UTC und sind im ISO8601-Format codiert: YYYY-MM-DDTHH:MM:SS.mmmZ.The timestamps are in UTC and encoded in the ISO8601 format YYYY-MM-DDTHH:MM:SS.mmmZ.

Beispiel:For example:

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

Diese Informationen werden auf jeder Ebene (nicht nur die Zweige der JSON-Struktur) gespeichert, um Aktualisierungen beizubehalten, bei denen Objektschlüssel entfernt werden.This information is kept at every level (not just the leaves of the JSON structure) to preserve updates that remove object keys.

Optimistische ParallelitätOptimistic concurrency

Tags sowie gewünschte und gemeldete Eigenschaften unterstützen optimistische Parallelität.Tags, desired, and reported properties all support optimistic concurrency. Tags verfügen über ein ETag (gemäß RFC7232), das der JSON-Darstellung des Tags entspricht.Tags have an ETag, as per RFC7232, that represents the tag's JSON representation. ETags können bei bedingten Aktualisierungsvorgängen über das Lösungs-Back-End verwendet werden, um die Konsistenz zu gewährleisten.You can use ETags in conditional update operations from the solution back end to ensure consistency.

Gewünschte und gemeldete Eigenschaften des Gerätezwillings verfügen zwar über keine ETags, aber über einen garantiert inkrementellen $version-Wert.Device twin desired and reported properties do not have ETags, but have a $version value that is guaranteed to be incremental. Zur Gewährleistung der Konsistenz von Updates kann von der aktualisierenden Partei die Version genutzt werden (ähnlich wie ein ETag).Similarly to an ETag, the version can be used by the updating party to enforce consistency of updates. 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.For example, a device app for a reported property or the solution back end for a desired property.

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.Versions are also useful when an observing agent (such as the device app observing the desired properties) must reconcile races between the result of a retrieve operation and an update notification. Im Abschnitt Ablauf zur Wiederherstellung der Geräteverbindung finden Sie weitere Informationen.The Device reconnection flow section provides more information.

Ablauf zur Wiederherstellung der GeräteverbindungDevice reconnection flow

IoT Hub behält keine Aktualisierungsbenachrichtigungen für gewünschte Eigenschaften für nicht verbundene Geräte bei.IoT Hub does not preserve desired properties update notifications for disconnected devices. Ein Gerät, das eine Verbindung herstellt, muss daher zusätzlich zum Abonnieren von Aktualisierungsbenachrichtigungen das gesamte Dokument der gewünschten Eigenschaften abrufen.It follows that a device that is connecting must retrieve the full desired properties document, in addition to subscribing for update notifications. Wenn die Gefahr von Racebedingungen zwischen Aktualisierungsbenachrichtigungen und dem vollständigen Abruf besteht, muss der folgende Ablauf sichergestellt werden:Given the possibility of races between update notifications and full retrieval, the following flow must be ensured:

  1. Geräte-App stellt eine Verbindung mit einem IoT Hub her.Device app connects to an IoT hub.
  2. Geräte-App abonniert Aktualisierungsbenachrichtigungen für gewünschte Eigenschaften.Device app subscribes for desired properties update notifications.
  3. Geräte-App ruft das vollständige Dokument für gewünschte Eigenschaften ab.Device app retrieves the full document for desired properties.

Die Geräte-App kann alle Benachrichtigungen ignorieren, bei denen $version kleiner oder gleich der Version des vollständigen abgerufenen Dokuments ist.The device app can ignore all notifications with $version less or equal than the version of the full retrieved document. Diese Herangehensweise ist möglich, da IoT Hub sicherstellt, dass die Versionsnummern immer erhöht werden.This approach is possible because IoT Hub guarantees that versions always increment.

Hinweis

Diese Logik ist in den Azure IoT-Geräte-SDKs bereits implementiert.This logic is already implemented in the Azure IoT device SDKs. Diese Beschreibung ist nur dann nützlich, wenn die Geräte-App keine der Azure IoT-Geräte-SDKs verwenden kann und die MQTT-Schnittstelle direkt programmiert werden muss.This description is useful only if the device app cannot use any of Azure IoT device SDKs and must program the MQTT interface directly.

Weiteres ReferenzmaterialAdditional reference material

Weitere Referenzthemen im IoT Hub-Entwicklerhandbuch:Other reference topics in the IoT Hub developer guide include:

Nächste SchritteNext steps

Nachdem Sie nun etwas über Gerätezwillinge erfahren haben, sind möglicherweise die folgenden Themen aus dem IoT Hub-Entwicklerhandbuch für Sie interessant:Now you have learned about device twins, you may be interested in the following IoT Hub developer guide topics:

Um einige der in diesem Artikel beschriebenen Konzepte auszuprobieren, sehen Sie sich die folgenden IoT Hub-Tutorials an:To try out some of the concepts described in this article, see the following IoT Hub tutorials: