Communique avec un hub IoT à l’aide du protocole MQTT

Article
06/27/2023

Cet article décrit comment les appareils peuvent utiliser des comportements MQTT pris en charge pour communiquer avec Azure IoT Hub. Grâce à IoT Hub, les appareils peuvent communiquer avec les points de terminaison d’appareil IoT Hub à l’aide de :

MQTT v3.1.1 sur le port TCP 8883
MQTT v3.1.1 sur WebSocket sur le port 443.

Remarque

Certaines des fonctionnalités mentionnées dans cet article, comme la messagerie cloud-à-appareil, les jumeaux d’appareil et la gestion des appareils, sont disponibles uniquement dans le niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.

Toutes les communications des appareils avec IoT Hub doivent être sécurisées à l’aide de TLS/SSL. Par conséquent, IoT Hub ne prend pas en charge les connexions non sécurisées sur le port TCP 1883.

Comparer la prise en charge de MQTT dans IoT Hub et Event Grid

IoT Hub n’est pas un répartiteur MQTT complet et ne prend pas en charge tous les comportements spécifiés dans la norme MQTT v3.1.1. Si votre solution a besoin de MQTT, nous vous recommandons la prise en charge de MQTT dans Azure Event Grid. Event Grid permet la communication bidirectionnelle entre clients MQTT sur des rubriques hiérarchiques flexibles à l’aide d’un modèle de messagerie pub-sub. Event Grid vous permet également de router vos messages MQTT vers des services Azure ou des points de terminaison personnalisés pour un traitement ultérieur.

Le tableau suivant explique les différences entre les deux services quant à la prise en charge de MQTT :

IoT Hub	Event Grid
Modèle client-serveur avec couplage étroit entre les appareils et les applications cloud.	Modèle publier-abonner qui dissocie les éditeurs et abonnés.
Prise en charge limitée des fonctionnalités pour MQTT v3.1.1 et prise en charge limitée des fonctionnalités pour la préversion de MQTT v5. La prise en charge d’autres fonctionnalités n’est pas prévue.	Prise en charge des protocoles MQTT v3.1.1 et v5, avec davantage de prise en charge de fonctionnalités et de conformité du secteur prévues.
Rubriques statiques et prédéfinies.	Rubriques hiérarchiques personnalisées avec prise en charge des caractères génériques.
Aucune prise en charge des diffusions cloud-à-appareil et de la communication appareil-à-appareil.	Prend en charge les diffusions appareil-à-cloud, les diffusions cloud-à-appareil à grande dispersion et les modèles de communication appareil-à-appareil.
Taille de message maximale : 256 Ko.	Taille de message maximale : 512 Ko.

Connexion à IoT Hub

Un appareil peut utiliser le protocole MQTT pour se connecter à un hub IoT en utilisant l’une des options suivantes :

Les Kits de développement logiciel (SDK) Azure IoT.
Protocole MQTT directement.

Le port MQTT (port TCP 8883) est bloqué dans de nombreux environnements réseau professionnels et scolaires. Si vous ne pouvez pas ouvrir le port 8883 dans votre pare-feu, nous vous recommandons d’utiliser MQTT sur WebSockets. MQTT sur WebSockets communique sur le port 443, qui est presque toujours ouvert dans les environnements réseau. Pour apprendre à spécifier les protocoles MQTT et MQTT sur WebSockets quand vous utilisez les SDK Azure IoT, consultez Utilisation des SDK d’appareils.

Utilisation des Kits device SDK

Les SDK d’appareil qui prennent en charge le protocole MQTT sont disponibles pour Java, Node.js, C, C# et Python. Les SDK d’appareil utilisent le mécanisme d’authentification choisi pour établir une connexion à un hub IoT. Pour utiliser le protocole MQTT, le paramètre de protocole du client doit être défini sur MQTT. Vous pouvez également spécifier MQTT sur WebSockets dans le paramètre de protocole client. Par défaut, les Kits device SDK se connectent à un IoT Hub avec l’indicateur CleanSession défini sur 0, et utilisent QoS 1 pour l’échange de messages avec l’IoT Hub. Bien qu’il soit possible de configurer QoS 0 pour accélérer l’échange de messages, il faut noter que la remise n’est ni garantie, ni reconnue par accusé de réception. C’est pourquoi la solution QoS 0 est souvent appelée « fire and forget » (tire et oublie).

Quand un appareil est connecté à un hub IoT, les SDK d’appareils fournissent des méthodes qui permettent à l’appareil d’échanger des messages avec un hub IoT.

Le tableau suivant contient des liens vers des exemples de code pour chaque langage pris en charge. Il spécifie le paramètre à utiliser pour établir une connexion à IoT Hub à l’aide du protocole MQTT ou MQTT sur WebSockets.

Langage	Paramètre de protocole MQTT	Paramètre de protocole MQTT sur 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 utilise MQTT sur WebSockets en cas d’échec de MQTT. Pour spécifier MQTT sur WebSockets uniquement, utilisez TransportType.Mqtt_WebSocket_Only.
Python	Prend en charge MQTT par défaut	Ajoutez `websockets=True` dans l’appel pour créer le client

Le fragment suivant montre comment spécifier le protocole MQTT sur WebSockets quand vous utilisez le SDK Node.js Azure IoT :

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

Le fragment suivant montre comment spécifier le protocole MQTT sur WebSockets quand vous utilisez le SDK Python Azure IoT :

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

Délai de maintien de connexion par défaut

Pour maintenir la connexion entre un client et IoT Hub, le service et le client s'envoient régulièrement une requête ping de maintien de connexion. Le client qui utilise le SDK IoT envoie une requête ping de maintien de connexion à l’intervalle défini dans le tableau suivant :

Langage	Intervalle de maintien de connexion par défaut	Configurable
Node.js	180 secondes	Non
Java	230 secondes	Oui
C	240 secondes	Oui
C#	300 secondes*	Oui
Python	60 secondes	Oui

*Le SDK C# définit la valeur de la propriété MQTT KeepAliveInSeconds sur 300 secondes. En fait, le SDK envoie une requête ping quatre fois par durée de maintien de connexion définie. En d’autres termes, le Kit de développement logiciel (SDK) envoie un test ping keep-alive une fois toutes les 75 secondes.

Conformément à la spécification MQTT v3.1.1, l’intervalle ping de maintien de connexion d’IoT Hub correspond à 1,5 fois la valeur du maintien de connexion du client. En revanche, IoT Hub limite le délai d’expiration maximal côté serveur à 29,45 minutes (1767 secondes). Cette limite existe car tous les services Azure sont liés au délai d’inactivité TCP de l’équilibreur de charge Azure, qui s’élève à 29,45 minutes.

Par exemple, un appareil utilisant le kit de développement logiciel (SDK) Java envoie une requête ping de maintien de connexion, puis perd la connectivité réseau. 230 secondes plus tard, l'appareil manque la requête ping de maintien de connexion car il est hors connexion. Toutefois, IoT Hub ne ferme pas immédiatement la connexion. Il attend (230 * 1.5) - 230 = 115 secondes de plus avant de déconnecter l'appareil en renvoyant l'erreur 404104 DeviceConnectionClosedRemotely.

La valeur de maintien de connexion maximale que vous pouvez définir pour le client est de 1767 / 1.5 = 1177 secondes. Tout trafic réinitialise le maintien de la connexion. Par exemple, une actualisation réussie du jeton de signature d’accès partagé (SAP) réinitialise le maintien de connexion.

Migration d’une application d’appareil d’AMQP vers MQTT

Si vous utilisez les SDK d’appareil, le passage du protocole AMQP au protocole MQTT nécessite de modifier le paramètre de protocole dans l’initialisation du client comme indiqué précédemment.

Lors de cette opération, vérifiez les éléments suivants :

AMQP retourne des erreurs pour nombreuses conditions, tandis que MQTT met fin à la connexion. Par conséquent, votre logique de gestion des exceptions peut nécessiter certaines modifications.
MQTT ne prend pas en charge les opérations de refus lors de la réception de messages cloud-à-appareil. Si votre application de back-end doit recevoir une réponse de l’application pour appareil, envisagez d’utiliser des méthodes directes.
AMQP n’est pas pris en charge dans le SDK Python.

Utilisation directe du protocole MQTT (en tant qu’appareil)

Si un appareil ne peut pas utiliser les SDK d’appareil, il peut toujours se connecter aux points de terminaison d’appareil publics à l’aide du protocole MQTT sur le port 8883.

Dans le paquet CONNECT, l’appareil doit utiliser les valeurs suivantes :

Pour le champ ClientId, utilisez le deviceId.
Dans le champ Nom d'utilisateur, utilisez {iotHub-hostname}/{device-id}/?api-version=2021-04-12, où {iotHub-hostname} est le CName complet du hub IoT.

Par exemple, si le nom de votre hub IoT est contoso.azure-devices.net et si le nom de votre appareil est MyDevice01, le champ Username complet doit contenir :

contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

Il est recommandé d’inclure api-version dans le champ. Dans le cas contraire, cela peut provoquer des comportements inattendus.
Dans le champ Password, utilisez un jeton SAP. Le format du jeton SAP est identique pour les protocoles HTTPS et AMQP :

SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

Notes

Si vous utilisez l’authentification par certificat X.509, les mots de passe de jeton SAS ne sont pas obligatoires. Pour plus d’informations, consultez le Tutoriel : Créer et charger des certificats pour les tests et suivez les instructions de code fournies dans la section de configuration TLS/SSL.

Pour plus d’informations sur la façon de générer des jetons SAP, consultez la section Utiliser des jetons SAP comme appareil de Contrôler l’accès à IoT Hub à l’aide de signatures d’accès partagé.

Vous pouvez également utiliser Azure IoT Hub extension pour Visual Studio Code multiplate-forme ou la commande d’extension CLI az iot hub generate-sas-token pour générer rapidement un jeton de signature d’accès partagé (SAP). Vous pouvez ensuite copier et coller le jeton SAP dans votre propre code à des fins de test.

Pour un tutoriel sur l’utilisation directe de MQTT, consultez Utiliser MQTT pour développer un client d’appareil IoT sans utiliser de kit de développement logiciel (SDK) d’appareils.

Utiliser l’extension Azure IoT Hub pour Visual Studio Code

Dans la barre latérale, développez le nœud Appareils sous la section Azure IoT Hub.
Cliquez avec le bouton droit sur votre appareil IoT et sélectionnez Générer un jeton SAS pour l’appareil dans le menu contextuel.
Entrez le délai d’expiration, en heures, pour le jeton SAP dans la zone d’entrée, puis sélectionnez la clé Entrée.
Le jeton SAP est créé et copié dans le Presse-papiers.

Le jeton SAP généré présente la structure suivante :

HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

La partie de ce jeton à utiliser dans le champ Password (Mot de passe) pour la connexion avec le protocole MQTT est :

SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

L’application de l’appareil peut spécifier un message Will dans le paquet CONNECTER. L’application de l’appareil doit utiliser devices/{device-id}/messages/events/ ou devices/{device-id}/messages/events/{property-bag} comme nom de rubrique Will pour définir des messages Will à transmettre en tant que message de télémétrie. Dans ce cas, si la connexion réseau est fermée, mais qu’un paquet DISCONNECT n’a pas été préalablement reçu à partir de l’appareil, IoT Hub envoie le message Will fourni dans le paquet CONNECT au canal de télémétrie. Le canal de télémétrie peut être soit le point de terminaison Événements par défaut, soit un point de terminaison personnalisé défini par le routage d’IoT Hub. Le message a la propriété iothub-MessageType, à laquelle une valeur de Will est affectée.

Utilisation directe du protocole MQTT (en tant que module)

Vous pouvez vous connecter à IoT Hub sur MQTT à l’aide d’une identité de module, ce qui revient à se connecter à IoT Hub en tant qu’appareil. Pour plus d’informations sur la connexion à IoT Hub sur MQTT en tant qu’appareil, consultez Utilisation directe du protocole MQTT (en tant qu’appareil). Toutefois, vous avez besoin d’utiliser les valeurs suivantes :

Définissez l'ID client sur {device-id}/{module-id}.
Si vous vous authentifiez avec un nom d’utilisateur et un mot de passe, définissez le nom d’utilisateur sur <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 et utilisez le jeton SAS associé à l’identité du module comme mot de passe.
Utilisez devices/{device-id}/modules/{module-id}/messages/events/ comme rubrique pour la publication des données de télémétrie.
Utilisez devices/{device-id}/modules/{module-id}/messages/events/ comme rubrique WILL.
Utilisez devices/{device-id}/modules/{module-id}/# comme rubrique pour recevoir des messages.
Les rubriques GET et PATCH sont identiques pour les modules et les appareils.
Les rubriques GET et PATCH sont identiques pour les modules et les appareils.

Pour plus d’informations sur l’utilisation de MQTT avec des modules, consultez Publier et s’abonner avec IoT Edge, et apprenez-en davantage sur le point de terminaison MQTT du hub IoT Edge.

Exemples en utilisant MQTT sans Kit de développement logiciel (SDK) Azure IoT

Le Référentiel d’exemple IoT MQTT contient des exemples C/C++, Python et CLI qui vous montrent comment envoyer des messages de télémétrie, recevoir des messages cloud-à-appareil et utiliser des jumeaux d’appareils sans utiliser les SDK d’appareils Azure.

Les exemples C/C++ utilisent la bibliothèque Eclipse Mosquitto, l’exemple Python utilise Eclipse Paho et les exemples de l’interface CLI utilisent mosquitto_pub.

Pour en savoir plus, consultez Tutoriel – Utiliser MQTT pour développer un client d’appareil IoT.

Configuration TLS/SSL

Pour utiliser le protocole MQTT directement, votre client doit se connecter via le protocole TLS/SSL. Sans cette étape, des erreurs de connexion se produiront.

Afin d’établir une connexion TLS, il se peut que vous deviez télécharger et référencer le certificat racine DigiCert utilisé par Azure. Entre le 15 février et le 15 octobre 2023, Azure IoT Hub migre son certificat racine TLS depuis le certificat racine DigiCert Baltimore vers DigiCert Global Root G2. Pendant cette période de migration, vous devez disposer des deux certificats sur vos appareils pour garantir la connectivité. Pour plus d’informations sur la migration, consultez Migrer des ressources IoT vers une nouvelle racine de certificat TLS. Pour plus d’informations sur ces certificats, consultez le site web Digicert.

L’exemple suivant montre comment implémenter cette configuration en utilisant la version Python de la bibliothèque Paho MQTT fournie par la fondation Eclipse.

Tout d’abord, installez la bibliothèque Paho à partir de votre environnement de ligne de commande :

pip install paho-mqtt

Ensuite, implémentez le client dans un script Python. Remplacez ces espaces réservés dans l’extrait de code suivant :

<local path to digicert.cer> est le chemin vers un fichier local qui contient le certificat racine DigiCert. Vous pouvez créer ce fichier en copiant les informations de certificat à partir de certs.c dans le SDK Azure IoT pour C. Incluez les lignes -----BEGIN CERTIFICATE----- et -----END CERTIFICATE-----, supprimez les marques " au début et à la fin de chaque ligne, et supprimez les caractères \r\n à la fin de chaque ligne.
<device id from device registry> est l’ID d’un appareil que vous avez ajouté à votre hub IoT.
<generated SAS token> est un jeton SAP pour l’appareil créé comme décrit précédemment dans cet article.
<iot hub name> est le nom de votre hub 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()

Pour vous authentifier à l’aide d’un certificat d’appareil, mettez à jour l’extrait de code précédent avec les modifications spécifiées dans l’extrait de code suivant. Pour plus d’informations sur la manière de préparer l’authentification par certificat, consultez la section Obtenir un certificat d’autorité de certification X.509 dans Authentifier des appareils à l’aide de certificats d’autorité de certification 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)

Envoi de messages appareil-à-cloud

Lorsqu’un appareil se connecte, il peut envoyer des messages à IoT Hub en utilisant devices/{device-id}/messages/events/ ou devices/{device-id}/messages/events/{property-bag} en tant que Nom de la rubrique. L’élément {property-bag} permet à l’appareil d’envoyer des messages avec d’autres propriétés dans un format encodé par URL. Par exemple :

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

Notes

Cet élément {property_bag} utilise le même encodage que celui des chaînes de requête dans le protocole HTTPS.

Notes

Si vous routez des messages D2C vers un compte de stockage Azure et que vous voulez tirer parti de l’encodage JSON, vous devez spécifier les informations Type de contenu Encodage du contenu, notamment $.ct=application%2Fjson&$.ce=utf-8, dans le cadre du {property_bag} mentionné dans la remarque précédente.

Le format de ces attributs est propre au protocole. IoT Hub traduit ces attributs en propriétés système correspondantes. Pour plus d’informations, consultez la section Propriétés système de Syntaxe des requêtes pour le routage des messages IoT Hub.

La liste suivante décrit les comportements spécifiques de l’implémentation d’IoT Hub :

IoT Hub ne prend pas en charge les messages QoS 2. Si un client d’appareil publie un message avec QoS 2, IoT Hub interrompt la connexion réseau.
IoT Hub ne conserve pas les messages Retain. Si un appareil envoie un message avec l’indicateur RETAIN défini sur 1, IoT Hub ajoute la propriété d’application mqtt-retain au message. Dans ce cas, IoT Hub ne conserve pas le message, mais le transmet à l’application principale.
IoT Hub ne prend en charge qu’une seule connexion MQTT active par appareil. Toute nouvelle connexion MQTT pour le compte du même ID d’appareil amène IoT Hub à supprimer la connexion existante, et le message 400027 ConnectionForcefullyClosedOnNewConnection est consigné dans les journaux IoT Hub
Pour router des messages en fonction de leur corps, vous devez commencer par ajouter la propriété « contentType » (ct) à la fin de la rubrique MQTT et lui affecter la valeur application/json;charset=utf-8, comme illustré dans l’exemple suivant. Pour plus d’informations sur le routage des messages en fonction de leurs propriétés ou de leur corps, consultez la documentation relative à la syntaxe des requêtes pour le routage des messages IoT Hub.

devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

Pour plus d’informations, consultez Envoyer des messages d’appareil-à-cloud et de cloud-à-appareil avec IoT Hub.

Réception de messages cloud-à-appareil

Pour recevoir des messages d’IoT Hub, l’appareil doit s’abonner en utilisant un devices/{device-id}/messages/devicebound/# en tant que Filtre de rubrique. Le caractère générique à plusieurs niveaux # dans le Filtre de rubrique est utilisé uniquement pour autoriser l’appareil à recevoir d’autres propriétés dans le nom de la rubrique. IoT Hub n’autorise pas l’utilisation des caractères génériques # ou ? pour filtrer les sous-rubriques. IoT Hub n’étant pas un broker de messagerie pub-sub à usage général, il prend uniquement en charge les noms et les filtres de rubrique documentés. Un appareil ne peut s’abonner qu’à cinq rubriques à la fois.

L’appareil ne reçoit aucun message d’IoT Hub tant qu’il ne s’est pas abonné avec succès à son point de terminaison spécifique, représenté par le filtre de rubrique devices/{device-id}/messages/devicebound/#. Une fois qu’un abonnement a été établi, l’appareil reçoit les messages cloud-à-appareil qui lui ont été envoyés après l’abonnement. Si l’appareil se connecte avec l’indicateur CleanSession défini sur 0, l’abonnement est rendu persistant entre les différentes sessions. Dans ce cas, la prochaine fois que l’appareil se connecte avec CleanSession 0, il reçoit les messages en attente qui lui ont été envoyés quand il était déconnecté. Si l’appareil utilise l’indicateur CleanSession défini sur 1, il ne reçoit pas les messages d’IoT Hub jusqu’à ce qu’il s’abonne à son point de terminaison d’appareil.

IoT Hub remet les messages avec le Nom de la rubriquedevices/{device-id}/messages/devicebound/, ou devices/{device-id}/messages/devicebound/{property-bag} lorsqu'il y a des propriétés de message. {property-bag} contient des paires clé/valeur codées URL de propriétés de message. Seules les propriétés d’application et les propriétés système définissables par l’utilisateur (comme messageId ou correlationId) sont incluses dans le jeu de propriétés. Les noms de propriété système ont le préfixe $ , tandis que les noms de propriété d’application ne sont précédés d’aucun préfixe. Pour plus d’informations sur le format du jeu de propriétés, consultez Envoi de messages appareil-à-cloud.

Dans les messages cloud-à-appareil, les valeurs du conteneur de propriétés sont représentées comme dans le tableau suivant :

Valeur de la propriété	Représentation	Description
`null`	`key`	Seule la clé apparaît dans le conteneur des propriétés
chaîne vide	`key=`	Clé suivie d’un signe égal sans valeur
valeur non Null, non vide	`key=value`	Clé suivie d’un signe égal et de la valeur

L’exemple suivant montre un conteneur de propriétés qui contient trois propriétés d’application : prop1 avec une valeur null; prop2, une chaîne vide ("") ; et prop3 avec la valeur « a string ».

/?prop1&prop2=&prop3=a%20string

Quand une application d’appareil s’abonne à une rubrique avec QoS 2, IoT Hub accorde le niveau QoS 1 maximal dans le paquet SUBACK. Après cela, IoT Hub remet les messages à l’appareil à l’aide de QoS 1.

Récupération des propriétés d’un jumeau d’appareil

Tout d’abord, un appareil s’abonne à $iothub/twin/res/# pour recevoir les réponses de l’opération. Ensuite, il envoie un message vide à la rubrique $iothub/twin/GET/?$rid={request id}, avec une valeur propagée pour l’ID de la requête. Le service envoie alors un message de réponse contenant les données de jumeau d’appareil sur la rubrique $iothub/twin/res/{status}/?$rid={request-id}, en utilisant le même ID de requête que la requête.

L’ID de la requête peut être n’importe quelle valeur valide de propriété de message et l’état est validé sous forme d’entier. Pour plus d’informations, consultez Envoyer des messages d’appareil-à-cloud et de cloud-à-appareil avec IoT Hub.

Le corps de la réponse contient la section des propriétés du jumeau d’appareil, comme illustré dans l’exemple de réponse suivant :

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

Les codes d’état possibles sont :

Statut	Description
200	Succès
429	Trop de requêtes (limitées). Pour plus d’informations, consultez Limitation d’IoT Hub.
5**	Erreurs de serveur

Pour en savoir plus, consultez Comprendre et utiliser les jumeaux d’appareil IoT Hub.

Mettre à jour les propriétés signalées du jumeau d’appareil

Pour mettre à jour les propriétés signalées, l’appareil émet une demande à destination d’IoT Hub via une publication sur une rubrique MQTT désignée. Une fois que IoT Hub a traité la demande, il répond en indiquant l’état de réussite ou d’échec de l’opération de mise à jour via une publication sur une autre rubrique. Cet appareil peut souscrire à cette rubrique pour être informé du résultat de sa demande de mise à jour jumeau numérique. Pour implémenter ce type d’interaction demande/réponse dans MQTT, nous utilisons la notion d’ID de demande ($rid) fournie initialement par l’appareil dans sa demande de mise à jour. Cet ID de demande est également inclus dans la réponse d'IoT Hub pour autoriser l'appareil à mettre en corrélation la réponse avec sa demande antérieure particulière.

La séquence suivante décrit comment un appareil met à jour les propriétés déclarées dans le jumeau d’appareil IoT Hub :

Un appareil doit tout d’abord s’abonner à la rubrique $iothub/twin/res/# pour recevoir des réponses d’opération de IoT Hub.
Un appareil envoie un message qui contient la mise à jour de jumeau d’appareil pour la rubrique $iothub/twin/PATCH/properties/reported/?$rid={request-id}. Ce message contient une valeur ID de requête.
Le service envoie ensuite un message de réponse qui contient la nouvelle valeur ETag de la collection de propriétés déclarées dans la rubrique $iothub/twin/res/{status}/?$rid={request-id}. Ce message de réponse utilise le même ID de requête que la requête.

Le corps du message de demande inclut un document JSON qui contient de nouvelles valeurs pour les propriétés signalées. Chaque membre du document JSON met à jour ou ajoute le membre correspondant dans le document du jumeau d’appareil. Un membre défini sur null supprime le membre de l’objet le contenant. Par exemple :

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

Les codes d’état possibles sont :

Statut	Description
204	Réussite (aucun contenu n’est retourné)
400	Demande incorrecte. JSON incorrect
429	Trop de demandes (limité), selon la Limitation d’IoT Hub
5**	Erreurs de serveur

L’extrait de code Python suivant illustre le processus de mise à jour des propriétés signalées du jumeau sur MQTT à l’aide du client Paho MQTT :

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)

En cas de réussite du processus de mise à jour des propriétés signalées du jumeau dans l’extrait de code précédent, le message de publication issu d’IoT Hub comprend la rubrique suivante : $iothub/twin/res/204/?$rid=1&$version=6, où 204 est le code d’état indiquant la réussite, $rid=1 correspond à l’ID de la requête fourni par l’appareil dans le code et $version désigne la version de la section des propriétés signalées des jumeaux d’appareil après la mise à jour.

Pour en savoir plus, consultez Comprendre et utiliser les jumeaux d’appareil IoT Hub.

Réception de notifications de mise à jour des propriétés souhaitées

Lorsqu’un appareil est connecté, IoT Hub envoie des notifications à la rubrique $iothub/twin/PATCH/properties/desired/?$version={new-version}, qui contient le contenu de la mise à jour effectuée par le serveur principal de la solution. Par exemple :

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

Comme pour les mises à jour de propriétés, les valeurs null signifient que le membre de l’objet JSON est en cours de suppression. De plus, $version indique la nouvelle version de la section des propriétés souhaitées du jumeau.

Important

IoT Hub génère des notifications de modification uniquement lorsque les appareils sont connectés. Veillez à implémenter le flux de reconnexion des appareils pour maintenir la synchronisation des propriétés souhaitées entre IoT Hub et l’application pour appareil.

Pour en savoir plus, consultez Comprendre et utiliser les jumeaux d’appareil IoT Hub.

Répondre à une méthode directe

Tout d’abord, un appareil doit s’abonner à $iothub/methods/POST/#. IoT Hub envoie des requêtes de méthodes à la rubrique $iothub/methods/POST/{method-name}/?$rid={request-id}, avec un corps vide ou un code JSON valide.

Pour répondre, l’appareil envoie un message avec un corps vide ou JSON valide à la rubrique $iothub/methods/res/{status}/?$rid={request-id}. Dans ce message, request ID doit correspondre à celui du message de requête, et status doit être un entier.

Pour plus d’informations, consultez Comprendre et appeler des méthodes directes à partir d’IoT Hub.

Étapes suivantes

Pour en savoir plus sur l’utilisation de MQTT, consultez :

Pour en savoir plus sur l’utilisation des SDK d’appareils IoT, consultez :

Kits de développement logiciel (SDK) Azure IoT

Pour en savoir plus sur la planification de votre déploiement IoT Hub, consultez :

Communique avec un hub IoT à l’aide du protocole MQTT

Comparer la prise en charge de MQTT dans IoT Hub et Event Grid

Connexion à IoT Hub

Utilisation des Kits device SDK

Délai de maintien de connexion par défaut

Migration d’une application d’appareil d’AMQP vers MQTT

Utilisation directe du protocole MQTT (en tant qu’appareil)

Utiliser l’extension Azure IoT Hub pour Visual Studio Code

Utilisation directe du protocole MQTT (en tant que module)

Exemples en utilisant MQTT sans Kit de développement logiciel (SDK) Azure IoT

Configuration TLS/SSL

Envoi de messages appareil-à-cloud

Réception de messages cloud-à-appareil

Récupération des propriétés d’un jumeau d’appareil

Mettre à jour les propriétés signalées du jumeau d’appareil

Réception de notifications de mise à jour des propriétés souhaitées

Répondre à une méthode directe

Étapes suivantes

Ressources supplémentaires