Zarządzanie cyfrowymi reprezentacjami bliźniaczymi usługi IoT Plug and Play
Usługa IoT Plug and Play obsługuje pobieranie cyfrowych reprezentacji bliźniaczych i aktualizowanie operacji cyfrowej reprezentacji bliźniaczej w celu zarządzania cyfrowymi reprezentacjami bliźniaczymi . Możesz użyć interfejsów API REST lub jednego z zestawów SDK usługi.
Aktualizowanie cyfrowej reprezentacji bliźniaczej
Urządzenie IoT Plug and Play implementuje model opisany przez język DTDL (Digital Twins Definition Language). Deweloperzy rozwiązań mogą użyć interfejsu API Update Digital Twin, aby zaktualizować stan składnika i właściwości cyfrowej reprezentacji bliźniaczej.
Urządzenie IoT Plug and Play używane jako przykład w tym artykule implementuje model kontrolera temperatury ze składnikami termostatu .
Poniższy fragment kodu przedstawia odpowiedź na żądanie Get digital twin sformatowane jako obiekt JSON. Aby dowiedzieć się więcej na temat formatu cyfrowej reprezentacji bliźniaczej, zobacz Omówienie cyfrowych reprezentacji bliźniaczych IoT Plug and Play:
{
"$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"
}
}
}
Cyfrowe reprezentacje bliźniacze umożliwiają aktualizowanie całego składnika lub właściwości przy użyciu poprawki JSON.
Można na przykład zaktualizować targetTemperature właściwość w następujący sposób:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
Poprzednia aktualizacja ustawia żądaną wartość właściwości na odpowiednim poziomie $metadata składnika, jak pokazano w poniższym fragmencie kodu. Usługa IoT Hub aktualizuje żądaną wersję właściwości:
"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"
}
}
}
Dodawanie, zastępowanie lub usuwanie składnika
Operacje na poziomie składnika wymagają pustego znacznika obiektu $metadata w ramach wartości.
Operacja dodawania lub zastępowania składnika ustawia żądane wartości wszystkich podanych właściwości. Usuwa również żądane wartości dla wszystkich właściwości zapisywalnych, które nie są dostarczane z aktualizacją.
Usunięcie składnika usuwa żądane wartości wszystkich właściwości zapisywalnych. Urządzenie ostatecznie synchronizuje to usunięcie i zatrzymuje raportowanie poszczególnych właściwości. Składnik zostanie następnie usunięty z cyfrowej reprezentacji bliźniaczej.
W poniższym przykładzie poprawki JSON pokazano, jak dodawać, zastępować lub usuwać składnik:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Dodawanie, zastępowanie lub usuwanie właściwości
Operacja dodawania lub zastępowania ustawia żądaną wartość właściwości. Urządzenie może synchronizować stan i zgłaszać aktualizację wartości wraz z kodem, wersją i opisem ack .
Usunięcie właściwości usuwa żądaną wartość właściwości, jeśli jest ustawiona. Następnie urządzenie może zatrzymać raportowanie tej właściwości i zostanie usunięte ze składnika. Jeśli ta właściwość jest ostatnią właściwością w składniku, składnik zostanie również usunięty.
W poniższym przykładzie poprawki JSON pokazano, jak dodawać, zastępować lub usuwać właściwość w składniku:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Reguły ustawiania żądanej wartości właściwości cyfrowej reprezentacji bliźniaczej
Nazwa/nazwisko
Nazwa składnika lub właściwości musi być prawidłową nazwą DTDL.
Dozwolone znaki to a-z, A-Z, 0-9 (nie jako pierwszy znak) i podkreślenie (nie jako pierwszy lub ostatni znak).
Nazwa może mieć długość od 1 do 64 znaków.
Wartość właściwości
Wartość musi być prawidłową właściwością DTDL.
Obsługiwane są wszystkie typy pierwotne. Obsługiwane są typy złożone, wyliczenia, mapy i obiekty. Aby dowiedzieć się więcej, zobacz Schematy DTDL.
Właściwości nie obsługują tablicy ani żadnego złożonego schematu z tablicą.
Maksymalna głębokość pięciu poziomów jest obsługiwana dla obiektu złożonego.
Wszystkie nazwy pól w obiekcie złożonym powinny być prawidłowymi nazwami DTDL.
Wszystkie klucze mapy powinny być prawidłowymi nazwami DTDL.
Rozwiązywanie problemów z błędami interfejsu API aktualizacji cyfrowej reprezentacji bliźniaczej
Interfejs API cyfrowej reprezentacji bliźniaczej zgłasza następujący ogólny komunikat o błędzie:
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.
Jeśli widzisz ten błąd, upewnij się, że poprawka aktualizacji jest zgodna z regułami ustawiania żądanej wartości właściwości cyfrowej reprezentacji bliźniaczej.
Podczas aktualizowania składnika upewnij się, że ustawiono pusty obiekt $metadata znacznika .
Aktualizacje może zakończyć się niepowodzeniem, jeśli zgłoszone wartości urządzenia nie są zgodne z Konwencje dotyczące wtyczek i odtwarzania IoT.
Następne kroki
Teraz, gdy znasz już cyfrowe reprezentacje bliźniacze, oto kilka dodatkowych zasobów: