Verwalten von digitalen IoT Plug & Play-Zwillingen
IoT Plug & Play unterstützt die Vorgänge Get digital twin (Abrufen des digitalen Zwillings) und Update digital twin (Aktualisieren des digitalen Zwillings) zum Verwalten von digitalen Zwillingen. Sie können dafür entweder die REST-APIs oder eines der Dienst-SDKs verwenden.
Aktualisieren eines digitalen Zwillings
Ein IoT Plug & Play Gerät implementiert ein Modell, das von Digital Twins Definition Language (DTDL) beschrieben wird. Lösungsentwickler können mithilfe der Update Digital Twin API (API zum Aktualisieren des digitalen Zwillings) den Status der Komponente und die Eigenschaften des digitalen Zwillings aktualisieren.
Das in diesem Artikel als Beispiel verwendete IoT Plug & Play-Gerät implementiert das Modell „Temperatur-Controller“ mit Thermostat-Komponenten.
Der folgende Codeausschnitt zeigt die Antwort auf eine Anforderung Get Digital Twin (Abrufen des digitalen Zwillings), die als JSON-Objekt formatiert ist. Weitere Informationen zum Format eines digitalen Zwillings finden Sie unter Grundlegendes zu digitalen IoT Plug & Play-Zwillingen:
{
"$dtId": "sample-device",
"serialNumber": "alwinexlepaho8329",
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 20.4,
"$metadata": {
"targetTemperature": {
"desiredValue": 20.4,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
},
"$metadata": {
"$model": "dtmi:com:example:TemperatureController;1",
"serialNumber": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}
Digitale Zwillinge ermöglichen es Ihnen, eine ganze Komponente oder Eigenschaft mithilfe eines JSON-Patches zu aktualisieren.
Beispielsweise können Sie die Eigenschaft targetTemperatureso aktualisieren:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
Mit dem vorherigen Update wird der gewünschte Wert einer Eigenschaft in den entsprechenden $metadata auf Komponentenebene festgelegt, wie im folgenden Codeausschnitt gezeigt wird. IoT Hub aktualisiert die gewünschte Version der Eigenschaft:
"thermostat1": {
"targetTemperature": 20.4,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.4,
"desiredVersion": 5,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
}
}
}
Hinzufügen, Ersetzen oder Entfernen einer Komponente
Vorgänge auf Komponentenebene erfordern einen leeren $metadata-Objektmarker innerhalb des Werts.
Ein Vorgang zum Hinzufügen oder Ersetzen von Komponenten legt die gewünschten Werte für alle bereitgestellten Eigenschaften fest. Außerdem werden die gewünschten Werte für alle schreibbaren Eigenschaften gelöscht, die mit dem Update nicht bereitgestellt wurden.
Beim Entfernen einer Komponente werden die gewünschten Werte aller vorhandenen schreibbaren Eigenschaften gelöscht. Ein Gerät synchronisiert schließlich diesen Entfernungsvorgang und beendet die Berichterstellung für die einzelnen Eigenschaften. Danach wird die Komponente aus dem digitalen Zwilling entfernt.
Das folgende JSON-Patchbeispiel zeigt, wie eine Komponente hinzugefügt, ersetzt oder entfernt wird:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Hinzufügen, Ersetzen oder Entfernen einer Eigenschaft
Durch einen Vorgang zum Hinzufügen oder Ersetzen wird der gewünschte Wert einer Eigenschaft festgelegt. Das Gerät kann den Status synchronisieren und eine Aktualisierung des Werts zusammen mit einem ack-Code, einer Version und einer Beschreibung melden.
Beim Entfernen einer Eigenschaft wird deren gewünschter Wert gelöscht, falls er festgelegt wurde. Das Gerät kann dann die Berichterstellung für diese Eigenschaft beenden, und sie wird aus der Komponente entfernt. Wenn diese Eigenschaft die letzte in der Komponente ist, wird die Komponente ebenfalls entfernt.
Das folgende JSON-Patchbeispiel zeigt, wie eine Eigenschaft in einer Komponente hinzugefügt, ersetzt oder entfernt wird:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Regeln zum Festlegen des gewünschten Werts für eine Eigenschaft des digitalen Zwillings
Name
Der Name einer Komponente oder Eigenschaft muss gültiger DTDL-Name sein.
Zulässige Zeichen sind a–z, A–Z, 0–9 (nicht als erstes Zeichen) und Unterstrich (nicht als erstes oder letztes Zeichen).
Ein Name kann 1 bis 64 Zeichen lang sein.
Eigenschaftswert
Der Wert muss eine gültige DTDL-Eigenschaft sein.
Alle einfachen Typen werden unterstützt. Innerhalb komplexer Typen werden Enumerationen, Zuordnungen und Objekte unterstützt. Weitere Informationen finden Sie unter DTDL-Schemas.
Eigenschaften unterstützen kein Array oder kein komplexes Schema mit einem Array.
Bei einem komplexen Objekt wird eine maximale Tiefe von fünf Ebenen unterstützt.
Alle Feldnamen innerhalb des komplexen Objekts sollten gültige DTDL-Namen sein.
Alle Zuordnungsschlüssel sollten gültige DTDL-Namen sein.
Beheben von API-Fehlern beim Aktualisieren von digitalen Zwillingen
Die Digital Twin-API löst die folgende generische Fehlermeldung aus:
ErrorCode:ArgumentInvalid;'{propertyName}' exists within the device twin and is not digital twin conformant property. Please refer to aka.ms/dtpatch to update this to be conformant.
Wenn Ihnen dieser Fehler angezeigt wird, vergewissern Sie sich, dass der Updatepatch die Regeln zum Festlegen des gewünschten Werts für eine Eigenschaft des digitalen Zwillings einhält.
Stellen Sie beim Aktualisieren einer Komponente sicher, dass der leere Objektmarker „$metadata“ festgelegt wird.
Updates können fehlschlagen, wenn die gemeldeten Werte eines Geräts den IoT Plug & Play-Konventionen nicht entsprechen.
Nächste Schritte
Nachdem Sie etwas über digitale Zwillinge erfahren haben, sind jetzt hier einige weitere Ressourcen: