Verstehen und Verwenden von Modulzwillingen in IoT Hub

In IoT Hub können unter jeder Geräteidentität bis zu 50 Modulidentitäten erstellt werden. Jede Modulidentität generiert implizit einen Modulzwilling. Modulzwillinge weisen Ähnlichkeiten mit Gerätezwillingen auf und stellen JSON-Dokumente dar, in denen Modulstatusinformationen wie Metadaten, Konfigurationen und Zustände gespeichert werden. Azure IoT Hub pflegt einen Modulzwilling für jedes Modul, das Sie mit IoT Hub verbinden.

Dieser Artikel setzt voraus, dass Sie zuerst Gerätezwillinge im IoT Hub verstehen und nutzen gelesen haben.

Auf der Geräteseite ermöglichen es die Software Development Kits (SDKs) für IoT Hub, Module zu erstellen, bei denen jedes Modul eine eigenständige Verbindung zum IoT Hub herstellt. Durch diese Funktionalität können Sie separate Namespaces für unterschiedliche Komponenten auf Ihrem Gerät verwenden. Ein Beispiel: Angenommen, Sie verfügen über einen Verkaufsautomaten mit drei verschiedene Sensoren. Unterschiedliche Abteilungen in Ihrem Unternehmen steuern jeden Sensor. Sie können ein Modul für jeden Sensor erstellen, sodass eine Abteilung nur Aufträge oder direkte Methoden an den Sensor senden kann, den sie steuern, wodurch Konflikte und Benutzerfehler vermieden werden.

Modulidentität und Modulzwilling bieten die gleichen Funktionen wie Geräteidentität und Gerätezwilling, aber mit einer höheren Granularität. Dank dieser höheren Granularität können geeignete Geräte (etwa betriebssystembasierte Geräte oder Firmwaregeräte, die mehrere Komponenten verwalten) Konfigurationen und Zustände für die einzelnen Komponenten isolieren. Modulidentität und Modulzwillinge ermöglichen die Trennung von Verwaltungszuständigkeiten bei Verwendung von IoT-Geräten mit modularen Softwarekomponenten. Wir arbeiten daran, bis zur allgemeinen Verfügbarkeit von Modulzwillingen alle Funktionen für Gerätezwillinge auf der Modulzwillingsebene zu unterstützen.

Dieser Artikel beschreibt Folgendes:

• Die Struktur des Modulzwillings: Tags, gewünschte Eigenschaften und gemeldete Eigenschaften.
• Die Vorgänge, die von Geräteanwendungen und dem Lösungs-Back-End an Modulzwillingen durchgeführt werden können.

Weitere Informationen zur Verwendung von gemeldeten Eigenschaften, D2C-Nachrichten und Dateiuploads finden Sie bei Bedarf im Leitfaden zur D2C-Kommunikation.

Weitere Informationen zu gewünschten Eigenschaften, direkten Methoden und C2D-Nachrichten finden Sie im Leitfaden zur C2D-Kommunikation.

Modulzwillinge

Modulzwillinge speichern modulspezifische Informationen, auf die Folgendes zutrifft:

• Module auf dem Gerät und IoT Hub können damit Modulzustände und -konfigurationen synchronisieren.

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

Der Lebenszyklus eines Modulzwillings ist mit der entsprechenden Modulidentität verknüpft. Modulzwillinge werden implizit erstellt und gelöscht, wenn in IoT Hub eine Modulidentität erstellt oder gelöscht wird.

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

• Tags. Ein Abschnitt des JSON-Dokuments, auf den Back-End-Anwendungen zugreifen und in den sie schreiben können. Tags sind für Module auf dem Gerät nicht sichtbar. Tags werden zu Abfragezwecken festgelegt.

• Gewünschte Eigenschaften Werden in Verbindung mit gemeldeten Eigenschaften zum Synchronisieren von Modulkonfigurationen oder -zuständen verwendet. Back-End-Anwendungen können gewünschte Eigenschaften festlegen, und die Modul-Anwendung kann sie lesen. Die Modul-App kann auch Benachrichtigungen über Änderungen an den gewünschten Eigenschaften erhalten.

• Gemeldete Eigenschaften Werden in Verbindung mit gewünschten Eigenschaften zum Synchronisieren von Modulkonfigurationen oder -zuständen verwendet. Die Modul-Anwendung kann gemeldete Eigenschaften festlegen, und Back-End-Anwendungen können sie lesen und abfragen.

• Modulidentitätseigenschaften: Der Stamm des JSON-Dokuments für einen Modulzwilling enthält die schreibgeschützten Eigenschaften der dazugehörigen Modulidentität aus der Identitätsregistrierung.

Das folgende Beispiel zeigt das JSON-Dokument für einen Modulzwilling:

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

Auf der obersten Ebene enthält ein Modulzwilling-Objekt die Modulidentitätseigenschaften sowie Containerobjekte für tags und sowohl reported als auch desired Eigenschaften. Der Container properties enthält einige schreibgeschützte Elemente ($metadata und $version), die weiter unten in den Abschnitten Metadaten des Modulzwillings und Optimistische Parallelität beschrieben werden.

Beispiel für eine gemeldete Eigenschaft

Im vorherigen Beispiel enthält der Modul twin eine batteryLevel gemeldete Eigenschaft. Mit dieser Eigenschaft können Module abgefragt und Aktionen auf der Grundlage des letzten gemeldeten Akkustands ausgeführt werden. Ein weiteres Beispiel wären von der Modul-App gemeldete Modulfunktionen oder Konnektivitätsoptionen.

Beispiel für eine gewünschte Eigenschaft

Im vorherigen Beispiel werden die gewünschten und gemeldeten Eigenschaften des telemetryConfig Modulzwillings von den Back-End-Anwendungen und der Modul-Anwendung verwendet, um die Telemetrie-Konfiguration für dieses Modul zu synchronisieren. Zum Beispiel:

1. Eine Back-End-Anwendung 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 Modul-App wird sofort über die Änderung benachrichtigt, wenn das Modul verbunden ist. Wenn es nicht verbunden ist, folgt die Modul-App beim Herstellen der Verbindung dem Ablauf zur Wiederherstellung der Modulverbindung. Anschließend meldet die Modul-App die aktualisierte Konfiguration (oder einen Fehler unter Verwendung der Eigenschaft status). Dies ist der Teil mit den gemeldeten Eigenschaften:

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

3. Eine Back-End-Anwendung kann die Ergebnisse der Konfigurationsoperation über viele Module hinweg verfolgen, indem sie Abfragen von Modulzwillingen durchführt.

Back-End-Vorgänge

Back-End-Anwendungen arbeiten mit dem Modulzwilling über die folgenden atomaren Operationen, die über HTTPS bereitgestellt werden:

• Abrufen des Modulzwillings anhand der ID: Dieser Vorgang gibt das Dokument für den Modulzwilling zurück (einschließlich Tags sowie gewünschter und gemeldeter Systemeigenschaften).

• Partielles Aktualisieren des Modulzwillings: Bei diesem Vorgang werden die Tags oder die gewünschten Eigenschaften in einem Modul twin teilweise aktualisiert. 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 überschreibt alle vorhandenen gewünschten Eigenschaften vollständig und ersetzt ein neues JSON-Dokument für properties/desired.

• Ersetzen von Tags. Dieser Vorgang überschreibt alle vorhandenen Tags vollständig und ersetzt ein neues JSON-Dokument für tags.

• Zwillingsbenachrichtigungen empfangen. Dieser Vorgang benachrichtigt, wenn der Zwilling geändert wird. Um Modul-Twin-Änderungsbenachrichtigungen zu erhalten, muss Ihre IoT-Lösung eine Route erstellen und 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.

Zusätzlich zu diesen Vorgängen können Back-End-Anwendungen die Modulzwillinge mit der SQL-ähnlichen IoT Hub-Abfragesprache abfragen.

Modulvorgänge

Die Modul-App führt mithilfe folgender atomarer Vorgänge Aktionen für den Modulzwilling aus:

• Abrufen des Modulzwillings: Dieser Vorgang gibt das Dokument zum Modulzwilling (einschließlich gewünschter und gemeldeter Systemeigenschaften) für das zurzeit verbundene Modul zurück.

• Teilweises Aktualisieren gemeldeter Eigenschaften. Dieser Vorgang ermöglicht die partielle Aktualisierung der gemeldeten Eigenschaften des derzeit verbundenen Moduls.

• Beobachten gewünschter Eigenschaften. Das derzeit verbundene Modul kann auf Wunsch benachrichtigt werden, sobald die gewünschten Eigenschaften aktualisiert werden.

Alle oben beschriebenen 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.

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.

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

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:

• IoT Hub berechnet und addiert die Länge des Schlüssels und Werts jeder Eigenschaft.

• 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 dieser Dokumente über den Grenzwert hinaus erhöhen würden, einen Fehler zurück.

Metadaten des Modulzwillings

IoT Hub verwaltet den Zeitstempel der letzten Aktualisierung für jedes JSON-Objekt in den gewünschten und gemeldeten Eigenschaften des Modulzwillings. 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": "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.

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.

Modulzwillinge haben ein ETag (Eigenschaft etag), gemäß RFC7232, das für die JSON-Darstellung des Zwillings steht. Sie können die etag-Eigenschaft in bedingten Aktualisierungsvorgängen von Back-End-Anwendungen verwenden, um Konsistenz sicherzustellen. Diese Option stellt Konsistenz in Vorgängen sicher, die den tags Container umfassen.

Gewünschte und gemeldete Eigenschaften des Modulzwillings enthalten außerdem einen $version-Wert, der garantiert inkrementell ist. Ähnlich wie bei einem ETag können Sie den Versionswert verwenden, um die Konsistenz von Updates zu erzwingen. Zum Beispiel eine Modul-Anwendung für eine gemeldete Eigenschaft oder eine Back-End-Anwendung für eine gewünschte Eigenschaft.

Versionen sind auch nützlich, wenn ein beobachtender Agent (beispielsweise die Modul-App, die die gewünschten Eigenschaften beobachtet) Racebedingungen zwischen dem Ergebnis eines Abrufvorgangs und einer Aktualisierungsbenachrichtigung beheben muss. Der Abschnitt Ablauf zur Wiederherstellung der Modulverbindung enthält weitere Informationen.

Ablauf zur Wiederherstellung der Modulverbindung

IoT Hub behält keine Aktualisierungsbenachrichtigungen für gewünschte Eigenschaften für nicht verbundene Module bei. Ein Modul, 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. Modul-App stellt eine Verbindung mit einem IoT Hub her.
2. Modul-App abonniert Aktualisierungsbenachrichtigungen für gewünschte Eigenschaften.
3. Modul-App ruft das vollständige Dokument für gewünschte Eigenschaften ab.

Die Modul-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, sehen Sie sich die folgenden IoT Hub-Tutorials an:

• Erste Schritte mit der Modulidentität und dem Modulzwilling von IoT Hub unter Verwendung eines .NET-Back-Ends und eines .NET-Geräts