Comprendre la messagerie cloud-à-appareil à partir d’un hub IoT
Les messages cloud-à-appareil constituent des notifications unidirectionnelles à partir de votre back-end de solution vers une application d’appareil. Pour une description des autres options cloud-à-appareil prises en charge par Azure IoT Hub, voir Conseils pour les communications cloud-à-appareil.
Notes
Les fonctionnalités décrites dans cet article sont uniquement disponibles au 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.
Vous envoyez les messages cloud-à-appareil via un point de terminaison côté service, appelé /messages/devicebound. Un appareil reçoit ensuite les messages via un point de terminaison spécifique de l’appareil ( /devices/{IdAppareil}/messages/devicebound).
Pour cibler chaque message cloud-à-appareil sur un seul appareil, IoT Hub définit la propriété to sur /devices/{IdAppareil}/messages/devicebound.
Chaque file d’attente d’appareil peut contenir jusqu’à 50 messages cloud-à-appareil. Les tentatives d’envoi d’un nombre supérieur de messages au même appareil entraînent une erreur.
Cette article évoque les concepts et processus des messages cloud-à-appareil. Pour découvrir de l’aide sur le développement d’applications qui gèrent les messages cloud-à-appareil, consultez Envoyer et recevoir des messages cloud-à-appareil.
Cycle de vie des messages cloud-à-appareil
Pour garantir la remise des messages au moins une fois, IoT Hub conserve les messages cloud-à-appareil dans des files d’attente par appareil. Les appareils doivent explicitement accuser réception d’un message avant que le hub IoT supprime le message de la file d’attente. Cette approche garantit la résilience contre les échecs de connectivité et d’appareils.
Le graphique de l’état du cycle de vie s’affiche dans le diagramme suivant :
Quand le service IoT Hub envoie un message à un appareil, il définit l’état du message sur Enqueued (En file attente). Lorsqu’un thread d’appareil est prêt à recevoir un message, le hub IoT verrouille le message en définissant l’état sur Invisible. Cet état permet aux autres threads sur l’appareil à commencer à recevoir d’autres messages. Lorsqu’un thread d’appareil a fini de traiter un message, il notifie IoT Hub en terminant le message. Ensuite, IoT Hub définit l’état sur Completed (Terminé).
Un appareil peut également :
Rejeter le message, ce qui amène IoT Hub à lui attribuer l’état Dead lettered (Mis en file d’attente de lettres mortes). Il n’existe aucune file d’attente de lettres mortes pour récupérer ces messages. Les appareils qui se connectent via le protocole MQTT (Message Queuing Telemetry Transport) ne peuvent pas rejeter les messages cloud-à-appareil.
Abandonner le message, ce qui amène IoT Hub à replacer ce dernier dans la file d’attente avec l’état Enqueued(En file attente). Les appareils qui se connectent via le protocole MQTT ne peuvent pas abandonner les messages cloud-à-appareil.
Il est possible qu’un thread ne parvienne pas à traiter un message, mais n’en avertisse pas IoT Hub. Dans ce cas, les messages passent automatiquement de l’état Invisible à l’état En file d’attente après un délai d’attente de visibilité (ou de verrouillage). La longueur de ce délai d’attente est d’une minute et ne peut pas être modifiée.
La propriété Nombre maximal de remises sur IoT Hub détermine le nombre maximal de fois qu’un message peut passer de l’état Enqueued (En file d’attente) à l’état Invisible, et inversement. Une fois ce nombre de transitions atteint, IoT Hub attribue au message l’état Dead lettered (Mis en file d’attente de lettres mortes). De même, IoT Hub attribue à un message l’état Dead lettered (Mis en file d’attente de lettres mortes) à l’issue de son délai d’expiration.
Généralement, un appareil achève un message cloud-à-appareil lorsque la perte du message n’affecte pas la logique d’application. C’est par exemple le cas quand l’appareil a rendu persistant le contenu du message en local, ou qu’il a exécuté une opération correctement. Le message peut également transporter des informations temporaires, dont la perte éventuelle n’aurait aucun impact sur les fonctionnalités de l’application. Quelquefois, pour les tâches longues, vous pouvez :
Terminer le message cloud-à-appareil après que l’appareil a rendu persistante la description de la tâche dans le stockage local.
Notifier le backend de la solution à l’aide d’un ou de plusieurs messages appareil-à-cloud à différents stades de la progression de la tâche.
Expiration du message (durée de vie)
Chaque message cloud-à-appareil est doté d’un délai d’expiration. Cette durée est définie par l’une des options suivantes :
- La propriété ExpiryTimeUtc dans le service
- IoT Hub, via l’utilisation de la valeur Durée de vie par défaut spécifiée comme propriété IoT Hub
Pour plus d’informations sur l’expiration des messages, consultez Options de configuration cloud-à-appareil.
Un moyen courant de tirer parti de l’expiration du message et d’éviter l’envoi de messages à des appareils déconnectés consiste à définir des valeurs de durée de vie courtes. Cette approche produit le même résultat que la gestion de l’état de connexion de l’appareil, mais s’avère plus efficace. Lorsque vous demandez des accusés de réception pour les messages, IoT Hub vous indique quels sont les appareils :
- En mesure de recevoir des messages.
- Qui ne sont pas en ligne ou qui ont échoué.
Commentaires de messages
Lorsque vous envoyez un message cloud-à-appareil, le service peut demander la remise d’un commentaire par message concernant l’état final de ce dernier. Pour configurer le retour de message, définissez la propriété d’application iothub-ack figurant dans le message cloud-à-appareil qui est envoyé sur l’une des quatre valeurs suivantes :
| Valeur de la propriété Ack | Comportement |
|---|---|
| Aucun | Par défaut. IoT Hub ne génère aucun message de commentaire. |
| positif | Si le message cloud-à-appareil prend l’état Completed (Terminé), IoT Hub génère un message de commentaire. |
| négatif | Si le message cloud-à-appareil prend l’état Dead lettered (Mis en file d’attente de lettres mortes), IoT Hub génère un message de commentaire. |
| complet | IoT Hub génère un message de commentaires dans les deux cas. |
Si la valeur de la propriété Ack est définie sur full et que vous ne recevez pas de message de commentaire, cela signifie que le message de commentaire est arrivé à expiration. Le service ne peut pas savoir ce qui est arrivé au message d’origine. Dans la pratique, un service doit s'assurer qu'il peut traiter les commentaires avant leur expiration. Le délai d’expiration maximal est de deux jours, ce qui vous laisse le temps de faire refonctionner le service en cas de défaillance.
Comme l’explique la section Points de terminaison, IoT Hub fournit des commentaires sous la forme de messages via un point de terminaison accessible au service (/messages/servicebound/feedback). La sémantique pour recevoir des commentaires est identique aux messages de cloud-à-appareil. Chaque fois que c’est possible, des commentaires de messages sont mis en lot dans un seul message, au format suivant :
| Propriété | Description |
|---|---|
| EnqueuedTime | Horodatage indiquant à quel moment le message de commentaires a été reçu par le hub. |
| UserId | {iot hub name} |
| ContentType | application/vnd.microsoft.iothub.feedback.json |
Le système envoie les commentaires soit lorsque le lot atteint 64 messages, soit dans les 15 secondes suivant le dernier envoi, selon ce qui se produit en premier.
Le corps est un tableau sérialisé JSON des enregistrements, chacun disposant des propriétés suivantes :
| Propriété | Description |
|---|---|
| enqueuedTimeUtc | Un horodatage indiquant la date et l’heure du résultat du message. Par exemple, un horodatage qui indique quand le message du commentaire a été reçu ou le message d’origine est arrivé à expiration. |
| originalMessageId | Valeur MessageId du message cloud-à-appareil auquel se rapportent ces informations de commentaire. |
| statusCode | Chaîne obligatoire, utilisée dans les messages de commentaire générés par IoT Hub : Success Expired DeliveryCountExceeded Rejeté Purged |
| description | Valeurs de chaîne pour StatusCode. |
| deviceId | Valeur DeviceId de l’appareil cible du message cloud-à-appareil auquel se rapporte ce commentaire. |
| deviceGenerationId | Valeur DeviceGenerationId de l’appareil cible du message cloud-à-appareil auquel se rapporte ce commentaire. |
Le service doit spécifier une valeur MessageId pour le message cloud-à-appareil afin de pouvoir mettre en corrélation ses commentaires avec le message d’origine.
L’exemple de code suivant montre le corps d’un message de commentaire :
[
{
"originalMessageId": "0987654321",
"enqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
"statusCode": "Success",
"description": "Success",
"deviceId": "123",
"deviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
},
{
...
},
...
]
Commentaires en attente pour les appareils supprimés
Quand un appareil est supprimé, les commentaires en attente sont également supprimés. Les commentaires des appareils sont envoyés par lots. Une fenêtre étroite, souvent inférieure à une seconde, peut se produire entre le moment où un appareil confirme la réception du message et le moment où le lot de commentaires suivant est préparé. Si un appareil est supprimé dans cette fenêtre étroite, les commentaires ne se produisent pas.
Vous pouvez résoudre ce problème en attendant un certain temps que les commentaires en attente arrivent avant de supprimer votre appareil. Les commentaires des messages associés doivent être présumés perdus une fois qu’un appareil est supprimé.
Options de configuration cloud-à-appareil
Chaque hub IoT expose les options de configuration suivantes pour la messagerie cloud-à-appareil :
| Propriété | Description | Plage et valeur par défaut |
|---|---|---|
| defaultTtlAsIso8601 | Durée de vie par défaut des messages cloud-à-appareil | Intervalle ISO_8601 de deux jours maximum (minimum une minute) ; valeur par défaut : une heure |
| maxDeliveryCount | Nombre de remises maximal pour les files d’attente par appareil cloud-à-appareil | 1 à 100 ; valeur par défaut : 10 |
| feedback.ttlAsIso8601 | Rétention des messages de commentaire liés au service | Intervalle ISO_8601 de deux jours maximum (minimum une minute) ; valeur par défaut : une heure |
| feedback.maxDeliveryCount | Nombre de remises maximal pour la file d’attente de commentaires | 1 à 100 ; valeur par défaut : 10 |
| feedback.lockDurationAsIso8601 | Durée de verrouillage de la file d’attente de commentaires | Intervalle ISO_8601 de 5 à 300 secondes (minimum cinq secondes) ; valeurs par défaut : 60 secondes. |
Vous pouvez configurer les options de configuration dans le Portail Azure ou l’interface Azure CLI :
Portail Azure : Sous Paramètres du hub dans votre hub IoT, sélectionnez Points de terminaison intégrés, puis accédez à Messagerie Cloud-à-appareil. (La définition des propriétés feedback.maxDeliveryCount et feedback.lockDurationAsIso8601 n’est actuellement pas prise en charge dans le Portail Azure.)
Azure CLI : utilisez la commande az iot hub update :
az iot hub update --name {your IoT hub name} \ --set properties.cloudToDevice.defaultTtlAsIso8601=PT1H0M0S az iot hub update --name {your IoT hub name} \ --set properties.cloudToDevice.maxDeliveryCount=10 az iot hub update --name {your IoT hub name} \ --set properties.cloudToDevice.feedback.ttlAsIso8601=PT1H0M0S az iot hub update --name {your IoT hub name} \ --set properties.cloudToDevice.feedback.maxDeliveryCount=10 az iot hub update --name {your IoT hub name} \ --set properties.cloudToDevice.feedback.lockDurationAsIso8601=PT0H1M0S
Étapes suivantes
Pour découvrir plus d’informations sur les Kits de développement logiciel (SDK) que vous pouvez utiliser pour gérer des messages cloud-à-appareil, voir Kits de développement logiciel (SDK) Azure IoT Hub.
Pour découvrir de l’aide sur le développement d’applications qui gèrent les messages cloud-à-appareil, consultez Envoyer et recevoir des messages cloud-à-appareil.