Administración de Digital Twins de IoT Plug and Play
IoT Plug and Play admite las operaciones Get digital twin (Obtener gemelo digital) y Update digital twin (Actualizar gemelo digital) para administrar Digital Twins. Puede usar las API de REST o uno de los SDK de servicio.
Actualización de un gemelo digital
Un dispositivo IoT Plug and Play implementa un modelo descrito por el lenguaje de definición de Digital Twins (DTDL). Los desarrolladores de soluciones pueden usar la API de actualización de gemelo digital para actualizar el estado del componente y las propiedades de gemelo digital.
El dispositivo IoT Plug and Play, que se usa como ejemplo en este artículo, implementa el modelo de controlador de temperatura con un componentes de termostato.
En el fragmento de código siguiente se muestra la respuesta a una solicitud Get digital twin (Obtener gemelo digital) con formato de objeto JSON. Para obtener más información sobre el formato de gemelo digital, vea Información de Digital Twins de 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"
}
}
}
Digital Twins permite actualizar una propiedad o un componente completo mediante una revisión de JSON.
Por ejemplo, puede actualizar la propiedad targetTemperature como se indica a continuación:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
La actualización anterior establece el valor deseado de una propiedad en el elemento $metadata de nivel de componente correspondiente, tal como se muestra en el siguiente fragmento de código. IoT Hub actualiza la versión deseada de la propiedad:
"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"
}
}
}
Adición, reemplazo o eliminación de un componente
Las operaciones de nivel de componente requieren un marcador $metadata de objeto vacío dentro del valor.
Una operación de adición o reemplazo de componente establece los valores deseados de todas las propiedades proporcionadas. También borra los valores deseados para las propiedades grabables que no se proporcionan con la actualización.
Al quitar un componente, se borran los valores deseados de todas las propiedades grabables presentes. Con el tiempo, un dispositivo sincroniza esta eliminación y deja de informar de las propiedades individuales. A continuación, el componente se quita del gemelo digital.
En el siguiente ejemplo de revisión de JSON se muestra cómo agregar, reemplazar o quitar un componente:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Adición, reemplazo o eliminación de una propiedad
Una operación de adición o reemplazo establece el valor deseado de una propiedad. El dispositivo puede sincronizar el estado y notificar una actualización del valor junto con un código ack, una versión y una descripción.
Al quitar una propiedad, se borra el valor deseado de la propiedad, si se ha establecido. Después, el dispositivo puede dejar de informar de esta propiedad y se quita del componente. Si esta propiedad es la última del componente, también se quita el componente.
En el siguiente ejemplo de revisión de JSON se muestra cómo agregar, reemplazar o quitar una propiedad dentro de un componente:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Reglas para establecer el valor deseado de una propiedad de gemelo digital
Nombre
El nombre de un componente o propiedad debe ser un nombre DTDL válido.
Los caracteres permitidos son a-z, A-Z, 0-9 (no como primer carácter) y guion bajo (no como primer ni último carácter).
Un nombre puede tener entre 1 y 64 caracteres.
Valor de propiedad
El valor debe ser una propiedad DTDL válida.
Se admiten todos los tipos primitivos. Dentro de los tipos complejos, se admiten las enumeraciones, las asignaciones y los objetos. Para más información, consulte Esquemas DTDL.
Las propiedades no admiten matrices ni esquemas complejos con una matriz.
Se admite una profundidad máxima de cinco niveles para un objeto complejo.
Todos los nombres de campo del objeto complejo deben ser nombres DTDL válidos.
Todas las claves de asignación deben ser nombres DTDL válidos.
Solución de problemas de errores de API de gemelo digital
La API de actualización de gemelo digital genera el siguiente mensaje de error genérico:
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.
Si ve este error, asegúrese de que la revisión de actualización sigue las reglas para establecer el valor deseado de una propiedad de gemelo digital.
Al actualizar un componente, asegúrese de que el marcador $metadata de objeto vacío está establecido.
Se pueden producir errores en las actualizaciones si los valores informados de un dispositivo no se ajustan a las convenciones de IoT plug and Play.
Pasos siguientes
Ahora que ha aprendido acerca de los gemelos digitales, estos son algunos recursos adicionales: