Creación y lectura de mensajes de IoT Hub
Para admitir la interoperabilidad sin problemas entre protocolos, IoT Hub define un conjunto común de características de mensajería que están disponibles en todos los protocolos accesibles desde el dispositivo. Se pueden usar tanto para enrutamiento de mensajes del dispositivo ala nube como de la nube al dispositivo.
Nota
Algunas de las características que se mencionan en este artículo, como la mensajería de la nube al dispositivo, los dispositivos gemelos y la administración de dispositivos, 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.
IoT Hub implementa mensajería de dispositivo a nube mediante un patrón de mensajería de streaming. Los mensajes de dispositivo a nube de IoT Hub son más parecidos a eventos de Event Hubs que a mensajes de Service Bus en que hay un gran volumen de eventos que se pasan a través del servicio que pueden leer varios lectores.
Un mensaje IoT Hub consta de:
Conjunto predeterminado de propiedades del sistema como el que se muestra a continuación.
Un conjunto de propiedades de la aplicación. Diccionario de propiedades de cadena que la aplicación puede definir y a las que puede acceder sin necesidad de deserializar el cuerpo del mensaje. IoT Hub nunca modifica estas propiedades.
Un cuerpo de mensaje, que puede contener cualquier tipo de datos.
Cada protocolo de dispositivo implementa las propiedades de configuración de maneras diferentes. Consulte las guías para desarrolladores de MQTT y AMQP para obtener más información.
Los valores y los nombres de propiedad solo pueden contener caracteres alfanuméricos ASCII, y {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} cuando envía mensajes del dispositivo a la nube usando el protocolo HTTPS o envía mensajes de la nube al dispositivo.
La mensajería de dispositivo a nube con IoT Hub tiene las siguientes características:
Los mensajes de dispositivo a nube son duraderos y se conservan en el punto de conexión messages/events predeterminado de una instancia de IoT Hub hasta siete días.
Los mensajes de dispositivo a nube pueden tener como máximo 256 KB y se pueden agrupar en lotes para optimizar los envíos. Los lotes pueden tener un tamaño máximo de 256 KB.
IoT Hub no permite el particionamiento arbitrario. Los mensajes de dispositivo a nube se dividen en particiones en función de su valor de deviceIdde origen.
Como se explica en Control del acceso a IoT Hub, IoT Hub habilita la autenticación y el control de acceso por dispositivo.
Puede marcar los mensajes con información que se incluye en las propiedades de la aplicación. Para obtener más información, consulte el enriquecimiento de mensajes.
Para más información sobre cómo codificar y descodificar mensajes que se han enviado usando distintos protocolos, consulte SDK de Azure IoT.
Nota
Cada protocolo de IoT Hub proporciona una propiedad de tipo de contenido del mensaje que se respeta al enrutar datos a puntos de conexión personalizados. Para que los datos se controlen correctamente en el destino (por ejemplo, que JSON se trate como una cadena analizable en lugar de como datos binarios codificados en Base64), debe proporcionar el tipo de contenido y el juego de caracteres adecuados para el mensaje.
Para usar el cuerpo del mensaje en una consulta de enrutamiento de IoT Hub, debe proporcionar un objeto JSON válido para el mensaje y establecer la propiedad de tipo de contenido del mensaje en application/json;charset=utf-8.
Un cuerpo de mensaje enrutable y válido puede tener un aspecto similar al siguiente:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Propiedades del sistema de los mensajes de IoT Hub D2C
| Propiedad | Descripción | ¿Lo puede establecer el usuario? | Palabra clave para el enrutamiento de la consulta |
|---|---|---|---|
| message-id | Un identificador configurable por el usuario para el mensaje utilizado para patrones de solicitud y respuesta. Formato: Una cadena que distingue mayúsculas y minúsculas (de hasta 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Sí | messageId |
| iothub-enqueuedtime | Fecha y hora en la que IoT Hub recibió el mensaje del dispositivo a la nube. | No | enqueuedTime |
| user-id | Un identificador que se utiliza para especificar el origen de los mensajes. Cuando IoT Hub genera mensajes, se establece en {iot hub name}. |
Sí | userId |
| iothub-connection-device-id | Un identificador establecido por IoT Hub en los mensajes de dispositivo a nube. Contiene el deviceId del dispositivo que envió el mensaje. | No | connectionDeviceId |
| iothub-connection-module-id | Un identificador establecido por IoT Hub en los mensajes de dispositivo a nube. Contiene el moduleId del dispositivo que envió el mensaje. | No | connectionModuleId |
| iothub-connection-auth-generation-id | Un identificador establecido por IoT Hub en los mensajes de dispositivo a nube. Contiene el valor connectionDeviceGenerationId (como se indica en Propiedades de identidad del dispositivo) del dispositivo que envió el mensaje. | No | connectionDeviceGenerationId |
| iothub-connection-auth-method | Un método de autenticación establecido por IoT Hub en los mensajes de dispositivo a nube. Esta propiedad contiene información sobre el método de autenticación usado para autenticar el dispositivo que envía el mensaje. | No | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Permite al dispositivo enviar la hora de creación de eventos al enviar datos en un lote. | Yes | creation-time-utc |
| iothub-creation-time-utc | Permite al dispositivo enviar la hora de creación de eventos al enviar un único mensaje a la vez. | Yes | creation-time-utc |
| dt-dataschema | El centro de IoT establece este valor en mensajes de dispositivo a la nube. Contiene el id. de modelo del dispositivo establecido en la conexión del dispositivo. | No | $dt-dataschema |
| dt-subject | Nombre del componente que envía los mensajes del dispositivo a la nube. | Sí | $dt-subject |
Propiedades de aplicación de los mensajes de IoT Hub D2C
Un uso común de las propiedades de aplicación es enviar una marca de tiempo desde el dispositivo mediante la propiedad iothub-creation-time-utc para registrar cuándo el dispositivo envió el mensaje. El formato de esta marca de tiempo debe ser UTC sin información de zona horaria. Por ejemplo, 2021-04-21T11:30:16Z es válido y 2021-04-21T11:30:16-07:00 no lo es:
{
"applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
"messageSource":"telemetry",
"deviceId":"sample-device-01",
"schema":"default@v1",
"templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
"enqueuedTime":"2021-01-29T16:45:39.143Z",
"telemetry":{
"temperature":8.341033560421833
},
"messageProperties":{
"iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
},
"enrichments":{}
}
Propiedades del sistema de los mensajes de IoT Hub C2D
| Propiedad | Descripción | ¿La puede definir el usuario? |
|---|---|---|
| message-id | Un identificador configurable por el usuario para el mensaje utilizado para patrones de solicitud y respuesta. Formato: Una cadena que distingue mayúsculas y minúsculas (de hasta 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Sí |
| sequence-number | Un número (exclusivo para cada cola de dispositivo) asignado por IoT Hub a cada mensaje de nube a dispositivo. | No |
| to | Un destino especificado en los mensajes de nube a dispositivo . | No |
| absolute-expiry-time | Fecha y hora de la expiración del mensaje. | Sí |
| correlation-id | Cadena de propiedad en un mensaje de respuesta que normalmente contiene el identificador del mensaje de la solicitud en los patrones de solicitud y respuesta. | Sí |
| user-id | Un identificador que se utiliza para especificar el origen de los mensajes. Cuando IoT Hub genera mensajes, se establece en {iot hub name}. |
Sí |
| iothub-ack | Un generador de mensajes de comentarios. Esta propiedad se usa en los mensajes de nube a dispositivo para solicitar a IoT Hub que genere mensajes de comentarios debido al consumo del mensaje por el dispositivo. Valores posibles: none (valor predeterminado): no se genera ningún mensaje de comentarios, positive: recibe un mensaje de comentarios si el mensaje se completó, negative: recibe un mensaje de comentarios si el mensaje expiró (o si se alcanzó el número máximo de entregas) sin que se complete en el dispositivo, y full: comentarios positivos y negativos. | Sí |
Los nombres de las propiedades del sistema son los siguientes:
Los nombres de las propiedades del sistema varían en función del punto de conexión al que se enrutan los mensajes. Consulte la tabla incluida a continuación para obtener detalles sobre estos nombres.
| Nombre de la propiedad del sistema | Event Hubs | Azure Storage | Azure Service Bus | Event Grid |
|---|---|---|---|---|
| Id. del mensaje | message-id | messageId | MessageId | message-id |
| Id. de usuario | user-id | userId | UserId | user-id |
| Id. de dispositivo de conexión | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Id. de módulo de conexión | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| Id. de generación de la autenticación de conexión | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Método de autenticación de conexión | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | content-type | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | N/D | iothub-enqueuedtime |
| CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Tamaño del mensaje
IoT Hub mide el tamaño de los mensajes de una manera independiente del protocolo, teniendo en cuenta solo la carga real. El tamaño en bytes se calcula como la suma de los siguientes valores:
- El tamaño del cuerpo en bytes.
- El tamaño en bytes de todos los valores de las propiedades del sistema de mensajes.
- El tamaño en bytes de todos los valores y nombres de propiedades del usuario.
Solamente se pueden usar caracteres ASCII para los valores y los nombres de propiedades, por lo que la longitud de las cadenas es igual al tamaño en bytes.
Propiedades contra la suplantación
Para evitar la suplantación de dispositivos en los mensajes de dispositivo a nube, Azure IoT Hub marca todos los mensajes con las siguientes propiedades:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
Las dos primeras contienen los valores deviceId y generationId del dispositivo de origen, tal como se indicó en Propiedades de identidad del dispositivo.
La propiedad iothub-connection-auth-method contiene un objeto JSON serializado con las siguientes propiedades:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Pasos siguientes
- Para información acerca de los límites de tamaño de mensaje en IoT Hub, consulte Cuotas y limitación de IoT Hub.
- Para información sobre cómo crear y leer mensajes de IoT Hub en varios lenguajes de programación, consulte las guías de inicio rápido.
- Para obtener información sobre la estructura de eventos que no son de telemetría generados por IoT Hub, consulte IoT Hub esquemas de eventos que no son de telemetría.