Partager via

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

Cet article explique comment les appareils peuvent utiliser le protocole MQTT pour communiquer avec Azure IoT Hub. Les points de terminaison d’appareil IoT Hub prennent en charge la connectivité des appareils à l’aide de :

Note

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 IoT Hub de base et standard/gratuit, consultez Choisir le niveau et la taille ioT Hub appropriés pour votre solution.

Toutes les communications d’appareil avec IoT Hub doivent être sécurisées à l’aide de TLS. Par conséquent, IoT Hub ne prend pas en charge les connexions MQTT non sécurisées sur le port 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 d’un répartiteur MQTT hébergé dans le cloud, utilisez Azure Event Grid à la place. Event Grid permet la communication bidirectionnelle entre les clients MQTT sur des rubriques hiérarchiques flexibles à l’aide d’un modèle de messagerie de publication-abonnement. Il vous permet également d’acheminer les messages MQTT vers d’autres services Azure ou des points de terminaison personnalisés pour un traitement ultérieur.

Le tableau suivant résume les différences actuelles dans la prise en charge de MQTT entre les deux services :

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 des fonctionnalités limitée pour MQTT v3.1.1. Prise en charge du protocole MQTT v3.1.1 et v5.
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 du cloud vers l'appareil ou des communications entre appareils. Prend en charge les diffusions appareil-à-cloud, les diffusions cloud-à-appareil à grande dispersion et les modèles de communication appareil-à-appareil.
Taille maximale de message de 256 Ko. Taille maximale du message de 512 Ko.

Se connecter à IoT Hub

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

De nombreux pare-feu professionnels et éducatifs bloquent le port MQTT (port TCP 8883). Si vous ne pouvez pas ouvrir le port 8883 dans votre pare-feu, utilisez MQTT sur WebSockets. MQTT sur WebSockets communique sur le port 443, qui est presque toujours ouvert. Pour apprendre à spécifier les protocoles MQTT et MQTT sur WebSockets quand vous utilisez les SDK Azure IoT, consultez Utilisation des SDK d’appareils.

Utiliser les kits SDK d’appareil

Les kits SDK d’appareil Azure IoT 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 un échange de messages plus rapide, vous devez noter que la remise n’est pas garantie et n’est pas reconnue. C’est pourquoi la solution QoS 0 est souvent appelée « fire and forget » (tire et oublie).

Lorsqu’un appareil se connecte à un hub IoT, les kits SDK d’appareil fournissent des méthodes permettant à 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.

Language 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 Utilise MQTT par défaut Pour créer le client, ajoutez websockets=True dans l'appel

Le fragment suivant montre comment spécifier le protocole MQTT sur WebSockets lorsque vous utilisez le Kit de développement logiciel (SDK) 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);

Le fragment suivant montre comment spécifier le protocole MQTT sur WebSockets lorsque vous utilisez le Kit de développement logiciel (SDK) Python Azure IoT :

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

Important

Cet article comprend les étapes à suivre pour connecter un appareil en utilisant une signature d’accès partagé, également appelée « authentification par clé symétrique ». Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification d’un appareil en utilisant des certificats X.509 est une approche plus sécurisée. Pour en savoir plus, consultez les meilleures pratiques de sécurité pour les solutions IoT > Sécurité des connexions.

Délai d’expiration de connexion par défaut

Pour vous assurer qu’une connexion client à un hub IoT reste active, le service et le client échangent régulièrement un ping keep-alive. Si vous utilisez l’un des kits SDK d’appareil, le client envoie un message keep-alive à l’intervalle défini dans le tableau suivant :

Language Intervalle de maintien de connexion par défaut Paramétrable
Node.JS 180 secondes Non
Java 230 secondes Non
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 de ping keep-alive d’IoT Hub est de 1,5 fois la valeur keep-alive du client ; Cependant, IoT Hub limite le délai maximal d’expiration du côté serveur à 29,45 minutes (1 767 secondes).

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.

Migrer une application d’appareil d’AMQP vers MQTT

Si vous utilisez les kits SDK d’appareil, pour passer d’AMQP à MQTT, vous devez modifier le paramètre de protocole dans l’initialisation du client.

Lorsque vous passez d’AMQP à MQTT, vérifiez les éléments suivants :

  • AMQP retourne des erreurs pour nombreuses conditions, tandis que MQTT met fin à la connexion. Par conséquent, vous devrez peut-être modifier votre logique de gestion des exceptions.

  • MQTT ne prend pas en charge l’opération de rejet lorsqu’elle reçoit des messages cloud-à-appareil. Si votre application back-end doit recevoir une réponse de l’application d’appareil, envisagez d’utiliser des méthodes directes.

  • AMQP n’est pas pris en charge dans le SDK Python.

Utiliser le protocole MQTT directement à partir d’un appareil

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

Important

Cet article comprend les étapes à suivre pour connecter un appareil en utilisant une signature d’accès partagé, également appelée « authentification par clé symétrique ». Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification d’un appareil en utilisant des certificats X.509 est une approche plus sécurisée. Pour en savoir plus, consultez les meilleures pratiques de sécurité pour les solutions IoT > Sécurité des connexions.

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 Nom d’utilisateur contient :

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

    Pour éviter un comportement inattendu, incluez la version de l’API dans le champ.

  • Dans le champ Password, utilisez un jeton SAP. L’extrait de code suivant montre le format du jeton SAP :

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

    Note

    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 Tutoriel : Créer et charger des certificats pour tester et suivre des instructions de code dans la section configuration TLS.

    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 l’extension Azure IoT Hub pour Visual Studio Code ou la commande d’extension CLI az iot hub generate-sas-token pour générer un jeton SAP. Vous pouvez ensuite copier et coller le jeton SAP dans votre propre code à des fins de test.

    L’extension génère un jeton SAP avec 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 d’appareil peut spécifier un message Will dans le paquet CONNECT . L’application d’appareil doit utiliser devices/{device-id}/messages/events/ ou devices/{device-id}/messages/events/{property-bag} comme nom de rubrique Will pour définir les messages Will à transférer 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.

Utiliser le protocole MQTT directement à partir d’un module

Vous pouvez également vous connecter à IoT Hub via MQTT à l’aide d’une identité de module. Cette approche est similaire à la connexion en tant qu’appareil, mais vous devez 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 à <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12. Si vous utilisez SAS, utilisez le jeton SAP 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 la rubrique Will.

  • Utilisez devices/{device-id}/modules/{module-id}/# comme rubrique pour recevoir des messages.

  • Les rubriques GET et PATCH jumelles sont identiques pour les modules et les appareils.

  • La rubrique d’état jumelle est la même pour les modules et les appareils.

Pour plus d’informations sur l’utilisation de MQTT avec des modules, consultez le point de terminaison MQTT du hub IoT Edge.

Exemples utilisant MQTT sans Kit de développement logiciel (SDK) d’appareil 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 plus d’informations, consultez Tutoriel - Utiliser MQTT pour développer un client d’appareil IoT sans utiliser un KIT DE développement logiciel (SDK) d’appareil.

Configuration TLS

Pour utiliser directement le protocole MQTT, votre client doit se connecter via TLS 1.2. Toute tentative d’ignorer cette étape échoue avec les erreurs de connexion.

Pour établir une connexion TLS, vous devrez peut-être télécharger et référencer le certificat racine global DigiCert G2 que Azure utilise. Pour plus d’informations sur ce certificat, consultez le site web de Digicert.

L’exemple suivant montre comment implémenter cette configuration à l’aide de la version Python de la bibliothèque Paho MQTT.

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 identités avec les certificats 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)

Envoyer des 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>)…

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

Si vous acheminez des messages D2C vers un compte de stockage Azure et que vous souhaitez utiliser l’encodage JSON, vous devez spécifier les informations de type de contenu et d’encodage de contenu, y compris $.ct=application%2Fjson&$.ce=utf-8, dans le cadre de la {property_bag} note précédente.

Note

Le format de ces attributs est spécifique 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 récapitule les comportements spécifiques à l’implémentation d’IoT Hub MQTT :

  • IoT Hub ne prend pas en charge les messages QoS 2. Si une application d’appareil publie un message avec QoS 2, IoT Hub ferme la connexion réseau.

  • IoT Hub ne conserve Retain pas les messages. 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, au lieu de conserver le message conservé, IoT Hub le transmet à l’application back-end.

  • 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 provoque IoT Hub à interrompre la connexion existante et inscrit 400027 ConnectionForcefullyClosedOnNewConnection dans les journaux IoT Hub.

  • Pour router les messages en fonction du corps du message, commencez par ajouter une propriété ct à la fin de la rubrique MQTT et définissez sa valeur application/json;charset=utf-8 comme indiqué 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 et recevoir des messages avec IoT Hub.

Recevoir des messages du cloud vers l'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 permet à l’appareil de recevoir plus de 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’est pas un répartiteur de messagerie à usage général, il prend uniquement en charge les noms de rubriques documentés et les filtres de rubriques. Un appareil ne peut s’abonner qu’à cinq rubriques à la fois.

L’appareil ne reçoit aucun message de IoT Hub tant qu’il n’a pas réussi à s’abonner à son point de terminaison spécifique à l’appareil, représenté par le filtre de sujets devices/{device-id}/messages/devicebound/#. Une fois qu’un abonnement est établi, l’appareil reçoit des messages du cloud vers l'appareil qui lui ont été envoyés après l'établissement de 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} quand 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

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

Récupérer les propriétés du 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 et recevoir des messages 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 :

État Description
200 Success
429 Trop de requêtes (limitées). Pour plus d’informations, consultez les quotas et les limitations d'IoT Hub
5** Erreurs de serveur

Pour en savoir plus, consultez Comprendre et utiliser les jumeaux d’appareils dans 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 auprès d’IoT Hub en publiant sur une rubrique MQTT désignée. Une fois que IoT Hub traite la demande, elle répond avec l’état de réussite ou d’échec de l’opération de mise à jour en publiant dans une autre rubrique. L’appareil peut s’abonner à cette rubrique pour recevoir des notifications sur le résultat de la demande de mise à jour de jumeau. Pour implémenter ce type d’interaction de requête/réponse dans MQTT, l’appareil fournit un ID de demande ($rid) dans sa demande de mise à jour initiale. Cet ID de requête est ensuite inclus dans la réponse d’IoT Hub pour permettre à l’appareil de mettre en corrélation la réponse à la requête correcte.

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 :

  1. Un appareil s’abonne d’abord à la $iothub/twin/res/# rubrique pour lui permettre de recevoir des réponses d’IoT Hub.

  2. 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.

  3. 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 :

État Description
204 Réussite (aucun contenu n’est retourné)
400 Demande incorrecte. JSON incorrect
429 Trop de demandes (limité), selon Quotas et 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)

Lorsque le processus de mise à jour des propriétés signalées du jumeau réussit, IoT Hub publie un message dans la rubrique suivante : $iothub/twin/res/204/?$rid=1&$version=6où 204 est le code d’état indiquant la réussite, $rid=1 correspond à l’ID de demande fourni par l’appareil dans le code et $version correspond à la version de la section 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’appareils dans IoT Hub.

Recevoir les 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 de l’appareil pour conserver les propriétés souhaitées synchronisées entre IoT Hub et l’application de l’appareil.

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

Répondre à une méthode directe

Tout d’abord, un appareil s’abonne à $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 :

  • Last updated on