Hantera digitala IoT Plug and Play-tvillingar
IoT Plug and Play stöder åtgärder för att hämta digitala tvillingar och uppdatera digitala tvillingar för att hantera digitala tvillingar. Du kan använda rest-API :er eller någon av tjänst-SDK:erna.
Uppdatera en digital tvilling
En IoT Plug and Play-enhet implementerar en modell som beskrivs av DTDL (Digital Twins Definition Language). Lösningsutvecklare kan använda API:et Update Digital Twin för att uppdatera komponentens tillstånd och egenskaperna för den digitala tvillingen.
IoT Plug and Play-enheten som används som exempel i den här artikeln implementerar temperaturstyrenhetsmodellen med termostatkomponenter .
Följande kodfragment visar svaret på en Get digital twin request formatted as a JSON object (Hämta digital tvilling-begäran formaterad som ett JSON-objekt). Mer information om formatet för digitala tvillingar finns i Förstå digitala IoT Plug and Play-tvillingar:
{
"$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"
}
}
}
Med digitala tvillingar kan du uppdatera en hel komponent eller egenskap med hjälp av en JSON-korrigering.
Du kan till exempel uppdatera egenskapen på targetTemperature följande sätt:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
Den tidigare uppdateringen anger önskat värde för en egenskap på motsvarande komponentnivå $metadata enligt följande kodfragment. IoT Hub uppdaterar den önskade versionen av egenskapen:
"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"
}
}
}
Lägga till, ersätta eller ta bort en komponent
Åtgärder på komponentnivå kräver en tom objektmarkör $metadata i värdet.
En åtgärd för att lägga till eller ersätta komponent anger önskade värden för alla angivna egenskaper. Det rensar också önskade värden för eventuella skrivbara egenskaper som inte tillhandahålls med uppdateringen.
Om du tar bort en komponent rensas önskade värden för alla skrivbara egenskaper som finns. En enhet synkroniserar slutligen den här borttagningen och slutar rapportera de enskilda egenskaperna. Komponenten tas sedan bort från den digitala tvillingen.
Följande JSON Patch-exempel visar hur du lägger till, ersätter eller tar bort en komponent:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Lägga till, ersätta eller ta bort en egenskap
En åtgärd för att lägga till eller ersätta anger önskat värde för en egenskap. Enheten kan synkronisera tillstånd och rapportera en uppdatering av värdet tillsammans med en ack kod, version och beskrivning.
Om du tar bort en egenskap rensas det önskade värdet för egenskapen om den har angetts. Enheten kan sedan sluta rapportera den här egenskapen och den tas bort från komponenten. Om den här egenskapen är den sista i komponenten tas även komponenten bort.
Följande JSON Patch-exempel visar hur du lägger till, ersätter eller tar bort en egenskap i en komponent:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Regler för att ange önskat värde för en digital tvillingegenskap
Namn
Namnet på en komponent eller egenskap måste vara giltigt DTDL-namn.
Tillåtna tecken är a-z, A-Z, 0-9 (inte som det första tecknet) och understreck (inte som det första eller sista tecknet).
Ett namn kan vara 1–64 tecken långt.
Egenskapsvärde
Värdet måste vara en giltig DTDL-egenskap.
Alla primitiva typer stöds. Inom komplexa typer stöds uppräkningar, kartor och objekt. Mer information finns i DTDL-scheman.
Egenskaper stöder inte matris eller något komplext schema med en matris.
Ett maximalt djup på fem nivåer stöds för ett komplext objekt.
Alla fältnamn i komplext objekt ska vara giltiga DTDL-namn.
Alla kartnycklar ska vara giltiga DTDL-namn.
Felsöka api-fel för uppdatering av digitala tvillingar
API:et för digitala tvillingar genererar följande allmänna felmeddelande:
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.
Om du ser det här felet kontrollerar du att uppdateringskorrigeringen följer reglerna för att ange önskat värde för en digital tvillingegenskap.
När du uppdaterar en komponent kontrollerar du att det tomma objektet $metadata markören har angetts.
Uppdateringar kan misslyckas om en enhets rapporterade värden inte överensstämmer med IoT plug and play-konventioner.
Nästa steg
Nu när du har lärt dig mer om digitala tvillingar finns här några fler resurser: