Creación y lectura de mensajes de IoT Hub
Para admitir la interoperabilidad 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. Estas características se pueden usar en mensajes de dispositivo a nube y mensajes de nube a 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 mediante el servicio que pueden leer varios lectores.
Un mensaje IoT Hub consta de:
Un conjunto predeterminado de propiedades del sistema, como se describe más adelante en este artículo.
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. Para más información, consulte las guías para desarrolladores Guía del protocolo MQTT y Guía del protocolo AMQP.
Cuando envíe mensajes de dispositivo a nube usando el protocolo HTTPS o envíe mensajes de nube a dispositivo, los nombres y valores de las propiedades solo pueden contener caracteres alfanuméricos ASCII, además de ! # $ % & ' * + - . ^ _ ` | ~.
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 más información, consulte el artículo sobre el enriquecimiento de mensajes.
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, un objeto JSON tratado como una cadena analizable en lugar de datos binarios codificados en Base64), proporciona el tipo de contenido y el conjunto de caracteres adecuados para el mensaje.
Para usar el cuerpo del mensaje en una consulta de enrutamiento de IoT Hub, proporciona un objeto JSON válido para el mensaje y establece la propiedad de tipo de contenido del mensaje en application/json;charset=utf-8.
En el ejemplo siguiente se muestra un cuerpo de mensaje enrutable válido:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Propiedades del sistema de mensajes de dispositivo a nube
| 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 además de - : . + % _ # * ? ! ( ) , = @ ; $ '. |
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. | 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 la aplicación de mensajes de dispositivo a nube
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, pero 2021-04-21T11:30:16-07:00 no lo es.
{
"applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
"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 mensajes de nube a dispositivo
| 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 además de - : . + % _ # * ? ! ( ) , = @ ; $ '. |
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, el identificador de usuario es el nombre del centro de IoT. | 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í |
Nombres de las propiedades del sistema
Los nombres de las propiedades del sistema varían en función del punto de conexión al que se enrutan los mensajes.
| 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.