IoT Plug en Play digitale dubbels beheren
IoT Plug en Play ondersteunt Bewerkingen voor digitale dubbels ophalen en digitale dubbels bijwerken om digitale dubbels te beheren. U kunt de REST API's of een van de service-SDK's gebruiken.
Een digital twin bijwerken
Een IoT Plug en Play-apparaat implementeert een model dat wordt beschreven door Digital Twins Definition Language (DTDL). Oplossingsontwikkelaars kunnen de Update Digital Twin-API gebruiken om de status van het onderdeel en de eigenschappen van de digitale dubbel bij te werken.
Het IoT Plug en Play-apparaat dat als voorbeeld in dit artikel wordt gebruikt, implementeert het model Temperatuurregelaar met thermostaatonderdelen.
Het volgende codefragment toont het antwoord op een get digital twin-aanvraag die is opgemaakt als een JSON-object. Zie IoT-Plug en Play digital twins voor meer informatie over de digitale dubbel-indeling:
{
"$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"
}
}
}
Met digitale dubbels kunt u een volledig onderdeel of een hele eigenschap bijwerken met behulp van een JSON Patch.
U kunt de targetTemperature eigenschap bijvoorbeeld als volgt bijwerken:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
Met de vorige update wordt de gewenste waarde van een eigenschap ingesteld op het bijbehorende onderdeelniveau $metadata , zoals wordt weergegeven in het volgende fragment. IoT Hub werkt de gewenste versie van de eigenschap bij:
"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"
}
}
}
Een onderdeel toevoegen, vervangen of verwijderen
Bewerkingen op onderdeelniveau vereisen een lege objectmarkering $metadata binnen de waarde.
Met een bewerking voor het toevoegen of vervangen van onderdelen worden de gewenste waarden van alle opgegeven eigenschappen ingesteld. Ook worden de gewenste waarden gewist voor beschrijfbare eigenschappen die niet bij de update worden geleverd.
Als u een onderdeel verwijdert, worden de gewenste waarden van alle schrijfbare eigenschappen gewist. Een apparaat synchroniseert deze verwijdering uiteindelijk en stopt met het rapporteren van de afzonderlijke eigenschappen. Het onderdeel wordt vervolgens verwijderd uit de digitale dubbel.
In het volgende JSON Patch-voorbeeld ziet u hoe u een onderdeel toevoegt, vervangt of verwijdert:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Een eigenschap toevoegen, vervangen of verwijderen
Met een bewerking voor toevoegen of vervangen wordt de gewenste waarde van een eigenschap ingesteld. Het apparaat kan de status synchroniseren en een update van de waarde rapporteren, samen met een ack code, versie en beschrijving.
Als u een eigenschap verwijdert, wordt de gewenste waarde van de eigenschap gewist als deze is ingesteld. Het apparaat kan vervolgens stoppen met het rapporteren van deze eigenschap en wordt verwijderd uit het onderdeel. Als deze eigenschap de laatste is in het onderdeel, wordt het onderdeel ook verwijderd.
In het volgende JSON Patch-voorbeeld ziet u hoe u een eigenschap in een onderdeel toevoegt, vervangt of verwijdert:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Regels voor het instellen van de gewenste waarde van een digitale dubbel-eigenschap
Naam
De naam van een onderdeel of eigenschap moet geldige DTDL-naam zijn.
Toegestane tekens zijn a-z, A-Z, 0-9 (niet als het eerste teken) en onderstrepingsteken (niet als het eerste of laatste teken).
Een naam mag 1-64 tekens lang zijn.
Eigenschapswaarde
De waarde moet een geldige DTDL-eigenschap zijn.
Alle primitieve typen worden ondersteund. Binnen complexe typen, opsommingen, kaarten en objecten worden ondersteund. Zie DTDL-schema's voor meer informatie.
Eigenschappen bieden geen ondersteuning voor matrix of een complex schema met een matrix.
Een maximale diepte van vijf niveaus wordt ondersteund voor een complex object.
Alle veldnamen binnen een complex object moeten geldige DTDL-namen zijn.
Alle kaartsleutels moeten geldige DTDL-namen zijn.
Problemen met de api voor digitale dubbels bijwerken oplossen
Met de API voor digitale dubbels wordt het volgende algemene foutbericht gegenereerd:
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.
Als u deze fout ziet, controleert u of de updatepatch de regels volgt voor het instellen van de gewenste waarde van een digitale dubbel-eigenschap.
Wanneer u een onderdeel bijwerkt, moet u ervoor zorgen dat het lege object $metadata markering is ingesteld.
Updates kunnen mislukken als de gerapporteerde waarden van een apparaat niet voldoen aan de IoT Plug en Play-conventies.
Volgende stappen
Nu u meer hebt geleerd over digitale dubbels, vindt u hier nog enkele bronnen: