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.

En este artículo se describe:

• La estructura del dispositivo gemelo: etiquetas, propiedades deseadas y propiedades notificadas.
• Las operaciones que pueden realizar las aplicaciones de dispositivo y back-end 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.

• Sincronizar el estado de flujos de trabajo de larga duración entre la aplicación del dispositivo y el back-end. Por ejemplo, cuando el back-end de la solución 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:

• El dispositivo y el back end pueden usar para sincronizar la configuración y las condiciones 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. Una sección del documento JSON en la que el back-end de solución puede 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. El back-end de solución puede establecer 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 el back-end de solución puede 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. Las propiedades connectionStateUpdatedTime y generationId no se incluirán.

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 batteryLevel notificada por la aplicación de dispositivo. 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.

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:

1. El back-end de la solución 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"
       },
       ...
   },
   

2. 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"
       }
       ...
   }
   

3. El back-end de la solución realiza un seguimiento de los resultados de la operación de configuración en muchos dispositivos mediante consultando dispositivos gemelos.

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 permite que el back-end de la solución actualice parcialmente las etiquetas o las propiedades deseadas del dispositivo gemelo. La actualización parcial se expresa como un documento JSON que agrega o actualiza cualquier propiedad. Las propiedades establecidas en null se quitan. El ejemplo siguiente crea una nueva propiedad deseada con el valor {"newProperty": "newValue"}, sobrescribe el valor existente de existingProperty con "otherNewValue", y quita otherOldProperty. 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 permite que el back-end de la solución sobrescriba completamente todas las propiedades deseadas y sustituya un nuevo documento JSON para properties/desired.

• Reemplazar etiquetas. Esta operación permite que el back-end de la solución sobrescriba completamente todas las etiquetas y sustituya un nuevo documento JSON para tags.

• Recibir notificaciones gemelas. Esta operación permite que el back-end de la solución reciba una notificación cuando se modifique la gemela. Para ello, 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. Esta operación usa el mismo formato de actualización JSON que el back-end de la solución usa para una actualización parcial de propiedades deseadas.

• Observar las propiedades deseadas. El dispositivo conectado actualmente puede elegir recibir notificaciones de las actualizaciones de las propiedades deseadas cuando se produzcan. El dispositivo recibe la misma forma de actualización (sustitución parcial o completa) ejecutada por el back-end de la solución.

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:

• Para cada propiedad del documento JSON, IoT Hub calcula y agrega de forma acumulativa la longitud del valor y la clave de la 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, la parte que realiza la actualización puede usar la versión para garantizar la coherencia de las actualizaciones. Por ejemplo, una aplicación de dispositivo para una propiedad notificada o la solució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:

1. La aplicación de dispositivo se conecta a un centro de IoT.
2. La aplicación de dispositivo se suscribe a las notificaciones de actualización de las propiedades deseadas.
3. 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:

• Tutorial: Configuración de los dispositivos con propiedades de dispositivos gemelos
• Uso de dispositivos gemelos