Envoi de messages cloud à appareil avec IoT Hub (.NET)

Article
06/03/2023

Azure IoT Hub est un service entièrement géré qui permet d’autoriser des communications bidirectionnelles fiables et sécurisées entre des millions d’appareils et un serveur principal de solution.

Cet article vous montre comment :

Envoyer des messages cloud-à-appareil (C2D) de votre back-end de solution vers un seul appareil par IoT Hub
Recevoir des messages cloud-à-appareil sur un appareil
À partir du back-end de votre solution, demandez l’accusé de réception (commentaires) pour les messages envoyés à un appareil depuis IoT Hub

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.

À la fin de cet article, vous exécutez deux applications de console .NET.

MessageReceiveSample : exemple d’application d’appareil incluse avec le kit de développement logiciel (SDK) Microsoft Azure IoT pour .NET, qui se connecte à votre hub IoT et reçoit des messages cloud à appareil.
SendCloudToDevice : application de service qui envoie un message cloud-à-appareil à l’application d’appareil par le biais d’IoT Hub, puis reçoit son accusé de réception.

Notes

IoT Hub offre la prise en charge de kits SDK pour plusieurs plateformes d’appareils et langages (C, Java, Python et JavaScript) par le biais de kits Azure IoT device SDK.

Vous trouverez des informations supplémentaires sur les messages cloud-à-appareil dans Messagerie D2C et C2D avec IoT Hub.

Prérequis

Un abonnement Azure. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
Un hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans Créer un hub IoT.
Un appareil inscrit dans votre hub IoT. Si vous n’avez pas encore inscrit d’appareil, inscrivez-en un dans le portail Azure.
Cet article utilise des exemples de code issus du SDK Azure IoT pour C#.
- Téléchargez ou clonez le référentiel du SDK depuis GitHub sur votre machine de développement.
- Assurez-vous que .NET Core version 3.0.0 ou ultérieure est installé sur votre ordinateur de développement. Vérifiez votre version en exécutant dotnet --version et en téléchargeant .NET si nécessaire.
Vérifiez que le port 8883 est ouvert dans votre pare-feu. L’exemple d’appareil décrit dans cet article utilise le protocole MQTT, qui communique via le port 8883. Ce port peut être bloqué dans certains environnements réseau professionnels et scolaires. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).
Visual Studio.

Obtention de la chaîne de connexion de l’appareil

Dans cet article, vous exécutez un exemple d’application qui simule un appareil, qui reçoit des messages cloud à appareil envoyés via votre IoT Hub. L’exemple d’application MessageReceiveSample inclus avec le SDK Microsoft Azure IoT pour .NET se connecte à votre hub IoT et agit comme votre appareil simulé. L’exemple utilise la chaîne de connexion principale de l’appareil inscrit sur votre hub IoT.

Pour obtenir la chaîne de connexion principale d’un appareil inscrit sur votre hub IoT, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet gauche de votre IoT Hub, sous Gestion des appareils, sélectionnez Appareils.
Dans la liste des appareils, sélectionnez l’appareil approprié.
Copiez la Chaîne de connexion principale, puis enregistrez la valeur.

Recevoir des messages dans l’application d’appareil

Dans cette section, exécutez l’exemple d’application d’appareil MessageReceiveSample pour recevoir les messages C2D envoyés via votre hub IoT. Ouvrez une nouvelle invite de commandes et accédez au dossier azure-iot-sdk-csharp\iothub\device\samples\getting started\MessageReceiveSample, dans le dossier où vous avez développé le SDK C# Azure IoT. Exécutez les commandes suivantes, en remplaçant la valeur de l’espace réservé {Your device connection string} par la chaîne de connexion de l’appareil que vous avez copiée à partir de l’appareil inscrit dans votre hub IoT.

dotnet restore
dotnet run --c "{Your device connection string}"

La sortie suivante provient de l’exemple d’application d’appareil après son démarrage et sa connexion à votre hub IoT :

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
     
5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.

L’exemple d’application d’appareil interroge les messages à l’aide des méthodes ReceiveAsync et CompleteAsync. La méthode ReceiveC2dMessagesPollingAndCompleteAsync utilise la méthode ReceiveAsync, qui retourne de manière asynchrone le message reçu au moment où l’appareil reçoit le message. ReceiveAsync retourne null après un délai d’expiration qui peut être spécifié. Dans cet exemple, le délai par défaut (une minute) est utilisé. Lorsque l’appareil reçoit une valeur null, elle doit continuer à attendre de nouveaux messages. Cette exigence est la raison pour laquelle l’exemple d’application inclut le bloc de code suivant dans la méthode ReceiveC2dMessagesPollingAndCompleteAsync :

   if (receivedMessage == null)
   {
      continue;
   }

L’appel de la méthode CompleteAsync notifie IoT Hub que le message a été traité avec succès et peut être supprimé en toute sécurité de la file d’attente de l’appareil. L’appareil doit appeler cette méthode lorsque son traitement se termine correctement, quel que soit le protocole utilisé.

Avec les protocoles AMQP et HTTPS, mais pas avec le protocole MQTT, l’appareil peut également :

abandonner un message - IoT Hub conserve alors le message dans la file d’attente de l’appareil pour un traitement ultérieur ;
rejeter un message, ce qui le supprime définitivement de la file d’attente de l’appareil.

S’il se produit un événement qui empêche l’appareil de traiter, d’abandonner ou de rejeter le message, IoT Hub le met à nouveau en file d’attente après un délai d’attente déterminé. C’est la raison pour laquelle la logique de traitement des messages de l’application pour périphérique doit être idempotente pour qu’un message identique reçu plusieurs fois produise le même résultat.

Pour plus d’informations sur le cycle de vie des messages cloud-à-appareil et sur la manière dont l’IoT Hub traite les messages cloud-à-appareil, consultez Envoyer des messages cloud-à-appareil à partir d’un hub IoT.

Notes

Quand vous utilisez HTTPS comme moyen de transport au lieu de MQTT ou AMQP, la méthode ReceiveAsync est immédiatement renvoyée. Le modèle de prise en charge des messages cloud-à-appareil avec HTTPS est représenté par des appareils connectés par intermittence qui vérifient rarement les messages (au minimum toutes les 25 minutes). L’émission d’un nombre plus élevé de réceptions HTTPS conduit IoT Hub à limiter les demandes. Pour plus d’informations sur les différences de prise en charge entre MQTT, AMQP et HTTPS, consultez Conseils sur les communications cloud-à-appareil et Choisir un protocole de communication.

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous allez créer un service principal pour envoyer des messages cloud-à-appareil via votre IoT Hub. Pour envoyer des messages cloud-à-appareil, votre service a besoin de l'autorisation de connexion de service. Par défaut, chaque IoT Hub est créé avec une stratégie d’accès partagé nommée service qui accorde cette autorisation.

Pour obtenir la chaîne de connexion IoT Hub pour la stratégie service, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre IoT Hub, sélectionnez Stratégies d’accès partagé.
Dans la liste des stratégies, sélectionnez la stratégie service.
Copiez la Chaîne de connexion principale, puis enregistrez la valeur.

Pour plus d’informations sur les autorisations et les stratégies d’accès partagé IoT Hub, consultez Contrôle d’accès et autorisations.

Envoi d’un message cloud vers appareil

Dans cette section, vous créez une application de console .NET qui envoie des messages cloud-à-appareil à l’application de l’appareil simulé. Vous avez besoin de l’ID d’appareil de votre appareil et de votre chaîne de connexion IoT Hub.

Dans Visual Studio, sélectionnez Fichier>Nouveau>Projet. Sous Créer un projet, sélectionnez Application console (.NET Framework) , puis cliquez sur Suivant.
Nommez le projet SendCloudToDevice, puis sélectionnez Suivant.
Acceptez la version la plus récente de .NET Framework. Sélectionnez Créer pour créer le projet.
Dans l’Explorateur de solutions, faites un clic droit sur le nouveau projet, puis sélectionnez Gérer les packages NuGet.
Sous Gérer les packages NuGet, sélectionnez Parcourir, puis recherchez et sélectionnez Microsoft.Azure.Devices. Sélectionnez Installer.

Cette opération a pour effet de télécharger, d’installer et d’ajouter une référence au package NuGet de l’Azure IoT service SDK.
Ajoutez l’instruction using suivante en haut du fichier Program.cs.
```
using Microsoft.Azure.Devices;
```
Ajoutez les champs suivants à la classe Program . Remplacez la valeur de l’espace réservé {iot hub connection string} par la chaîne de connexion IoT Hub que vous avez copiée dans Obtenir la chaîne de connexion du hub IoT. Remplacez la valeur de l’espace réservé {device id} par l’ID de l’appareil inscrit dans votre hub IoT.
```
static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";
static string targetDevice = "{device id}";
```

Ajoutez la méthode suivante à la classe Program pour envoyer un message à votre appareil.

private async static Task SendCloudToDeviceMessageAsync()
{
     var commandMessage = new
      Message(Encoding.ASCII.GetBytes("Cloud to device message."));
     await serviceClient.SendAsync(targetDevice, commandMessage);
}

Enfin, ajoutez les lignes suivantes à la méthode Main .

Console.WriteLine("Send Cloud-to-Device message\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Console.WriteLine("Press any key to send a C2D message.");
Console.ReadLine();
SendCloudToDeviceMessageAsync().Wait();
Console.ReadLine();

Appuyez sur F5 pour démarrer votre exemple d’application de service. Sélectionnez la fenêtre SendCloudToDevice, puis appuyez sur Entrée. Vous devez voir le message reçu par l’exemple d’application d’appareil, comme illustré dans l’exemple de sortie suivant.

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.

5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.
5/22/2023 11:15:18 AM> Polling using ReceiveAsync() - received message with Id=
5/22/2023 11:15:18 AM> Received message: [Cloud to device message.]
        Content type:

5/22/2023 11:15:18 AM> Completed C2D message with Id=.

Réception des commentaires de remise

Il est possible de demander des accusés de réception (ou d’expiration) à IoT Hub pour chaque message cloud-à-appareil. Cette option permet au serveur principal de solution d’informer facilement d’une nouvelle tentative ou d’une logique de compensation. Pour plus d’informations sur le cycle de vie des messages cloud-à-appareil, consultez Messagerie D2C et C2D avec IoT Hub.

Dans cette section, vous modifiez l’exemple d’application de service SendCloudToDevice pour demander des commentaires et en recevoir de la part du hub IoT.

Dans Visual Studio, dans le projet SendCloudToDevice, ajoutez la méthode suivante à la classe Program.

private async static void ReceiveFeedbackAsync()
{
     var feedbackReceiver = serviceClient.GetFeedbackReceiver();

     Console.WriteLine("\nReceiving c2d feedback from service");
     while (true)
     {
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
           string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
     }
 }

Notez que ce modèle de réception est le même que celui utilisé pour recevoir des messages cloud-à-appareil à partir de l’application de l’appareil.

Ajoutez la ligne suivante à la méthode Main juste après serviceClient = ServiceClient.CreateFromConnectionString(connectionString).
```
ReceiveFeedbackAsync();
```
Pour obtenir des commentaires sur la remise de votre message cloud-à-appareil, vous devez spécifier une propriété dans la méthode SendCloudToDeviceMessageAsync . Ajoutez la ligne suivante, immédiatement après la ligne var commandMessage = new Message(...);.
```
commandMessage.Ack = DeliveryAcknowledgement.Full;
```
Vérifiez que l’exemple d’application d’appareil est en cours d’exécution, puis exécutez l’exemple d’application de service en appuyant sur F5. Sélectionnez la fenêtre de console SendCloudToDevice, puis appuyez sur Entrée. Vous devez voir le message reçu par l’exemple d’application d’appareil et, après quelques secondes, le message de commentaires reçu par votre application SendCloudToDevice. La sortie suivante montre le message de commentaires reçu par l’exemple d’application de service :
```
Send Cloud-to-Device message


Receiving c2d feedback from service
Press any key to send a C2D message.

Received feedback: Success
```

Notes

Par souci de simplicité, cet article n’implémente aucune stratégie de nouvelles tentatives. Dans le code de production, vous devez implémenter des stratégies de nouvelle tentative (par exemple, un backoff exponentiel) comme indiqué dans Gestion des erreurs temporaires.

Étapes suivantes

Dans cet article, vous avez appris à envoyer et recevoir des messages de cloud-à-appareil.

Pour en savoir plus sur les messages cloud-à-appareil, consultez Envoyer des messages cloud-à-appareil à partir d’IoT Hub.
Pour en savoir plus sur les formats de message de IoT Hub, consultez Créer et lire des messages IoT Hub.

Envoi de messages cloud à appareil avec IoT Hub (.NET)

Prérequis

Obtention de la chaîne de connexion de l’appareil

Recevoir des messages dans l’application d’appareil

Obtenir la chaîne de connexion du hub IoT

Envoi d’un message cloud vers appareil

Réception des commentaires de remise

Étapes suivantes

Ressources supplémentaires