Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En este artículo se describe cómo los dispositivos pueden usar el protocolo MQTT para comunicarse con Azure IoT Hub. Los puntos de conexión de dispositivo de IoT Hub admiten la conectividad de dispositivos mediante:
- El protocolo MQTT v3.1.1 en el puerto 8883
- MQTT v3.1.1 a través de WebSocket en el puerto 443
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/Gratuito de IoT Hub, consulte Elegir el nivel y tamaño de IoT Hub adecuado para su solución.
Toda la comunicación de dispositivos con IoT Hub debe protegerse mediante TLS. Por lo tanto, IoT Hub no admite conexiones MQTT no seguras a través del puerto 1883.
Comparación de la compatibilidad con MQTT en IoT Hub y Event Grid
IoT Hub no es un agente MQTT completo, así que no se admite su uso con todos los comportamientos que se especifican en la norma MQTT v3.1.1. Si la solución necesita un agente MQTT hospedado en la nube, use Azure Event Grid en su lugar. Event Grid permite la comunicación bidireccional entre clientes MQTT en temas jerárquicos flexibles mediante un modelo de mensajería de publicación y suscripción. También le permite enrutar mensajes MQTT a otros servicios de Azure o puntos de conexión personalizados para su posterior procesamiento.
En la tabla siguiente se resumen las diferencias en la compatibilidad con MQTT entre los dos servicios:
IoT Hub | Event Grid |
---|---|
Modelo de servidor cliente con acoplamiento estricto entre dispositivos y aplicaciones en la nube. | Modelo de publicación y suscripción que desacopla publicadores y suscriptores. |
Soporte limitado de características para MQTT v3.1.1. No se ha planeado más compatibilidad con características. | Compatibilidad con el protocolo MQTT v3.1.1 y v5, con más compatibilidad con características y cumplimiento del sector planeado. |
Temas estáticos y predefinidos. | Temas jerárquicos personalizados con compatibilidad con caracteres comodín. |
No se admiten las transmisiones de la nube hacia el dispositivo ni la comunicación entre dispositivos. | Admite difusión del dispositivo a la nube, de la nube a dispositivo, de alta distribución y patrones de comunicación de dispositivo a dispositivo. |
Tamaño máximo de mensaje de 256 KB. | Tamaño máximo de mensaje de 512 KB. |
Conexión a IoT Hub
Un dispositivo puede usar el protocolo MQTT para conectarse a un centro de IoT mediante una de las opciones siguientes:
- Los SDK de dispositivo IoT de Azure.
- El protocolo MQTT directamente.
Muchos firewalls corporativos y educativos bloquean el puerto MQTT (puerto TCP 8883). Si no puede abrir el puerto 8883 en el firewall, use MQTT a través de WebSockets. MQTT sobre WebSockets se comunica a través del puerto 443, que casi siempre está abierto. Para obtener información sobre cómo especificar los protocolos MQTT y MQTT sobre WebSockets cuando use los SDK de IoT de Azure, consulte Uso de los SDK de dispositivo.
Uso de los SDK de dispositivo
Los SDK de dispositivo IoT de Azure que admiten el protocolo MQTT están disponibles para Java, Node.js, C, C# y Python. En los SDK de dispositivo, las conexiones a los centros de IoT se establecen mediante el mecanismo de autenticación que se establezca. Para utilizar el protocolo MQTT, el parámetro de protocolo de cliente debe establecerse en MQTT. También puede especificar MQTT sobre WebSockets en el parámetro de protocolo de cliente. De forma predeterminada, los SDK de dispositivo se conectan a un centro de IoT con la marca CleanSession establecida en 0 y usan QoS 1 para el intercambio de mensajes con el centro de IoT. Aunque es posible configurar QoS 0 para un intercambio de mensajes más rápido, debe tener en cuenta que la entrega no está garantizada y no se reconoce. Por esta razón, QoS 0 a menudo se denomina "dispare y olvídese".
Cuando un dispositivo se conecta a un centro de IoT, los SDK de dispositivo proporcionan métodos que permiten al dispositivo intercambiar mensajes con un centro de IoT.
La tabla siguiente contiene vínculos a ejemplos de código para cada idioma admitido y especifica el parámetro que se debe utilizar para establecer una conexión con Azure IoT Hub mediante el protocolo MQTT o MQTT sobre WebSockets.
Idioma | Parámetro de protocolo MQTT | Parámetro de protocolo MQTT sobre WebSockets |
---|---|---|
Node.js | azure-iot-device-mqtt.Mqtt | azure-iot-device-mqtt.MqttWs |
Java | IotHubClientProtocol.MQTT | IotHubClientProtocol.MQTT_WS |
C | MQTT_Protocol | MQTT_WebSocket_Protocol |
C# | TransportType.Mqtt | TransportType.Mqtt recurre a MQTT sobre WebSockets si se produce un error en MQTT. Para especificar MQTT exclusivamente sobre WebSockets, utilize TransportType.Mqtt_WebSocket_Only. |
Python | Usa MQTT de forma predeterminada | Para crear el cliente, agregue websockets=True en la llamada. |
En el fragmento siguiente se muestra cómo especificar el protocolo MQTT a través de WebSockets al usar el SDK de Azure IoT Node.js:
var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);
En el fragmento siguiente se muestra cómo especificar el protocolo MQTT a través de WebSockets al usar el SDK de Python de Azure IoT:
from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)
Importante
En este artículo se incluyen los pasos para conectar un dispositivo mediante una firma de acceso compartido, también denominada autenticación de clave simétrica. Este método de autenticación es cómodo para probar y evaluar, pero autenticar un dispositivo mediante certificados X.509 es un enfoque más seguro. Para más información, consulte Procedimientos recomendados de seguridad para soluciones > de IoT Seguridad de la conexión.
Tiempo de espera de mantenimiento de conexión predeterminado
Para asegurarse de que una conexión de cliente a una conexión de IoT Hub permanece activa, tanto el servicio como el cliente envían periódicamente un ping de mantenimiento activo entre sí. Si usa uno de los SDK de dispositivo, el cliente envía un mensaje keep-alive en el intervalo definido en la tabla siguiente:
Idioma | Intervalo de mantenimiento de conexión predeterminado | Configurable |
---|---|---|
Node.js | 180 Segundos | No |
Java | 230 Segundos | No |
C | 240 segundos | Sí |
C# | 300 segundos* | Sí |
Python | 60 segundos | Sí |
*El SDK de C# define el valor predeterminado de la propiedad KeepAliveInSeconds de MQTT como 300 segundos. En realidad, el SDK envía una solicitud de ping cuatro veces por duración de mantenimiento activo establecida. En otras palabras, el SDK envía un ping de conexión una vez cada 75 segundos.
Después de la especificación MQTT v3.1.1, el intervalo de ping de mantenimiento activo de IoT Hub es 1,5 veces el valor de mantenimiento activo del cliente; sin embargo, IoT Hub limita el tiempo de espera máximo del servidor a 29,45 minutos (1 767 segundos).
Por ejemplo, un dispositivo que usa el SDK de Java envía el ping de Keep-Alive y después pierde la conectividad de red. 230 segundos más tarde, el dispositivo pierde el ping de Keep-Alive porque está sin conexión. Sin embargo, IoT Hub no cierra la conexión de inmediato, espera otros (230 * 1.5) - 230 = 115
segundos antes de desconectar el dispositivo con el error 404104 DeviceConnectionClosedRemotely.
El valor de Keep-Alive máximo del cliente que puede establecer es 1767 / 1.5 = 1177
segundos. Cualquier tráfico restablece el valor de keep-alive. Por ejemplo, una actualización correcta del token de firma de acceso compartido (SAS) restablece el mantenimiento activo.
Migración de una aplicación de dispositivo de AMQP a MQTT
Si usas los SDKs de dispositivos, para cambiar de AMQP a MQTT, necesitas modificar el parámetro de protocolo en la inicialización del cliente.
Al cambiar de AMQP a MQTT, compruebe los siguientes elementos:
AMQP devuelve errores para muchas condiciones, mientras que MQTT finaliza la conexión. Como resultado, es posible que tenga que cambiar la lógica de control de excepciones.
MQTT no admite la operación de rechazo cuando recibe mensajes de nube a dispositivo. Si la aplicación back-end necesita recibir una respuesta de la aplicación de dispositivo, considere la posibilidad de usar métodos directos.
No se admite el uso de AMQP en el SDK de Python.
Uso del protocolo MQTT directamente desde un dispositivo
Si un dispositivo no puede usar los SDK de dispositivo IoT, todavía puede conectarse a los puntos de conexión del dispositivo público mediante el protocolo MQTT en el puerto 8883.
Importante
En este artículo se incluyen los pasos para conectar un dispositivo mediante una firma de acceso compartido, también denominada autenticación de clave simétrica. Este método de autenticación es cómodo para probar y evaluar, pero autenticar un dispositivo mediante certificados X.509 es un enfoque más seguro. Para más información, consulte Procedimientos recomendados de seguridad para soluciones > de IoT Seguridad de la conexión.
En el paquete CONNECT el dispositivo debe usar los siguientes valores:
Para el campo ClientId, use deviceId.
Para el campo Nombre de usuario use
{iotHub-hostname}/{device-id}/?api-version=2021-04-12
, donde{iotHub-hostname}
es elCName
completo del centro de IoT.Por ejemplo, si el nombre del centro de IoT es contoso.azure-devices.net y si el nombre del dispositivo es MyDevice01, el campo Nombre de usuario contiene:
contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12
Para evitar un comportamiento inesperado, incluya el atributo api-version en el campo.
Para el campo Contraseña, utilice un token SAS. En el fragmento de código siguiente se muestra el formato del token de SAS:
SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}
Nota:
Si usa la autenticación de certificados X.509, no se requieren contraseñas de token de SAS. Para más información, consulte Tutorial: Creación y carga de certificados para pruebas y siga las instrucciones de código de la sección Configuración de TLS.
Para obtener más información sobre cómo generar tokens de SAS, consulte la sección Uso de tokens de SAS como dispositivo de Control del acceso a IoT Hub mediante firmas de acceso compartido.
También puede usar la extensión de Azure IoT Hub para Visual Studio Code o el comando de extensión de la CLI az iot hub generate-sas-token para generar un token de SAS. Después, puede copiar y pegar el token de SAS en su propio código con fines de prueba.
La extensión genera un token de SAS con la estructura siguiente:
HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802
La parte de este token que se debe usar como el campo Password para conectarse con MQTT es:
SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802
La aplicación de dispositivo puede especificar un mensaje Will en el paquete CONNECT . La aplicación de dispositivo debe usar devices/{device-id}/messages/events/
o devices/{device-id}/messages/events/{property-bag}
como nombre del tema Will para definir los mensajes Will que se reenviarán como un mensaje de telemetría. En este caso, si la conexión de red se cierra, pero no se recibió anteriormente un paquete DISCONNECT desde el dispositivo, se enviará el mensaje Will, que se suministra en el paquete CONNECT, al canal de telemetría desde IoT Hub. El canal de telemetría puede ser el punto de conexión Eventos predeterminado o un punto de conexión personalizado que se define por el enrutamiento de IoT Hub. El mensaje tiene la propiedad iothub-MessageType con un valor de Will asignado.
Uso del protocolo MQTT directamente desde un módulo
También puede conectarse a IoT Hub a través de MQTT mediante una identidad de módulo. Este enfoque es similar a la conexión como dispositivo, pero debe usar los siguientes valores:
Establezca el identificador de cliente en
{device-id}/{module-id}
.Si se autentica con el nombre de usuario y la contraseña, establezca el nombre de usuario en
<hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12
. Si usa SAS, use el token de SAS asociado a la identidad del módulo como contraseña.Use
devices/{device-id}/modules/{module-id}/messages/events/
como tema para publicar los datos de telemetría.Usa
devices/{device-id}/modules/{module-id}/messages/events/
como el tema Will.Use
devices/{device-id}/modules/{module-id}/#
como tema para recibir mensajes.Los temas GET y PATCH del gemelo son los mismos para módulos y dispositivos.
El tema de estado del gemelo es el mismo para módulos y dispositivos.
Para más información sobre el uso de MQTT con módulos, consulte el punto de conexión MQTT del hub de IoT Edge.
Ejemplos con MQTT sin un SDK de dispositivo IoT de Azure
El Repositorio de ejemplo de MQTT para IoT contiene ejemplos de C/C++, Python y la CLI que muestran cómo enviar mensajes de telemetría, recibir mensajes de la nube al dispositivo y usar dispositivos gemelos sin usar los SDK de dispositivo de Azure.
Los ejemplos de C/C++ usan la biblioteca de Eclipse Mosquitto, el ejemplo de Python usa Eclipse Paho y los ejemplos de la CLI usan mosquitto_pub
.
Para más información, consulte Tutorial: Uso de MQTT para desarrollar un cliente de dispositivo IoT sin usar un SDK de dispositivo.
Configuración de TLS
Para usar el protocolo MQTT directamente, el cliente debe conectarse a través de TLS 1.2. Los intentos de omitir este paso producirán errores de conexión.
Para establecer una conexión TLS, es posible que tenga que descargar y hacer referencia al certificado raíz G2 global de DigiCert que usa Azure. Para obtener más información sobre este certificado, consulte el sitio web de Digicert.
En el ejemplo siguiente se muestra cómo implementar esta configuración usando la versión en Python de la biblioteca Paho MQTT.
En primer lugar, instale la biblioteca Paho desde el entorno de línea de comandos:
pip install paho-mqtt
A continuación, implemente el cliente en un script de Python. Reemplace estos marcadores de posición en el siguiente fragmento de código:
<local path to digicert.cer>
es la ruta de acceso a un archivo local que contiene el certificado raíz de DigiCert. Puede crear este archivo copiando la información de certificado de certs.c en el SDK de Azure IoT para C. Incluya las líneas-----BEGIN CERTIFICATE-----
y-----END CERTIFICATE-----
, quite las marcas"
al principio y al final de cada línea, y quite los caracteres\r\n
al final de cada línea.<device id from device registry>
es el ID de un dispositivo que agregaste a tu IoT hub.<generated SAS token>
es un token de SAS para el dispositivo que se creó como se describió anteriormente en este artículo.<iot hub name>
el nombre del centro de IoT.
from paho.mqtt import client as mqtt
import ssl
path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"
def on_connect(client, userdata, flags, rc):
print("Device connected with result code: " + str(rc))
def on_disconnect(client, userdata, rc):
print("Device disconnected with result code: " + str(rc))
def on_publish(client, userdata, mid):
print("Device sent message")
client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)
client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
device_id + "/?api-version=2021-04-12", password=sas_token)
client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)
client.connect(iot_hub_name+".azure-devices.net", port=8883)
client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()
Para autenticarse mediante un certificado de dispositivo, actualice el fragmento de código anterior con los cambios especificados en el siguiente fragmento de código. Para obtener más información sobre cómo prepararse para la autenticación basada en certificados, consulte la sección Obtención de un certificado de entidad de certificación X.509 de Autenticación de identidades con certificados X.509.
# Create the client as before
# ...
# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
device_id + "/?api-version=2021-04-12", password=None)
# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)
Envío de mensajes del dispositivo a la nube
Una vez que un dispositivo se ha conectado, puede enviar mensajes a IoT Hub con devices/{device-id}/messages/events/
o devices/{device-id}/messages/events/{property-bag}
como Nombre de tema. El elemento {property-bag}
permite al dispositivo enviar mensajes con otras propiedades en un formato con codificación URL. Por ejemplo:
RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…
Este elemento {property_bag}
usa la misma codificación que se usa para las cadenas de consulta en el protocolo HTTPS.
Si va a enrutar mensajes D2C a una cuenta de Azure Storage y desea usar la codificación JSON, debe especificar la información de codificación de contenido y tipo de contenido, incluido $.ct=application%2Fjson&$.ce=utf-8
, como parte de la {property_bag}
mencionada en la nota anterior.
Nota:
El formato de estos atributos es específico del protocolo. IoT Hub convierte estos atributos en sus propiedades del sistema correspondientes. Para obtener más información, consulte la sección Propiedades del sistema de IoT Hub sintaxis de consulta de enrutamiento de mensajes.
En la lista siguiente se resumen los comportamientos específicos de la implementación de MQTT de IoT Hub:
El uso de mensajes QoS 2 no se admite en IoT Hub. Si una aplicación de dispositivo publica un mensaje con QoS 2, IoT Hub cierra la conexión de red.
IoT Hub no conserva
Retain
mensajes. Si un dispositivo envía un mensaje con la marca RETAIN establecida en 1, IoT Hub agrega la propiedad de aplicación mqtt-retain al mensaje. En este caso, en lugar de conservar el mensaje retenido, IoT Hub lo pasa a la aplicación back-end.IoT Hub solo admite una conexión MQTT activa por dispositivo. Cualquier nueva conexión MQTT en nombre del mismo identificador de dispositivo hace que IoT Hub quite la conexión existente y escriba 400027 ConnectionForcelyClosedOnNewConnection en los registros de IoT Hub.
Para enrutar los mensajes en función del cuerpo del mensaje, agregue primero la propiedad
ct
al final del tema MQTT y establezca su valorapplication/json;charset=utf-8
en como se muestra en el ejemplo siguiente. Para obtener más información sobre el enrutamiento de mensajes en función de las propiedades del mensaje o el cuerpo del mensaje, consulte la documentación de Sintaxis de las consultas de enrutamiento de mensajes de IoT Hub.devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8
Para más información, consulte Envío y recepción de mensajes con IoT Hub.
Recepción de mensajes de nube a dispositivo
Para recibir mensajes de IoT Hub, un dispositivo debe suscribirse usando devices/{device-id}/messages/devicebound/#
como un filtro de tema. El carácter comodín #
de varios niveles del filtro de tema permite al dispositivo recibir más propiedades en el nombre del tema. IoT Hub no permite el uso de los comodines #
o ?
para filtrar subtemas. IoT Hub no es un agente de mensajería de publicación y suscripción de uso general, solo admite los nombres de tema documentados y los filtros de tema. Un dispositivo solo puede suscribirse a cinco temas a la vez.
El dispositivo no recibe ningún mensaje de IoT Hub hasta que se suscribe correctamente al punto de conexión específico del dispositivo, representado por el filtro del tema devices/{device-id}/messages/devicebound/#
. Una vez establecida una suscripción, el dispositivo recibe mensajes de nube a dispositivo que se le enviaron después del tiempo de la suscripción. Si el dispositivo se conecta con la marca CleanSession establecida en 0, la suscripción se conserva entre distintas sesiones. En este caso, la próxima vez que el dispositivo se conecte con CleanSession 0, este recibirá los mensajes pendientes que se le han enviado mientras estaba desconectado. Si el dispositivo usa la marca CleanSession establecida en 1, no recibe los mensajes de IoT Hub hasta que se suscribe al punto de conexión del dispositivo.
IoT Hub entrega los mensajes con el Nombre del temadevices/{device-id}/messages/devicebound/
o devices/{device-id}/messages/devicebound/{property-bag}
si hay propiedades de mensaje. {property-bag}
contiene pares clave-valor codificados en URL de propiedades del mensaje. Las propiedades de la aplicación y del sistema configuradas por el usuario (como messageId o correlationId) son las únicas que se incluyen en el paquete de propiedades. Los nombres de propiedad del sistema tienen el prefijo $ ; las propiedades de aplicaciones utilizan el nombre de propiedad original sin prefijo. Para obtener más información sobre el formato de la bolsa de propiedades, consulte Envío de mensajes de dispositivo a la nube.
En los mensajes de la nube al dispositivo, los valores del contenedor de propiedades se representan como en la tabla siguiente:
Valor de propiedad | Representación | Descripción |
---|---|---|
null |
key |
Solo aparece la clave en el contenedor de propiedades |
cadena vacía | key= |
Clave seguida de un signo igual sin valor |
valor que no es nulo ni está vacío | key=value |
Clave seguida de un signo igual y un valor |
En el ejemplo siguiente se muestra un contenedor de propiedades que contiene tres propiedades de la aplicación: prop1 con un valor de null
; prop2, que es una cadena vacía (""); y prop3 que tiene como valor "a string".
/?prop1&prop2=&prop3=a%20string
Cuando una aplicación de dispositivo se suscribe a un tema con QoS 2, IoT Hub concede el nivel máximo de QoS 1 en el paquete SUBACK . Después de eso, IoT Hub envía mensajes al dispositivo con QoS 1.
Recuperación de propiedades de dispositivos gemelos
En primer lugar, un dispositivo se suscribe a $iothub/twin/res/#
para recibir las respuestas de la operación. A continuación, envía un mensaje en blanco al tópico $iothub/twin/GET/?$rid={request id}
, con un valor poblado para el identificador de solicitud. El servicio envía entonces un mensaje de respuesta que contiene los datos del dispositivo gemelo del tema $iothub/twin/res/{status}/?$rid={request-id}
, con el mismo identificador de solicitud que la solicitud.
El ID de la solicitud puede ser cualquier valor válido para un valor de propiedad de mensaje, y el estado se valida como un número entero. Para más información, consulte Envío y recepción de mensajes con IoT Hub.
El cuerpo de la respuesta contiene la sección de propiedades del dispositivo gemelo, como se muestra en la siguiente respuesta de ejemplo:
{
"desired": {
"telemetrySendFrequency": "5m",
"$version": 12
},
"reported": {
"telemetrySendFrequency": "5m",
"batteryLevel": 55,
"$version": 123
}
}
Los códigos de estado posibles son:
Estado | Descripción |
---|---|
200 | Éxito |
429 | Demasiadas solicitudes (limitadas). Para obtener más información, consulte Cuotas y regulación de IoT Hub. |
5** | Errores del servidor |
Para más información, consulte Información y uso de dispositivos gemelos en IoT Hub.
Actualización de las propiedades notificadas del dispositivo gemelo
Para actualizar las propiedades notificadas, el dispositivo emite una solicitud a IoT Hub publicando en un tema MQTT designado. Una vez que IoT Hub procesa la solicitud, responde con el estado de éxito o fallo de la operación de actualización, mediante la publicación en otro tópico. El dispositivo puede suscribirse a este tema para recibir notificaciones sobre el resultado de la solicitud de actualización del gemelo. Para implementar este tipo de interacción de solicitud/respuesta en MQTT, el dispositivo proporciona un identificador de solicitud ($rid
) en su solicitud de actualización inicial. A continuación, este identificador de solicitud se incluye en la respuesta de IoT Hub para permitir que el dispositivo ponga en correlación la respuesta a la solicitud correcta.
La secuencia siguiente describe cómo un dispositivo actualiza las propiedades notificadas en el dispositivo gemelo de IoT Hub:
Un dispositivo se suscribe primero al
$iothub/twin/res/#
tema para permitir que reciba respuestas de IoT Hub.Un dispositivo envía un mensaje que contiene la actualización del dispositivo gemelo al tema
$iothub/twin/PATCH/properties/reported/?$rid={request-id}
. Este mensaje incluye un valor de identificador de solicitud.Después, el servicio envía un mensaje de respuesta que contiene el nuevo valor de ETag de la colección de propiedades notificadas del tema
$iothub/twin/res/{status}/?$rid={request-id}
. Este mensaje de respuesta usa el mismo identificador de solicitud que la solicitud.
En el cuerpo del mensaje de solicitud, se incluye un documento JSON donde, a su vez, se incluyen los nuevos valores para las propiedades de las que se informa. En el documento JSON, cada miembro actualiza o agrega al miembro correspondiente en el documento del dispositivo gemelo. La configuración de un miembro en null
elimina el miembro del objeto contenedor. Por ejemplo:
{
"telemetrySendFrequency": "35m",
"batteryLevel": 60
}
Los códigos de estado posibles son:
Estado | Descripción |
---|---|
204 | Correcto (sin contenido) |
400 | Solicitud incorrecta. JSON con formato incorrecto |
429 | Demasiadas solicitudes (limitadas), según las cuotas y la limitación de IoT Hub |
5** | Errores del servidor |
El siguiente fragmento de código Python demuestra el proceso de actualización de las propiedades de los informes gemelos a través de MQTT utilizando el cliente MQTT Paho:
from paho.mqtt import client as mqtt
# authenticate the client with IoT Hub (not shown here)
client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
rid, twin_reported_property_patch, qos=0)
Cuando el proceso de actualización de propiedades notificadas por el gemelo se realiza correctamente, IoT Hub publica un mensaje en el tema siguiente: $iothub/twin/res/204/?$rid=1&$version=6
, donde 204
es el código de estado que indica que se ha realizado correctamente, $rid=1
corresponde al identificador de solicitud proporcionado por el dispositivo en el código y $version
corresponde a la versión de la sección de propiedades notificadas de dispositivos gemelos después de la actualización.
Para más información, consulte Información y uso de dispositivos gemelos en IoT Hub.
Recibir notificaciones de actualización de propiedades deseadas
Cuando se conecta un dispositivo, IoT Hub envía notificaciones al tema $iothub/twin/PATCH/properties/desired/?$version={new-version}
, que contiene la actualización realizada por la solución de back-end. Por ejemplo:
{
"telemetrySendFrequency": "5m",
"route": null,
"$version": 8
}
Para las actualizaciones de propiedad, los valores null
significan que se elimina el miembro del objeto JSON. Además, el elemento $version
se usa para indicar la nueva versión de la sección de propiedades deseadas del gemelo.
Importante
IoT Hub genera notificaciones de cambio solo si los dispositivos están conectados. Asegúrese de implementar el flujo de reconexión de dispositivos para mantener las propiedades deseadas sincronizadas entre IoT Hub y la aplicación de dispositivo.
Para más información, consulte Información y uso de dispositivos gemelos en IoT Hub.
Respuesta a un método directo
En primer lugar, un dispositivo se suscribe a $iothub/methods/POST/#
. IoT Hub envía solicitudes de método al tema $iothub/methods/POST/{method-name}/?$rid={request-id}
, con un valor JSON válido o un cuerpo vacío.
Para responder, el dispositivo envía un mensaje con un valor JSON válido o un cuerpo vacío al tema $iothub/methods/res/{status}/?$rid={request-id}
. En este mensaje, el identificador de solicitud debe coincidir con el del mensaje de solicitud y el estado debe ser un número entero.
Para obtener más información, vea el artículo Conocimiento e invocación de los métodos directos de IoT Hub.
Pasos siguientes
Para más información sobre el uso de MQTT, consulte: