Dispositivos gemelos en IoT Hub
Los dispositivos gemelos son documentos JSON que almacenan información acerca del estado del dispositivo, incluidos metadatos, configuraciones y condiciones. Azure IoT Hub mantiene un dispositivo gemelo para cada dispositivo que se conecta a IoT Hub.
Nota
Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.
En este artículo se describe:
- La estructura del dispositivo gemelo: etiquetas, propiedades deseadas y propiedades notificadas.
- Las operaciones que aplicaciones de dispositivos y el back-end de solución pueden realizar en dispositivos gemelos.
Use los dispositivos gemelos para:
Almacenar metadatos específicos de dispositivo en la nube. Por ejemplo, la ubicación de una máquina expendedora.
Notificar la información sobre el estado actual, como las funcionalidades y las condiciones disponibles de la aplicación del dispositivo. Por ejemplo, si un dispositivo está conectado con su instancia de IoT Hub a través de un móvil o de WiFi.
Sincronice el estado de los flujos de trabajo de ejecución prolongada entre la aplicación de dispositivo y las aplicaciones de back-end. Por ejemplo, cuando una aplicación de back-end especifica la nueva versión de firmware que se va a instalar y la aplicación de dispositivo informa de las distintas fases del proceso de actualización.
Consultar los metadatos, la configuración o el estado del dispositivo.
Para obtener más información sobre el uso de propiedades notificadas, mensajes del dispositivo a la nube o carga de archivos, consulte Guía de comunicación del dispositivo a la nube.
Para obtener más información sobre el uso de propiedades deseadas, métodos directos o mensajes de la nube al dispositivo, consulte Guía de comunicación de la nube al dispositivo.
Para obtener información sobre cómo se relacionan los dispositivos gemelos con el modelo de dispositivo utilizado en un dispositivo Azure IoT Plug and Play, consulte Información de Digital Twins de IoT Plug and Play.
Dispositivos gemelos
Los dispositivos gemelos almacenan información relacionada con el dispositivo que:
Las aplicaciones de dispositivo y las aplicaciones de back-end pueden usar para sincronizar las condiciones y la configuración del dispositivo.
El back-end de la solución se puede usar para consultar e identificar operaciones de larga duración.
El ciclo de vida de un dispositivo gemelo está vinculado a su identidad del dispositivo correspondiente. Los dispositivos gemelos se crean y se eliminan implícitamente cuando se crea o se elimina una identidad de dispositivo en IoT Hub.
Un dispositivo gemelo es un documento JSON que incluye:
Etiquetas. Sección del documento JSON en la que las aplicaciones de back-end pueden leer y escribir. Las etiquetas no son visibles para las aplicaciones de dispositivo.
Propiedades deseadas. Se usan en conjunción con las propiedades notificadas para sincronizar la configuración o la condición del dispositivo. Las aplicaciones de back-end pueden establecer las propiedades deseadas y la aplicación de dispositivo puede leerlas. La aplicación de dispositivo también puede recibir notificaciones de los cambios en las propiedades deseadas.
Propiedades notificadas. Se usan en conjunción con las propiedades deseadas para sincronizar la configuración o la condición del dispositivo. La aplicación de dispositivo puede establecer propiedades notificadas y las aplicaciones de back-end pueden leerlas y consultarlas.
Propiedades de identidad del dispositivo. La raíz del documento JSON del dispositivo gemelo contiene las propiedades de solo lectura de la identidad de dispositivo correspondiente, almacenadas en el registro de identidad de dispositivo. No se incluyen las propiedades
connectionStateUpdatedTimeygenerationId.
En el ejemplo siguiente se muestra un documento JSON del dispositivo gemelo:
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
El objeto raíz contiene las propiedades de identidad del dispositivo y los objetos de contenedor para tags y las propiedades reported y desired. El contenedor properties incluye algunos elementos de solo lectura ($metadata y$version) descritos en las secciones Metadatos de dispositivo gemelo y Simultaneidad optimista.
Ejemplo de propiedad notificada
En el ejemplo anterior, el dispositivo gemelo contiene una propiedad notificada batteryLevel. Esta propiedad permite consultar y operar en los dispositivos en función del último nivel de batería notificado. Otros ejemplos incluyen la aplicación de dispositivo notificando las funcionalidades del dispositivo o las opciones de conectividad.
Nota:
Las propiedades notificadas simplifican los escenarios en los que está interesado en el último valor conocido de una propiedad. Use mensajes de dispositivo a nube si desea procesar la telemetría del dispositivo en forma de secuencias de eventos con marca de tiempo, como series temporales.
Ejemplo de propiedad deseada
En el ejemplo anterior, el back-end de la solución y la aplicación de dispositivo usan las propiedades deseadas y notificadas del dispositivo gemelo telemetryConfig para sincronizar la configuración de telemetría de este dispositivo. Por ejemplo:
Una aplicación back-end establece la propiedad deseada con el valor de configuración deseado. Esta es la parte del documento con el conjunto de propiedad deseada:
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },La aplicación de dispositivo recibe la notificación del cambio de inmediato si el dispositivo está conectado. Si no está conectado, la aplicación de dispositivo sigue el flujo de reconexión del dispositivo cuando se conecta. Después, la aplicación de dispositivo notifica la configuración actualizada (o una condición de error mediante la propiedad
status. Esta es la parte de las propiedades notificadas:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }Una aplicación back-end realiza un seguimiento de los resultados de la operación de configuración en muchos dispositivos mediante consultando dispositivos gemelos.
Nota:
Los fragmentos de código anteriores son ejemplos, optimizados para mejorar su legibilidad, de una manera de codificar una configuración de dispositivo y su estado. IoT Hub no impone un esquema específico para las propiedades deseadas y notificadas en los dispositivos gemelos.
Importante
IoT Plug and Play define un esquema que usa varias propiedades adicionales para sincronizar los cambios con las propiedades deseadas y notificadas. Si la solución usa IoT Plug and Play, debe seguir las convenciones de esta tecnología al actualizar las propiedades gemelas. Para obtener más información y un ejemplo, vea Propiedades editables en IoT Plug and Play.
Se pueden usar los dispositivos gemelos para sincronizar operaciones de larga duración, como las actualizaciones de firmware. Para más información sobre cómo usar las propiedades para sincronizar y realizar un seguimiento de las operaciones de larga duración en todos los dispositivo consulte Uso de las propiedades deseadas para configurar dispositivos.
Operaciones de back-end
Para trabajar en el back-end de la solución, el dispositivo gemelo usa las siguientes operaciones atómicas expuestas mediante HTTPS:
Recuperación del dispositivo gemelo por el identificador. Esta operación devuelve el documento del dispositivo gemelo, incluidas las etiquetas y las propiedades del sistema, deseadas y notificadas.
Actualización parcial de los dispositivos gemelos. Esta operación actualiza parcialmente las etiquetas o las propiedades deseadas en un dispositivo gemelo. La actualización parcial se expresa como un documento JSON que agrega o actualiza cualquier propiedad. Las propiedades establecidas en
nullse quitan. El ejemplo siguiente crea una nueva propiedad deseada con el valor{"newProperty": "newValue"}, sobrescribe el valor existente deexistingPropertycon"otherNewValue", y quitaotherOldProperty. No se realiza ningún cambio en otras etiquetas o propiedades deseadas existentes:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Reemplazar propiedades deseadas. Esta operación sobrescribe completamente todas las propiedades deseadas existentes y sustituye un nuevo documento JSON para
properties/desired.Reemplazar etiquetas. Esta operación sobrescribe completamente todas las etiquetas existentes y sustituye un nuevo documento JSON para
tags.Recibir notificaciones gemelas. Esta operación notifica cuándo se modifica el gemelo. Para recibir notificaciones de cambio de dispositivos gemelos, la solución de IoT debe crear una ruta y establecer el origen de datos igual a twinChangeEvents. De manera predeterminada, no existe tal ruta, por tanto, no se envían notificaciones gemelas. Si la tasa de cambio es demasiado alta, o por otras razones, como errores internos, IoT Hub podría enviar una sola notificación que contiene todos los cambios. Por lo tanto, si la aplicación necesita registro y auditoría confiables de todos los estados intermedios, debe usar mensajes del dispositivo a la nube. Para más información sobre las propiedades y el cuerpo devueltos en el mensaje de las notificaciones gemelas, consulte Esquemas de eventos que no son de telemetría.
Todas las operaciones anteriores admiten la simultaneidad optimista y requieren el permiso ServiceConnect, tal y como se define en Controlar el acceso a IoT Hub.
Además de estas operaciones, el back-end de soluciones puede hacer lo siguiente:
Consultar los dispositivos gemelos mediante el lenguaje de consultas de IoT Hub del tipo SQL.
Realizar operaciones en conjuntos grandes de dispositivos gemelos usando trabajos.
Operaciones de dispositivo
La aplicación de dispositivo aplica las siguientes operaciones atómicas en el dispositivo gemelo:
Recuperación del dispositivo gemelo. Esta operación devuelve el documento del dispositivo gemelo (incluidas las propiedades del sistema deseadas y notificadas) para el dispositivo conectado actualmente. (Las etiquetas no son visibles para las aplicaciones de dispositivo).
Actualizar parcialmente propiedades notificadas. Esta operación permite la actualización parcial de las propiedades notificadas del dispositivo conectado actualmente.
Observar las propiedades deseadas. El dispositivo conectado actualmente puede elegir recibir notificaciones de las actualizaciones de las propiedades deseadas cuando se produzcan.
Todas las operaciones anteriores requieren el permiso DeviceConnect, tal y como se define en el artículo Controlar el acceso a IoT Hub.
Los SDK de dispositivos IoT de Azure permiten usar fácilmente las operaciones anteriores desde numerosos lenguajes y plataformas. Para más información detallada sobre los tipos primitivos de IoT Hub para la sincronización de propiedades deseadas, consulte Flujo de reconexión de dispositivos.
Formato de etiquetas y propiedades
Las etiquetas y las propiedades deseadas y notificadas son objetos JSON con las siguientes restricciones:
Claves: Todas las claves en objetos JSON tienen codificación UTF-8, con distinción de mayúsculas y minúsculas, y una longitud de hasta 1 KB. Entre los caracteres permitidos no se incluyen los caracteres de control UNICODE (segmentos C0 y C1), ni
.,$y SP.Nota
Las consultas IoT Hub usadas en el enrutamiento de mensajes no admiten espacios en blanco ni ninguno de los caracteres siguientes como parte de un nombre de clave:
()<>@,;:\"/?={}.Valores: Todos los valores en un objeto JSON pueden ser de los siguientes tipos JSON: booleano, número, cadena, objeto. También se admiten las matrices.
Los enteros pueden tener un valor mínimo de -4503599627370496 y un máximo de 4503599627370495.
Los valores de la cadena son codificados UTF-8 y pueden tener una longitud máxima de 4 KB.
Profundidad: La profundidad máxima de los objetos JSON en etiquetas y propiedades deseadas y notificadas es 10. Por ejemplo, el objeto siguiente es válido:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Tamaño del dispositivo gemelo
IoT Hub aplica un límite de tamaño de 8 KB en el valor de tags y un límite de tamaño de 32 KB cada uno en el valor de properties/desired y properties/reported. Estos totales son exclusivos de los elementos de solo lectura, como $version y $metadata/$lastUpdated.
El tamaño gemelo se calcula como sigue:
IoT Hub calcula y agrega la longitud de la clave y el valor de cada propiedad.
Las claves de la propiedad se consideran cadenas codificadas UTF-8.
Los valores de propiedad simples se consideran cadenas codificadas UTF-8, valores numéricos (8 bytes) o valores booleanos (4 bytes).
El tamaño de las cadenas codificadas UTF-8 se calcula contando todos los caracteres, excepto los caracteres de control UNICODE (segmentos C0 y C1).
Los valores de propiedad complejos (objetos anidados) se calculan en función del tamaño agregado de las claves de la propiedad y los valores de propiedad que contienen.
IoT Hub rechaza con un error todas las operaciones que podrían aumentar el tamaño de los documentos tags, properties/desired o properties/reported por encima del límite.
Metadatos de dispositivo gemelo
IoT Hub conserva la marca de tiempo de la última actualización para cada objeto JSON en las propiedades deseadas y notificadas del dispositivo gemelo. Las marcas de tiempo están en formato UTC y se codifican con el formato ISO8601YYYY-MM-DDTHH:MM:SS.mmmZ.
Por ejemplo:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
Esta información se conserva en todo los niveles (no solo en las hojas de la estructura JSON) para conservar las actualizaciones que quitan las claves de objeto.
Simultaneidad optimista
Tanto las etiquetas como las propiedades deseadas y notificadas admiten la simultaneidad optimista. Si tiene que garantizar el orden de las actualizaciones de propiedades gemelas, considere la posibilidad de implementar la sincronización a nivel de la aplicación esperando la devolución de llamada de las propiedades notificadas antes de enviar la siguiente actualización.
Los dispositivos gemelos tienen una propiedad ETag etag, según RFC7232, que representa la representación JSON del gemelo. Puede usar la propiedad etag en operaciones de actualización condicional desde el back-end de la solución para garantizar la coherencia. Esta propiedad es la única opción para garantizar la coherencia en las operaciones que implican el contenedor tags.
Las propiedades deseadas y notificadas del dispositivo gemelo también tienen un valor $version que se garantiza será incremental. De forma similar a una ETag, puede usar la propiedad versión para aplicar la coherencia de las actualizaciones. Por ejemplo, una aplicación de dispositivo para una propiedad notificada o una aplicación de back-end para una propiedad deseada.
Las versiones también son útiles cuando un agente de observación (por ejemplo, la aplicación de dispositivo que observa las propiedades deseadas) tiene que conciliar las carreras entre el resultado de una operación de recuperación y una notificación de actualización. En la sección Flujo de reconexión de dispositivos se proporciona más información.
Flujo de reconexión de dispositivos
IoT Hub no conserva las notificaciones de actualización de las propiedades deseadas para los dispositivos desconectados. Se supone que un dispositivo que se está conectando debe recuperar el documento con todas las propiedades deseadas, además de suscribirse a las notificaciones de actualización. Dada la posibilidad de carreras entre las notificaciones de actualización y la recuperación completa, se debe asegurar el flujo siguiente:
- La aplicación de dispositivo se conecta a un centro de IoT.
- La aplicación de dispositivo se suscribe a las notificaciones de actualización de las propiedades deseadas.
- La aplicación de dispositivo recupera el documento completo de las propiedades deseadas.
La aplicación de dispositivo puede pasar por alto todas las notificaciones cuyo valor de $version sea anterior o igual a la versión del documento completo recuperado. Este enfoque es posible porque IoT Hub garantiza que las versiones siempre se incrementan.
Pasos siguientes
Para probar algunos de los conceptos descritos en este artículo, consulte los siguientes artículos de IoT Hub: