Управление цифровыми двойниками IoT Plug and Play
IoT Plug and Play поддерживает операции получения цифрового двойника и обновления цифрового двойника для управления цифровыми двойниками. Для этого можно использовать REST API или один из пакетов SDK службы.
Обновление цифрового двойника
Устройство IoT самонастраивающийся реализует модель, описанную языком определения Digital Twins (DTDL). Разработчики решений могут использовать API обновления цифрового двойника, чтобы изменять состояние компонента и свойства цифрового двойника.
В нашем примере устройства IoT Plug and Play для этой статьи реализована модель контроллера температуры с компонентами термостата.
Следующий фрагмент кода демонстрирует ответ на запрос получения цифрового двойника в формате объекта JSON. Дополнительные сведения о формате цифрового двойника см. в статье Сведения о цифровых двойниках 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"
}
}
}
Цифровые двойники позволяют обновить весь компонент или отдельное свойство с помощью формата JSON Patch.
В нашем примере вы можете изменить свойство targetTemperature следующим образом:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
Предыдущее обновление задает нужное значение свойства на соответствующем уровне компонента $metadata, как показано в следующем фрагменте кода. Центр Интернета вещей обновляет требуемую версию свойства:
"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"
}
}
}
Добавление, замена или удаление компонента
Для операций уровня компонента требуется пустой маркер объекта $metadata в пределах значения.
Операция добавления или замены компонента задает требуемые значения для всех предоставленных свойств. Она также очищает требуемые значения для всех свойств, доступных для записи, которые не включены в обновление.
При удалении компонента очищаются требуемые значения для всех свойств, доступных для записи. Устройство рано или поздно синхронизирует это удаление и прекратит отправку отчетов по отдельным свойствам. Затем компонент удаляется из цифрового двойника.
Следующий пример JSON Patch демонстрирует добавление, замену и удаление компонентов:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Добавление, замена или удаление свойства
Операция добавления или замены задает требуемое значение свойства. Устройство может синхронизировать состояние и сообщать об обновлении значения, передавая код, версию и описание ack.
Удаление свойства очищает требуемое значение свойства, если оно задано. После этого устройство прекратит сообщать об этом свойстве, и оно будет удалено из компонента. Если это свойство было последним в компоненте, удаляется весь компонент.
Следующий пример JSON Patch демонстрирует добавление, замену и удаление свойств в компоненте:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Правила задания требуемых значений для свойства цифрового двойника
Имя
Имя компонента или свойства должно быть допустимым именем DTDL.
Допустимые символы: a–z, A–Z, 0–9 (не могут быть первым символом) и символ подчеркивания (не может быть первым или последним символом).
Имя может содержать от 1 до 64 символов.
Значение свойства
Значение должно быть допустимым свойством DTDL.
Поддерживаются все примитивные типы. В сложных типах поддерживаются перечисления, сопоставления и объекты. Дополнительные сведения см. в разделе "Схемы DTDL".
Свойства не поддерживают массивы или сложные схемы с массивами.
Для сложного объекта поддерживается глубина не более пяти уровней.
Все имена полей в сложном объекте должны быть допустимыми именами DTDL.
Все ключи карты должны быть допустимыми именами DTDL.
Устранение ошибок при обновлениях через API цифрового двойника
API цифрового двойника создает сообщение об ошибке общего типа:
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.
Если вы видите эту ошибку, убедитесь, что исправление обновления следует правилам для задания требуемого значения свойства цифрового двойника.
При обновлении компонента обязательно установите маркер $metadata для пустого объекта.
Обновления могут завершиться неудачей, если сообщаемые значения устройства не соответствуют соглашениям IoT Plug and Play.
Следующие шаги
Теперь, когда вы узнали о цифровых двойниках, вот несколько дополнительных ресурсов: