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.

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.

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

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

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.

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.