Envoyer et recevoir des messages cloud-à-appareil

Recevoir des messages cloud-à-appareil

Cette section explique comment recevoir des messages cloud-à-appareil à l’aide de la classe DeviceClient dans le Kit de développement logiciel (SDK) Azure IoT pour .NET.

Il existe deux options qu’une application cliente d’appareil peut utiliser pour recevoir des messages :

• Interrogation : l’application de l’appareil recherche de nouveaux messages IoT Hub à l’aide d’une boucle de code (par exemple, une boucle while ou for). La boucle s’exécute en continu, en vérifiant les messages.
• Rappel: l’application d’appareil configure une méthode de gestionnaire de messages asynchrone appelée immédiatement lorsqu’un message arrive.

Déclarer un objet DeviceClient

DeviceClient inclut les méthodes et propriétés nécessaires pour recevoir des messages d’IoT Hub.

Par exemple :

static DeviceClient deviceClient;

Fournir les paramètres de connexion

Fournissez la chaîne de connexion principale IoT Hub et l’ID de l’appareil à l’aide de DeviceClient en utilisant la méthode CreateFromConnectionString. Outre la chaîne de connexion principale IoT Hub requise, la méthode CreateFromConnectionString peut être surchargée pour inclure ces paramètres de facultatifs :

• transportType - Le protocole de transport : variantes de HTTP version 1, AMQP ou MQTT. AMQP est la valeur par défaut. Pour afficher toutes les valeurs disponibles, consultez Énumération TransportType.
• transportSettings - - Interface utilisée pour définir divers paramètres spécifiques au transport pour DeviceClient et ModuleClient. Pour plus d’informations, consultez interface ITransportSettings.
• ClientOptions : options qui autorisent la configuration de l’instance cliente de l’appareil ou du module pendant l’initialisation.

Cet exemple appelle CreateFromConnectionString à définir les paramètres de connexion IoT Hub DeviceClient et d’ID d’appareil.

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

Interrogation

L'interrogation utilise ReceiveAsync pour vérifier les messages.

Un appel à ReceiveAsync peut prendre ces formes :

• ReceiveAsync() : attendez la période d’expiration par défaut d’un message avant de continuer.
• ReceiveAsync (Timespan) : recevez un message de la file d’attente de l’appareil à l’aide d’un délai d’expiration spécifique.
• ReceiveAsync (CancellationToken) : recevez un message de la file d’attente de l’appareil à l’aide d’un jeton d’annulation. Lors de l’utilisation d’un jeton d’annulation, la période d’expiration par défaut n’est pas utilisée.

Lorsque vous utilisez un type de transport HTTP 1 au lieu de MQTT ou AMQP, la méthode ReceiveAsync retourne immédiatement. Le modèle pris en charge pour les messages cloud-à-appareil avec HTTP 1 est des appareils connectés par intermittence qui vérifient les messages rarement (un minimum de toutes les 25 minutes). L’émission de plus de réceptions HTTP 1 entraîne la limitation des requêtes IoT Hub. Pour plus d’informations sur les différences entre la prise en charge de MQTT, AMQP et HTTP 1, consultez conseils de communication cloud-à-appareil et Choisir un protocole de communication.

Méthode CompleteAsync

Une fois que l’appareil reçoit un message, l’application de l’appareil appelle la méthode CompleteAsync pour informer IoT Hub que le message a été traité avec succès et qu’il peut être supprimé en toute sécurité de la file d’attente de l’appareil IoT Hub. L’appareil doit appeler cette méthode lorsque son traitement se termine correctement, quel que soit le protocole de transport qu’il utilise.

Abandon, rejet ou délai d’expiration du message

Avec les protocoles AMQP et HTTP version 1, mais pas les protocole MQTT, l’appareil peut également :

• Abandonnez un message en appelant AbandonAsync. Ainsi, IoT Hub conserve le message dans la file d’attente de l’appareil pour une consommation future.
• Rejeter un message en appelant RejectAsync. Cela supprime définitivement le message 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.

Boucle d’interrogation

À l’aide de l’interrogation, une application utilise une boucle de code qui appelle la méthode ReceiveAsync à plusieurs reprises pour rechercher les nouveaux messages jusqu’à ce qu’ils s’arrêtent.

Si vous utilisez ReceiveAsync avec une valeur de délai d’attente ou le délai d’expiration par défaut, dans la boucle, chaque appel à ReceiveAsync attend la période d’expiration spécifiée. Si ReceiveAsync expire, une valeur null est retournée et la boucle continue.

Lorsqu'un message est reçu, un objet Task est renvoyé par ReceiveAsync qui doit être transmis à CompleteAsync. Un appel à CompleteAsync avertit IoT Hub de supprimer le message spécifié de la file d’attente de messages en fonction du paramètre Task.

Dans cet exemple, la boucle appelle ReceiveAsync jusqu’à ce qu’un message soit reçu ou que la boucle d’interrogation soit arrêtée.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Rappel

Pour recevoir des messages de rappel cloud-à-appareil dans l'application de l'appareil, l'application doit se connecter à IoT Hub et configurer un écouteur de rappel pour traiter les messages entrants. Les messages entrants de l’appareil sont reçus à partir de la file d’attente de messages IoT Hub.

À l’aide du rappel, l’application d’appareil configure une méthode de gestionnaire de messages à l’aide de SetReceiveMessageHandlerAsync. Le gestionnaire de messages est appelé, puis un message est reçu. La création d’une méthode de rappel pour recevoir des messages supprime la nécessité d’interroger en permanence les messages reçus.

Le rappel est disponible uniquement à l’aide de ces protocoles :

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_only

L’option de protocole Http1 ne prend pas en charge les rappels, car les méthodes du Kit de développement logiciel (SDK) doivent interroger les messages reçus de toute façon, ce qui bat le principe de rappel.

Dans cet exemple, SetReceiveMessageHandlerAsync configure une méthode de gestionnaire de rappel nommée OnC2dMessageReceivedAsync, appelée chaque fois qu’un message est reçu.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

Recevoir une stratégie de nouvelle tentative de message

La stratégie de nouvelle tentative de message du client d’appareil peut être définie à l’aide de DeviceClient.SetRetryPolicy.

Le délai d’attente de nouvelle tentative de message est stocké dans la propriété DeviceClient.OperationTimeoutInMilliseconds.

Exemple de message de réception du SDK

Le Kit de développement logiciel (SDK) .NET/C# inclut un exemple Message Receive qui inclut les méthodes de message de réception décrites dans cette section.

Envoi de messages cloud vers appareil

Cette section décrit le code essentiel pour envoyer un message d’une application back-end de solution à un appareil IoT à l’aide de la classe ServiceClient dans le Kit de développement logiciel (SDK) Azure IoT pour .NET. Comme indiqué précédemment, une application backend de solution se connecte à un IoT Hub et les messages sont envoyés à IoT Hub codés avec un appareil de destination. IoT Hub stocke les messages entrants dans sa file d’attente de messages et les messages sont remis de la file d’attente de messages IoT Hub à l’appareil cible.

Une application back-end de solution peut également demander et recevoir un retour de livraison pour un message envoyé à IoT Hub destiné à être distribué sur l'appareil via la file d'attente des messages.

Déclarer un objet ServiceClient

ServiceClient inclut des méthodes et des propriétés nécessaires pour envoyer des messages d’une application via IoT Hub à un appareil.

static ServiceClient serviceClient;

Fournir la chaîne de connexion

Fournissez la chaîne de connexion principale IoT Hub à l’aide de ServiceClient en utilisant la méthode CreateFromConnectionString. Outre la chaîne de connexion principale IoT Hub requise, la méthode CreateFromConnectionString peut être surchargée pour inclure ces paramètres de facultatifs :

• transportType - Amqp ou Amqp_WebSocket_Only.
• transportSettings : paramètres de proxy AMQP et HTTP pour le client de service.
• ServiceClientOptions : options qui autorisent la configuration de l’instance du client de service lors de l’initialisation. Pour plus d’informations, consultez ServiceClientOptions.

Cet exemple crée l’objet ServiceClient à l’aide de la chaîne de connexion IoT Hub.

static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Envoyer un message cloud-à-appareil asynchrone

Utilisez sendAsync pour envoyer un message asynchrone depuis une application via le cloud (IoT Hub) vers l'appareil. L’appel est effectué à l’aide du protocole AMQP.

sendAsync utilise ces paramètres :

• deviceID : identificateur de chaîne de l’appareil cible.
• message - Message cloud-à-appareil. Le message est de type Message et peut être mis en forme en conséquence.
• timeout - Une valeur de délai d'attente facultative. La valeur par défaut est d’une minute si elle n’est pas spécifiée.

Cet exemple envoie un message de test à l’appareil cible avec une valeur de délai d’expiration de 10 secondes.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

Réception des commentaires de remise

Un programme d’envoi peut demander des accusés de réception (ou d’expiration) à IoT Hub pour chaque message cloud-à-appareil. Cette option permet au programme d’envoi d’utiliser la logique d’information, de nouvelle tentative ou de compensation. Une description complète des opérations et des propriétés de retour de message est décrite dans Retour de message.

Pour recevoir des commentaires sur la remise des messages :

• Créer l’objet feedbackReceiver
• Envoyer des messages en utilisant le paramètre Ack
• Attendez de recevoir des commentaires

Créer l'objet feedbackReceiver

Appelez GetFeedbackReceiver pour créer un objet FeedbackReceiver . FeedbackReceiver contient des méthodes que les services peuvent utiliser pour effectuer des opérations de réception de commentaires.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Envoyer des messages à l’aide du paramètre Ack

Chaque message doit inclure une valeur pour l’accusé de réception propriété Ack afin de recevoir des commentaires de remise. La propriété Ack peut être l’une des valeurs suivantes :

• aucun (valeur par défaut) : aucun message de commentaires n’est généré.

• Positive: recevez un message de commentaires si le message a été terminé.

• Negative: recevez un message de commentaires si le message a expiré (ou le nombre maximal de remises a été atteint) sans être terminé par l’appareil.

• Full: commentaires pour les résultats Positive et Negative.

Dans cet exemple, la propriété Ack est définie sur Full, demandant un retour de livraison de message positif ou négatif pour un message.

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

Attendez de recevoir des commentaires

Définissez une CancellationToken. Ensuite, dans une boucle, appelez ReceiveAsync à plusieurs reprises, en vérifiant les messages de commentaires de remise. Chaque appel à ReceiveAsync attend la période d’expiration définie pour l’objet ServiceClient.

• Si un délai d’expiration ReceiveAsync expire sans message reçu, ReceiveAsync retourne null et la boucle continue.
• Si un message de commentaires est reçu, un objet Task est retourné par ReceiveAsync qui doit être transmis à CompleteAsync, ainsi que le jeton d’annulation. Un appel à CompleteAsync supprime le message envoyé spécifié de la file d’attente de messages en fonction du paramètre Task.
• Si nécessaire, le code de réception peut appeler AbandonAsync pour remettre un message d'envoi dans la file d'attente.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

Cet exemple montre une méthode qui inclut ces étapes.

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

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         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 de commentaires est similaire au modèle utilisé pour recevoir des messages cloud-à-appareil dans l’application d’appareil.

Reconnexion du client de service

Lors de la rencontre d’une exception, le client de service transmet ces informations à l’application appelante. À ce stade, il est recommandé d’inspecter les détails de l’exception et de prendre les mesures nécessaires.

Par exemple :

• S’il s’agit d’une exception réseau, vous pouvez réessayer l’opération.
• S’il s’agit d’une exception de sécurité (exception non autorisée), inspectez vos informations d’identification et vérifiez qu’elles sont à jour.
• S’il s’agit d’une exception de limitation/quota dépassée, surveillez et/ou modifiez la fréquence d’envoi de requêtes, ou mettez à jour votre unité d’échelle d’instance hub. Consultez Quotas et limitation IoT Hub pour plus de détails.

Envoyer une stratégie de nouvelle tentative de message

La stratégie de nouvelle tentative de message ServiceClient peut être définie à l’aide de ServiceClient.SetRetryPolicy.

Exemple de message d'envoi du SDK

Le SDK .NET/C# inclut un exemple de client de service qui inclut les méthodes d'envoi de message décrites dans cette section.

Recevoir des messages cloud-à-appareil

Cette section explique comment recevoir des messages cloud-à-appareil à l’aide de la classe DeviceClient du Kit de développement logiciel (SDK) Azure IoT pour Java.

Pour qu’une application d’appareil basée sur Java reçoive des messages cloud vers appareil, elle doit se connecter à IoT Hub, puis configurer un écouteur de rappel et un gestionnaire de messages pour traiter les messages entrants provenant d’IoT Hub. L’application d’appareil doit également être en mesure de détecter et de gérer les déconnexions si la connexion de message appareil-à-IoT Hub est interrompue.

Importer des bibliothèques du Kit de développement logiciel (SDK) Java Azure IoT

Le code référencé dans cet article utilise ces bibliothèques SDK.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

Déclarer un objet DeviceClient

L'instanciation de l'objet DeviceClient nécessite ces paramètres :

• connString : Chaîne de connexion de l’appareil IoT. La chaîne de connexion est un ensemble de paires clé-valeur séparées par « ; », avec les clés et les valeurs séparées par '='. Elle doit contenir des valeurs pour ces clés : HostName, DeviceId, and SharedAccessKey.
• Protocole de transport : la connexion DeviceClient peut utiliser l’un des protocoles de transport IoTHubClientProtocol suivants . AMQP est le plus polyvalent, permet de vérifier fréquemment les messages et permet le rejet et l’annulation des messages. MQTT ne prend pas en charge les méthodes de rejet ou d’abandon des messages :
  • AMQPS
  • AMQPS_WS
  • HTTPS
  • MQTT
  • MQTT_WS

Par exemple :

static string connectionString = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

Définir la méthode de rappel de message

Utilisez la méthode setMessageCallback pour définir une méthode de gestionnaire de messages qui est avertie lorsqu'un message est reçu d'IoT Hub.

setMessageCallback inclut ces paramètres :

• callback - Nom de la méthode de rappel. Peut être null.
• context - Contexte facultatif de type object. Utilisez null si aucune spécification n’est spécifiée.

Dans cet exemple, une méthode callback nommée MessageCallback sans paramètre de contexte n’est passée à setMessageCallback.

client.setMessageCallback(new MessageCallback(), null);

Créer un gestionnaire de rappel de message

Un gestionnaire de messages de rappel reçoit et traite un message entrant transmis à partir de la file d’attente des messages IoT Hub.

Dans cet exemple, le gestionnaire de messages traite un message entrant, puis retourne IotHubMessageResult.COMPLETE. Une valeur de retour IotHubMessageResult.COMPLETE informe IoT Hub que le message est correctement traité et que le message peut être supprimé en toute sécurité de la file d’attente de l’appareil. L’appareil doit retourner IotHubMessageResult.COMPLETE une fois son traitement terminé, en informant IoT Hub que le message doit être supprimé de la file d’attente de messages, quel que soit le protocole qu’il utilise.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

Options d’abandon et de rejet des messages

Bien que le grand nombre de messages entrants d’un appareil soit correctement reçu et entraîne IotHubMessageResult.COMPLETE, il peut être nécessaire d’abandonner ou de rejeter un message.

• Avec AMQP et HTTPS, mais pas MQTT, une application peut :
  • IotHubMessageResult.ABANDON le message. IoT Hub le remet en file d'attente et le renvoie plus tard.
  • IotHubMessageResult.REJECT le message. IoT Hub ne met pas en file d’attente le message et supprime définitivement le message de la file d’attente des messages.
• Les clients utilisant MQTT ou MQTT_WS ne peuvent pas ABANDON ou REJECT messages.

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.

Créer la méthode de rappel d’état du message

Une application peut utiliser registerConnectionStatusChangeCallback pour enregistrer une méthode de rappel à exécuter lorsque l'état de connexion de l'appareil change. Ainsi, l’application peut détecter une connexion de messages arrêtés et tenter de se reconnecter.

Dans cet exemple, IotHubConnectionStatusChangeCallbackLogger est inscrite en tant que méthode de rappel de changement d’état de connexion.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

Le rappel est déclenché et passé un objet ConnectionStatusChangeContext.

Appelez connectionStatusChangeContext.getNewStatus() pour obtenir l’état de connexion actuel.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

L’état de connexion retourné peut être l’une des valeurs suivantes :

• IotHubConnectionStatus.DISCONNECTED
• IotHubConnectionStatus.DISCONNECTED_RETRYING
• IotHubConnectionStatus.CONNECTED

Appelez connectionStatusChangeContext.getNewStatusReason() pour obtenir la raison du changement d’état de la connexion.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Appelez connectionStatusChangeContext.getCause() pour trouver la raison de la modification de l’état de la connexion. getCause() peut retourner null si aucune information n’est disponible.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

Consultez l’exemple de HandleMessages listé dans l’exemple de message SDK recevoir l’exemple de message de cet article pour obtenir un exemple complet montrant comment extraire l’état de modification de l’état de la méthode de rappel de changement d’état, raison pour laquelle l’état de l’appareil a changé et le contexte.

Ouvrir la connexion entre l’appareil et IoT Hub

Utilisez ouvrir pour créer une connexion entre l’appareil et IoT Hub. L’appareil peut désormais envoyer et recevoir des messages de manière asynchrone vers et depuis un IoT Hub. Si le client est déjà ouvert, la méthode ne fait rien.

client.open(true);

Exemple de message de réception du SDK

HandleMessages : exemple d’application d’appareil incluse avec le kit de développement logiciel Microsoft Azure IoT pour Java, qui se connecte à votre hub IoT et reçoit des messages cloud à appareil.

Envoi de messages cloud vers appareil

Cette section explique comment envoyer un message cloud-à-appareil à l’aide de la classe ServiceClient à partir du Kit de développement logiciel (SDK) Azure IoT pour Java. Une application back-end de solution se connecte à un hub IoT et les messages sont envoyés à IoT Hub encodés avec un appareil de destination. IoT Hub stocke les messages entrants dans sa file d’attente de messages et les messages sont remis de la file d’attente de messages IoT Hub à l’appareil cible.

Une application back-end de solution peut également demander et recevoir un retour de livraison pour un message envoyé à IoT Hub destiné à être distribué sur l'appareil via la file d'attente des messages.

Ajouter l’instruction de dépendance

Ajoutez la dépendance pour utiliser le package iothub-java-service-client dans votre application pour communiquer avec votre service IoT Hub :

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

Ajouter des instructions import

Ajoutez ces instructions importer pour utiliser le Kit de développement logiciel (SDK) Java Azure IoT et le gestionnaire d’exceptions.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Définir le protocole de connexion

Utilisez IotHubServiceClientProtocol pour définir le protocole de couche application utilisé par le client de service pour communiquer avec un IoT Hub.

IotHubServiceClientProtocol accepte uniquement l’énumération AMQPS ou AMQPS_WS .

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Créer l’objet ServiceClient

Créez l’objet ServiceClient , en fournissant la chaîne de connexion et le protocole Iot Hub.

private static final String connectionString = "{yourhubconnectionstring}";
private static final ServiceClient serviceClient (connectionString, protocol);

Ouvrir la connexion entre l’application et IoT Hub

ouvrir la connexion de l’expéditeur AMQP. Cette méthode crée la connexion entre l’application et IoT Hub.

serviceClient.open();

Ouvrir un récepteur de commentaires pour les commentaires de remise de messages

Vous pouvez utiliser un FeedbackReceiver pour recevoir des messages envoyés aux commentaires IoT Hub. Un FeedbackReceiver est un récepteur spécialisé dont la méthode Receive retourne un FeedbackBatch au lieu d’un Message.

Dans cet exemple, l’objet FeedbackReceiver est créé et l’instruction open() est appelée pour attendre des commentaires.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

Ajouter des propriétés de message

Vous pouvez éventuellement utiliser setProperties pour ajouter des propriétés de message. Ces propriétés sont incluses dans le message envoyé à l’appareil et peuvent être extraites par l’application de l’appareil dès réception.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Créer et envoyer un message asynchrone

L’objet Message stocke le message à envoyer. Dans cet exemple, un « message cloud à appareil » est remis.

Utilisez setDeliveryAcknowledgement pour demander un accusé de réception de la file d’attente de messages remis/non remis à IoT Hub. Dans cet exemple, l'accusé de réception demandé est Full, soit délivré, soit non délivré.

Utilisez SendAsync pour envoyer un message asynchrone du client au périphérique. Vous pouvez également utiliser la méthode Send (pas asynchrone), mais cette fonction est synchronisée en interne afin qu’une seule opération d’envoi soit autorisée à la fois. Le message est remis de l’application à IoT Hub. IoT Hub place le message dans la file d’attente de messages, prêt à être remis à l’appareil cible.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

Recevoir des commentaires sur la remise des messages

Une fois qu’un message est envoyé à partir de l’application, l’application peut appeler recevoir avec ou sans valeur de délai d’expiration. Si aucune valeur de délai d’expiration n’est fournie, le délai d’expiration par défaut est utilisé. Cela renvoie un objet FeedbackBatch qui contient les propriétés de commentaires de remise des messages qui peuvent être examinées.

Cet exemple crée le récepteur FeedbackBatch et appelle getEnqueuedTimeUtc, imprimant l'heure de mise en file d'attente du message.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

Exemples de messages envoyés par le KIT SDK

• Exemple de client de service - Exemple d'envoi de message, #1.

• Exemple de client de service - Exemple d’envoi de message, #2.

Installer la bibliothèque du Kit de développement logiciel (SDK) Azure IoT

Installez la bibliothèque SDK azure-iot-device sur votre ordinateur de développement avant d'appeler tout code associé :

pip install azure-iot-device

Il existe deux classes du Kit de développement logiciel (SDK) Python utilisées pour envoyer des messages vers et depuis des appareils IoT. Les méthodes de gestion des messages de ces classes sont décrites dans les sections de cette page.

• La classe IoTHubDeviceClient inclut des méthodes permettant de créer une connexion synchrone d’un appareil à un Azure IoT Hub et de recevoir des messages d’IoT Hub.

• La classe IoTHubRegistryManager inclut des API pour les opérations du Gestionnaire de Registre IoT Hub. Dans cet article, les méthodes de cette classe montrent comment se connecter à IoT Hub et envoyer un message à un appareil.

Recevoir des messages cloud-à-appareil

Cette section explique comment recevoir des messages cloud-à-appareil à l’aide de la classe IoTHubDeviceClient du Kit de développement logiciel (SDK) Azure IoT pour Python.

Pour qu’une application d’appareil basée sur Python reçoive des messages cloud vers appareil, elle doit se connecter à IoT Hub, puis configurer un gestionnaire de messages de rappel pour traiter les messages entrants provenant d’IoT Hub.

Importer l’objet IoTHubDeviceClient

Ajoutez une ligne de code pour importer les fonctions IoTHubDeviceClient à partir du Kit de développement logiciel (SDK) azure.iot.device.

from azure.iot.device import IoTHubDeviceClient

Connecter le client d’appareil

Instanciez IoTHubDeviceClient, en transmettant une chaîne de connexion IoT Hub à create_from_connection_string. Cela crée une connexion de l’appareil à IoT Hub.

Vous pouvez également vous connecter IoTHubDeviceClientà un appareil à l’aide de l’une des méthodes suivantes :

• Chaîne de jeton SAS
• Authentification par clé symétrique
• Authentification par certificat X.509

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

Gérer la reconnexion

IoTHubDeviceClient tente par défaut de rétablir une connexion supprimée. Le comportement de reconnexion est régi par les paramètres IoTHubDeviceClient connection_retry et connection_retry_interval.

Créer un gestionnaire de messages

Créez la fonction de gestionnaire de messages pour traiter les messages entrants sur l’appareil.

Dans cet exemple, message_handler est appelée lorsqu’un message est reçu. Les propriétés du message (.items) sont imprimées dans la console à l’aide d’une boucle.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

Affecter le gestionnaire de messages

Utilisez la méthode on_message_received pour affecter la méthode de gestionnaire de messages à l’objet IoTHubDeviceClient.

Dans cet exemple, une méthode de gestionnaire de messages nommée message_handler est attachée à l'objet IoTHubDeviceClient client. L’objet client attend de recevoir un message cloud-à-appareil provenant d’un IoT Hub. Ce code attend jusqu’à 300 secondes (5 minutes) pour un message ou se ferme si une touche de clavier est enfoncée.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

Exemple de message de réception du SDK

Recevoir un message - Recevez des messages Cloud-to-Device (C2D) envoyés depuis Azure IoT Hub vers un appareil.

Envoi de messages cloud vers appareil

Cette section décrit comment envoyer un message cloud à appareil à l’aide de la classe IoTHubRegistryManager du SDK Azure IoT pour Python. Une application back-end de solution se connecte à un hub IoT et les messages sont envoyés à IoT Hub encodés avec un appareil de destination. IoT Hub stocke les messages entrants dans sa file d’attente de messages et les messages sont remis de la file d’attente de messages IoT Hub à l’appareil cible.

Importer l’objet IoTHubRegistryManager

Ajoutez l’instruction import suivante : IoTHubRegistryManager inclut des API pour les opérations IoT Hub Registry Manager.

from azure.iot.hub import IoTHubRegistryManager

Connecter le gestionnaire de Registre IoT Hub

Instanciez l’objet IoTHubRegistryManager qui se connecte à un hub IoT, en passant une chaîne de connexion IoT Hub à from_connection_string.

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

Générer et envoyer un message

Utilisez send_c2d_message pour envoyer un message via le cloud (IoT Hub) à l’appareil.

send_c2d_message utilise ces paramètres :

• deviceID : identificateur de chaîne de l’appareil cible.
• message - Message cloud-à-appareil. Le message est de type str (chaîne).
• properties - Collection facultative de propriétés de type dict. Les propriétés peuvent contenir des propriétés d’application et des propriétés système. La valeur par défaut est {}.

Cet exemple envoie un message de test à l’appareil cible.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

Exemple de message d'envoi du SDK

send_message.py : montre comment envoyer un message cloud-à-appareil.

Installer les packages de messagerie Node.js

Exécutez ces commandes pour installer les packages azure-iot-device et azure-iothub sur votre machine de développement :

npm install azure-iot-device --save
npm install azure-iothub --save

Le package azure-iot-device contient des objets qui s’interfacent avec les appareils IoT. Cet article décrit le code de classe Client qui reçoit les messages d'IoT Hub.

Le package azure-iothub contient des objets qui s’interfacent avec IoT Hub. Cet article décrit Client code de classe qui envoie un message d’une application à un appareil via IoT Hub.

Recevoir des messages dans l’application d’appareil

Cette section décrit comment recevoir des messages cloud-à-appareil à l'aide du package azure-iot-device dans le SDK Azure IoT pour Node.js.

Pour qu’une application d’appareil basée sur Node.js reçoive des messages cloud-à-appareil, elle doit se connecter à IoT Hub, puis configurer un écouteur de rappel et un gestionnaire de messages pour traiter les messages entrants provenant d’IoT Hub. L’application d’appareil doit également être en mesure de détecter et de gérer les déconnexions si la connexion de message appareil-à-IoT Hub est interrompue.

Créer un module client

À partir du package azure-iot-device, créez un Client en utilisant la classe Client. La classe Client contient des méthodes qu’un appareil peut utiliser pour recevoir et envoyer à IoT Hub.

const Client = require('azure-iot-device').Client;

Choisir un protocole de transport

L’objet Client prend en charge ces protocoles :

• Amqp
• Http - Lors de l'utilisation de Http, l'instance Client vérifie rarement les messages provenant d'IoT Hub (au minimum toutes les 25 minutes).
• Mqtt
• MqttWs
• AmqpWs

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.

Cet exemple affecte le protocole AMQP à une variable Protocol. Cette variable de protocole est transmise à la méthode Client.fromConnectionString dans la Ajouter la chaîne de connexion section de cet article.

const Protocol = require('azure-iot-device-mqtt').Amqp;

Fonctionnalités d’achèvement, de rejet et d’abandon des messages

Les méthodes d’achèvement, de rejet et d’abandon des messages peuvent être utilisées en fonction du protocole choisi.

AMQP et HTTP

Les transports AMQP et HTTP peuvent terminer, rejeter ou abandonner un message :

• Terminer : pour terminer un message, le service qui a envoyé le message cloud-à-appareil est averti que le message est reçu. IoT Hub supprime le message de la file d’attente de messages. La méthode prend la forme de client.complete(message, callback function).
• Rejeter - Pour rejeter un message, le service qui a envoyé le message cloud-à-appareil est averti que le message n’est pas traité par l’appareil. IoT Hub supprime définitivement le message de la file d’attente de l’appareil. La méthode prend la forme de client.reject(message, callback function).
• Abandonner - Pour abandonner un message, IoT Hub tente immédiatement de le renvoyer. IoT Hub conserve le message dans la file d’attente de l’appareil pour une consommation future. La méthode prend la forme de client.abandon(message, callback function).

MQTT

MQTT ne prend pas en charge les fonctions complètes, rejetées ou abandonnées du message. Au lieu de cela, MQTT accepte un message par défaut et le message est supprimé de la file d’attente de messages IoT Hub.

Tentatives de Redelivery

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.

Ajouter la chaîne et le protocole de transport IoT Hub

Appelez fromConnectionString pour établir une connexion entre l’appareil et le hub IoT à l’aide de ces paramètres :

• connStr : Une chaîne de connexion qui encapsule les autorisations de « connexion de périphérique » pour un hub IoT. La chaîne de connexion contient le nom d'hôte, l'ID de l'appareil et la clé d'accès partagé dans ce format : "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>"
• transportCtor : protocole de transport.

const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Créer un gestionnaire de messages entrants

Le gestionnaire de messages est appelé pour chaque message entrant.

Une fois qu’un message a été reçu, si vous utilisez AMQP ou le transport HTTP, appelez la méthode client.complete pour informer IoT Hub que le message peut être supprimé de la file d’attente de messages.

Par exemple, ce gestionnaire de messages imprime l’ID de message et le corps du message dans la console, puis appelle client.complete pour informer IoT Hub qu’il a traité le message et qu’il peut être supprimé en toute sécurité de la file d’attente de l’appareil. L’appel à complete n’est pas obligatoire si vous utilisez le transport MQTT et que vous pouvez l’omettre. Un appel àcomplete est requis pour le transport AMQP ou HTTPS.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

Créer un gestionnaire de déconnexion de connexion

Le gestionnaire de déconnexion est appelé lorsque la connexion est déconnectée. Un gestionnaire de déconnexion est utile pour implémenter le code de reconnexion.

Cet exemple intercepte et affiche le message d’erreur de déconnexion dans la console.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

Ajouter des écouteurs d’événements

Vous pouvez spécifier ces écouteurs d’événements à l’aide de la méthode .on.

• Gestionnaire de connexions
• Gestionnaire d’erreurs
• Gestionnaire de déconnexion
• Gestionnaire de messages

Cet exemple inclut le message et les gestionnaires de déconnexion définis précédemment.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

Ouvrir la connexion à IoT Hub

Utilisez la méthode ouvrir pour ouvrir une connexion entre un appareil IoT et IoT Hub. Utilisez .catch(err) pour intercepter un code d’erreur et de gestionnaire d’appels.

Par exemple :

client.open()
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Exemple de message de réception du SDK

simple_sample_device : application d’appareil qui se connecte à votre hub IoT et reçoit des messages cloud-à-appareil.

Envoi de messages cloud vers appareil

Cette section explique comment envoyer un message cloud-à-appareil à l’aide du package azure-iothub à partir du Kit de développement logiciel (SDK) Azure IoT pour Node.js. Comme indiqué précédemment, une application backend de solution se connecte à un IoT Hub et les messages sont envoyés à IoT Hub codés avec un appareil de destination. IoT Hub stocke les messages entrants dans sa file d’attente de messages et les messages sont remis de la file d’attente de messages IoT Hub à l’appareil cible.

Une application back-end de solution peut également demander et recevoir un retour de livraison pour un message envoyé à IoT Hub destiné à être distribué sur l'appareil via la file d'attente des messages.

Charger les modules client et de message

Déclarez un objet Client à l’aide de la classe Client à partir du package azure-iothub.

Déclarez un objet Message à l’aide de la classe Message à partir du package azure-iot-common.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

Créer l’objet Client

Créez le Client à l'aide de fromConnectionString en utilisant ces paramètres :

• Chaîne de connexion IoT Hub
• Type de transport

Dans cet exemple, l’objet serviceClient est créé avec le type de transport Amqp.

var connectionString = '{IoT Hub connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

Ouvrir la connexion cliente

Appelez la méthode Client ouvrir pour ouvrir une connexion entre une application et IoT Hub.

open pouvez être appelée avec ou sans spécifier une fonction de rappel appelée lorsque l’opération de open est terminée.

Dans cet exemple, la méthode open inclut une fonction facultative err de rappel de connexion ouverte. Si une erreur ouverte se produit, un objet d’erreur est retourné. Si la connexion ouverte réussit, une valeur de rappel null est retournée.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

Créer un message

L'objet message inclut le message asynchrone cloud-à-appareil. La fonctionnalité de message fonctionne de la même façon sur AMQP, MQTT et HTTP.

L’objet message prend en charge plusieurs propriétés, y compris ces propriétés. Consultez les propriétés message pour obtenir une liste complète.

• ack - Commentaires de remise. Décrit dans la section suivante.
• properties : carte contenant des clés de chaîne et des valeurs pour le stockage des propriétés de message personnalisées.
• messageId : utilisé pour mettre en corrélation la communication bidirectionnelle.

Ajoutez le corps du message lorsque l’objet de message est instancié. Dans cet exemple, un message 'Cloud to device message.' est ajouté.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

Accusé de réception

Un programme d’envoi peut demander des accusés de réception (ou d’expiration) à IoT Hub pour chaque message cloud-à-appareil. Cette option permet au programme d’envoi d’utiliser la logique d’information, de nouvelle tentative ou de compensation. Une description complète des opérations et des propriétés de retour de message est décrite dans Retour de message.

Chaque message qui doit recevoir un retour de message doit inclure une valeur pour la propriété d'accusé de réception de livraison ack. La propriété ack peut être l’une des valeurs suivantes :

• aucun (valeur par défaut) : aucun message de commentaires n’est généré.

• sent: recevez un message de commentaires si le message a été terminé.

• : recevez un message de commentaires si le message a expiré (ou le nombre maximal de remises a été atteint) sans être terminé par l’appareil.

• full: commentaires pour les résultats envoyés et non envoyés.

Dans cet exemple, la propriété ack est définie sur full, demandant à la fois les commentaires envoyés et non envoyés pour un message.

message.ack = 'full';

Lier le récepteur de commentaires de message

La fonction de rappel du récepteur de commentaires de message est liée au Client à l’aide de getFeedbackReceiver.

Le récepteur de commentaires de message reçoit deux arguments :

• Objet Error (peut être null)
• Objet AmqpReceiver : émet des événements lorsque de nouveaux messages de commentaires sont reçus par le client.

Cet exemple de fonction reçoit et imprime un message de commentaires de remise dans la console.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

Ce code lie la fonction de rappel de commentaires receiveFeedback au service Client objet à l’aide de getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Définir un gestionnaire de résultats d’achèvement de message

La fonction de rappel d’envoi de message est appelée après l’envoi de chaque message.

Cet exemple de fonction imprime le message send résultats de l’opération dans la console. Dans cet exemple, la fonction printResultFor est fournie en tant que paramètre à la fonction send décrite dans la section suivante.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

Envoyer un message

Utilisez la envoyer fonction pour envoyer un message cloud-à-appareil asynchrone à l’application d’appareil via IoT Hub.

send prend en charge ces paramètres :

• deviceID : ID d’appareil de l’appareil cible.
• message : corps du message à envoyer à l’appareil.
• terminé : fonction facultative à appeler une fois l’opération terminée. Terminé est appelé avec deux arguments :
  • Objet Error (peut être null).
  • objet de réponse spécifique au transport utile pour la journalisation ou le débogage.

Ce code appelle send pour envoyer un message cloud-à-appareil à l’application d’appareil via IoT Hub. La fonction de rappel printResultFor définie dans la section précédente reçoit les informations d’accusé de réception.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

Cet exemple montre comment envoyer un message à votre appareil et gérer le message de commentaires lorsque l’appareil reconnaît le message cloud-à-appareil :

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

Exemple de message d'envoi du SDK

send_c2d_message.js - Envoyer des messages C2D à un appareil via IoT Hub.