Enriquecimientos 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 los mensajes con información adicional antes de que estos 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
Valor A
Uno o varios puntos de conexión a los que debe aplicarse el enriquecimiento.
La clave es una cadena. Una clave solo puede incluir caracteres alfanuméricos o estos caracteres especiales: guion (-), guion bajo (_) y punto (.).
El valor puede ser cualquiera de los ejemplos siguientes:
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 se admiten las variables $iothubname, $twin.tags, $twin.properties.desired y $twin.properties.reported para el enriquecimiento de mensajes. Además, solo se admiten tipos primitivos para 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 admitido por el enrutamiento de mensajes de IoT Hub, incluidos los ejemplos siguientes:
- telemetría del dispositivo, como la temperatura o la presión
- notificaciones de cambio de dispositivo gemelo: cambios en el dispositivo gemelo
- eventos de ciclo de vida del dispositivo, como cuando se crea o elimina el dispositivo
Puede agregar enriquecimientos a los mensajes que van al punto de conexión incorporado 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 elementos que enriquezcan los mensajes que se publican en Event Grid, para lo que primero se crea 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. Luego, puede configurar elementos que enriquezcan el punto de conexión, para lo que usará 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 métodos siguientes:
| Método | Comando |
|---|---|
| Portal | Azure Portal Consulte el tutorial de enriquecimientos de mensajes |
| Azure CLI | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
La adición de enriquecimientos de mensajes no agrega latencia al enrutamiento de mensajes.
Para probar enriquecimientos de mensajes, consulte el tutorial sobre enriquecimientos de mensajes.
Limitaciones
Puede agregar hasta 10 enriquecimientos por centro de IoT para esos centros en el nivel Estándar o Básico. Para los centros de IoT de nivel Gratis, puede agregar hasta dos enriquecimientos.
En algunos casos, si aplica un enriquecimiento 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 que se ha especificado. 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 casos siguientes:
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 que usa el dispositivo gemelo 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 de ubicación bajo las etiquetas, 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 una propiedad simple. Por ejemplo, si el valor de enriquecimiento se establece en $twin.tags.location y la propiedad de ubicación bajo las etiquetas es un objeto que contiene propiedades secundarias como
{"building": 43, "room": 503}, el mensaje se marca 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 del mensaje supera los 256 KB, el centro de IoT eliminará el mensaje. Puede usar métricas de IoT Hub para identificar y depurar errores cuando se eliminan los 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 obtener más información, vea Supervisión de IoT Hub.
Los mensajes enriquecidos no se aplican a los eventos de cambio de gemelo digital.
Los módulos no heredan las etiquetas gemelas de sus dispositivos correspondientes. Los enriquecimientos de mensajes que se originan en módulos de dispositivo (por ejemplo, de módulos de IoT Edge) deben usar las etiquetas gemelas que se establecen en el módulo gemelo.
Precios
El enriquecimiento de mensajes está disponible sin ningún 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: