Enriquecimiento de mensajes para mensajes de IoT Hub del dispositivo a la nube

El enriquecimiento de mensajes es la capacidad de un centro de IoT para marcar mensajes con información adicional antes de que los mensajes se envíen al punto de conexión designado. Una razón para utilizar el enriquecimiento de mensajes es incluir datos que se pueden usar para simplificar el procesamiento descendente. Por ejemplo, el enriquecimiento de mensajes de telemetría de dispositivos con una etiqueta de dispositivo gemelo puede reducir la carga de los clientes para realizar llamadas API de dispositivos gemelos para obtener esta información.

El enriquecimiento de mensajes tiene tres elementos clave:

• Nombre o clave de enriquecimiento

• Un valor

• Uno o varios puntos de conexión para los que se debe aplicar el enriquecimiento.

La clave es una cadena. Una clave solo puede contener caracteres alfanuméricos o estos caracteres especiales: guión (-), guión bajo (_) y punto (.).

El valor puede ser cualquiera de los siguientes ejemplos:

• Cualquier cadena estática. No se permiten valores dinámicos como condiciones, lógica, operaciones y funciones. Por ejemplo, si desarrolla una aplicación SaaS que la utilizan varios clientes, puede asignar un identificador a cada cliente y hacer que ese identificador esté disponible en la aplicación. Cuando se ejecuta la aplicación, IoT Hub marcará los mensajes de telemetría de los dispositivos con el identificador del cliente, haciendo posible procesar los mensajes de forma diferente para cada cliente.

• El nombre del centro de IoT que envía el mensaje. Este valor es $iothubname.

• Información del dispositivo gemelo, como la ruta de acceso. Algunos ejemplos serían $twin.tags.field y $twin.tags.latitude.

  Nota:

  En este momento, solo $iothubname, $twin.tags, $twin.properties.desired y $twin.properties.reported son variables admitidas para el enriquecimiento de mensajes. Además, solo se admiten tipos primitivos para los enriquecimientos. Los mensajes no se pueden enriquecer con tipos de objeto.

Los enriquecimientos de mensajes se agregan como propiedades de la aplicación a los mensajes enviados a los puntos de conexión elegidos.

Aplicación de enriquecimientos

Los mensajes pueden proceder de cualquier origen de datos compatible con el enrutamiento de mensajes de IoT Hub, incluidos los siguientes ejemplos:

• telemetría del dispositivo, como la temperatura o la presión
• Notificaciones de cambio de dispositivo gemelo: cambios en el dispositivo gemelo
• Eventos del ciclo de vida del dispositivo, como cuando se crea o se elimina el dispositivo

Puede agregar enriquecimientos a los mensajes que van al punto de conexión integrado de un centro de IoT o a los mensajes que se enrutan a puntos de conexión personalizados, como Azure Blob Storage, una cola de Service Bus o un tema de Service Bus.

También puede agregar enriquecimientos a los mensajes que se publican en Event Grid creando primero una suscripción de Event Grid con el tipo de mensaje de telemetría del dispositivo. En función de esta suscripción, crearemos una ruta predeterminada en Azure IoT Hub para la telemetría. Esta ruta única puede controlar todas las suscripciones de Event Grid. A continuación, puede configurar enriquecimientos para el punto de conexión mediante la pestaña Enriquecer mensajes de la sección Enrutamiento de mensajes de IoT Hub. Para obtener información sobre cómo reaccionar a eventos mediante Event Grid, consulte IoT Hub y Event Grid.

Se aplican los enriquecimientos de punto de conexión. Si especifica cinco enriquecimientos que se van a marcar para un punto de conexión específico, todos los mensajes que lleguen a ese punto de conexión se marcan con los mismos cinco enriquecimientos.

Los enriquecimientos se pueden configurar mediante los siguientes métodos:

Agregar enriquecimientos de mensajes no agrega latencia al enrutamiento de mensajes.

Para probar los enriquecimientos de mensajes, consulte el tutorial de enriquecimiento de mensajes

Limitaciones

• Puede agregar hasta 10 enriquecimientos por centro de IoT para los centros del nivel estándar o básico. En el caso de los centros de IoT del nivel Gratis, puede agregar hasta 2 enriquecimientos.

• En algunos casos, si va a enriquecer un mensaje con un valor establecido en una etiqueta o propiedad en el dispositivo gemelo, el valor se marcará con la ruta de acceso del dispositivo gemelo especificada. Por ejemplo, si un valor de enriquecimiento se establece en $twin.tags.field, los mensajes se marcarán con la cadena "$twin.tags.field", en lugar del valor de ese campo del gemelo. Este comportamiento se produce en los siguientes casos:

  • El centro de IoT está en el nivel básico. Los centros de IoT de nivel básico no admiten dispositivos gemelos.

  • El centro de IoT está en el nivel estándar, pero no existe la ruta de acceso del dispositivo gemelo que se usa para el valor del enriquecimiento. Por ejemplo, si el valor de enriquecimiento se establece en $twin.tags.___location y el dispositivo gemelo no tiene una propiedad ___location en tags, el mensaje se marca con la cadena "$twin.tags.___location".

  • El centro de IoT está en el nivel estándar, pero la ruta de acceso del dispositivo gemelo que se usa para el valor del enriquecimiento se resuelve en un objeto, en lugar de en una propiedad simple. Por ejemplo, si el valor de enriquecimiento se establece en $twin.tags.___location y la propiedad ___location de tags es un objeto que contiene propiedades secundarias como {"building": 43, "room": 503}, el mensaje se estampa con la cadena "$twin.tags.___location".

• Las actualizaciones de un dispositivo gemelo pueden tardar hasta cinco minutos en quedar reflejadas en el valor de enriquecimiento correspondiente.

• El tamaño total del mensaje, incluidos los enriquecimientos, no puede superar los 256 KB. Si el tamaño de un mensaje supera los 256 KB, IoT Hub quitará el mensaje. Puede usar métricas de IoT Hub para identificar y depurar errores cuando se quitan mensajes. Por ejemplo, puede supervisar la métrica de mensajes de telemetría incompatibles (d2c.telemetry.egress.invalid) en las métricas de enrutamiento. Para más información, consulte Supervisión de IoT Hub.

• Los enriquecimientos de mensajes no se aplican a los eventos de cambio de gemelos digitales.

• Los módulos no heredan etiquetas gemelas de sus dispositivos correspondientes. Los enriquecimientos de los mensajes que se originan en módulos de dispositivo (por ejemplo, en módulos de IoT Edge) deben usar las etiquetas gemelas que se establecen en el módulo gemelo.

Precios

Los enriquecimientos de mensajes están disponibles sin cargo adicional. Actualmente, se le cobra cuando envía un mensaje a un centro de IoT. Solo se le cobrará una vez por ese mensaje, incluso si el mensaje va a varios puntos de conexión.

Pasos siguientes

Consulte estos artículos para obtener más información sobre el enrutamiento de mensajes a un centro de IoT:

• Tutorial de enriquecimiento de mensajes

• Uso del enrutamiento de mensajes de IoT Hub para enviar mensajes del dispositivo a la nube a distintos puntos de conexión

• Tutorial: Enrutamiento de IoT Hub