Partager via

Prise en main de la gestion d’appareils

  • Article

Les applications back-end peuvent utiliser des primitives Azure IoT Hub, par exemple les jumeaux d’appareil et les méthodes directes, pour effectuer le démarrage et le monitoring à distance des actions de gestion des appareils sur les appareils.

Utilisez une méthode directe à partir d’une application back-end pour lancer des actions de gestion des appareils, comme le redémarrage, la réinitialisation de paramètre d’usine et la mise à jour du micrologiciel.

L’appareil est chargé de :

  • Traitement de la requête de méthode directe envoyée par IoT Hub
  • Lancement de l’action correspondante spécifique à l’appareil sur l’appareil
  • Fourniture à IoT Hub des mises à jour de l’état via des propriétés signalées

Cet article illustre la manière dont une application back-end et une application d’appareil peuvent fonctionner de pair pour lancer et surveiller une action d’appareil à distance à l’aide d’une méthode directe.

  • Une application de service appelle une méthode directe pour redémarrer dans une application d’appareil via un hub IoT.
  • Une application d’appareil gère une méthode directe pour redémarrer un appareil.

Remarque

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.

Remarque

Cet article est destiné à compléter les exemples de SDK Azure IoT référencés à partir de cet article. Vous pouvez utiliser des outils SDK pour créer des applications d’appareil et de back-end.

Prérequis

  • Un hub IoT

  • Un appareil inscrit

  • Si votre application utilise le protocole MQTT, assurez-vous que port 8883 est ouvert dans votre pare-feu. Le protocole MQTT communique sur 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).

  • Nécessite Visual Studio

Vue d’ensemble

Cet article décrit comment utiliser le kits de développement logiciel (SDK) Azure IoT pour .NET pour créer un code d’application d’appareil et de service back-end pour les messages directs d’appareil.

Créer une application d’appareil

Cette section explique comment utiliser le code d’application d’appareil pour créer un écouteur de rappel de méthode directe.

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 plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité des connexions.

Package NuGet d’appareil nécessaire

Les applications clientes d’appareil écrites en C# nécessitent le package NuGet Microsoft.Azure.Devices.Client.

Ajoutez ces instructions using pour utiliser la bibliothèque d’appareils.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Connexion à un appareil

La classe DeviceClient expose toutes les méthodes requises pour interagir avec les messages d’appareil.

Connectez-vous à l’appareil à l’aide de la méthode CreateFromConnectionString avec la chaîne de connexion de l’appareil et du protocole de transfert de connexion.

Le paramètre de protocole de transfert CreateFromConnectionString TransportType prend en charge les protocoles de transfert suivants :

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_Only
  • Http1

Cet exemple se connecte à un appareil à l’aide du protocole de transfert Mqtt.

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Créer un écouteur de rappel de méthode directe

Utilisez SetMethodHandlerAsync pour initialiser un écouteur de rappel de méthode directe. L’écouteur est associé à un mot clé nom de méthode, tel que « redémarrage ». Le nom de la méthode peut être utilisé dans une application IoT Hub ou back-end pour déclencher la méthode de rappel sur l’appareil.

Cet exemple montre comment configurer un écouteur de rappel nommé onReboot qui se déclenche lorsque le nom de la méthode directe « redémarrage » est appelé.

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

Pour reprendre l’exemple, la méthode de rappel onReboot met en œuvre la méthode directe sur l’appareil.

La fonction de gestionnaire appelle MethodResponse pour envoyer un accusé de réception de la réponse à l’application appelante.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Remarque

Pour simplifier les choses, 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.

Exemples d’appareils SDK

Le Kit de développement logiciel (SDK) Azure IoT pour .NET fournit des exemples fonctionnels d’applications d’appareil qui gèrent les tâches de méthode directe. Pour plus d’informations, consultez l’article suivant :

Créer une application back-end

Cette section explique comment déclencher une méthode directe sur un appareil.

La classeServiceClient expose toutes les méthodes requises pour créer une application back-end afin d’envoyer des appels de méthode directe aux appareils.

Package NuGet de service nécessaire

Les applications de service principal nécessitent le package NuGet Microsoft.Azure.Devices.

Ajoutez ces instructions using pour utiliser la bibliothèque de service.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

  • Stratégie d’accès partagé
  • Microsoft Entra

Important

Cet article comprend les étapes à suivre pour se connecter à un service à l’aide d’une signature d’accès partagé. Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification à un service avec Microsoft Entra ID ou des identités managées est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité du cloud.

Se connecter à l’aide d’une stratégie d’accès partagé

Connectez une application back-end en utilisant CreateFromConnectionString.

Pour invoquer une méthode directe sur un appareil via l’IoT Hub, 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.

En tant que paramètre de CreateFromConnectionString, fournissez la stratégie d’accès partagé service. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

  • Clè secrète client
  • Certificat
  • Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Conseils d’utilisation pour DefaultAzureCredential.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Microsoft Entra nécessite ces packages NuGet et les instructions using correspondantes :

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

Dans cet exemple, la clé secrète client d’inscription de l’application Microsoft Entra, l’ID client et l’ID de locataire sont ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par DefaultAzureCredential pour authentifier l’application. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à une méthode de connexion IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Le TokenCredential résultant peut ensuite être passé pour se connecter à une méthode IoT Hub pour n’importe quel client du Kit de développement logiciel (SDK) qui accepte les informations d’identification Microsoft Entra :

Dans cet exemple, TokenCredential est passé à ServiceClient.Create pour créer un objet de connexion ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Dans cet exemple, TokenCredential est passé à RegistryManager.Create pour créer un objet RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Exemple de code

Pour obtenir un exemple fonctionnel de l’authentification du service Microsoft Entra, consultez Exemple d’authentification basée sur les rôles.

Appeler une méthode sur un appareil

Pour appeler une méthode sur un appareil :

  1. Créez un objet CloudToDeviceMethod. Transmettez le nom de la méthode directe de l’appareil en tant que paramètre.
  2. Appelez InvokeDeviceMethodAsync pour appeler la méthode sur l’appareil.

Cet exemple appelle la méthode « redémarrage » pour lancer un redémarrage sur l’appareil. La méthode « redémarrage » est mappée à un écouteur sur l’appareil, comme décrit dans la section Créer un écouteur de rappel de méthode directe de cet article.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

Exemples de services Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) Azure IoT pour .NET fournit des exemples de travail d’applications de service qui gèrent les tâches de message. Pour plus d’informations, consultez l’article suivant :

  • Nécessite Java SE Development Kit 8. Veillez à sélectionner Java 8 sous Prise en charge à long terme pour accéder aux téléchargements du kit JDK 8.

Vue d’ensemble

Cet article décrit comment utiliser les Kits de développement logiciel (SDK) Azure IoT pour Java pour créer le code d’application de l’appareil et du service back-end pour les méthodes directes de l’appareil.

Créer une application d’appareil

Cette section explique comment utiliser le code d’application d’appareil pour créer un écouteur de rappel de méthode directe.

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 plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité des connexions.

Instruction d’importation d’appareil

Utilisez les instructions d’importation d’appareil suivantes pour accéder au SDK Azure IoT pour Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

Connexion à un appareil

La classe DeviceClient expose toutes les méthodes dont vous avez besoin pour interagir avec les méthodes directes de l’appareil.

Pour vous connecter à un appareil :

  1. Utilisez IotHubClientProtocol pour choisir un protocole de transport. Par exemple :

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. Utilisez le constructeur DeviceClient pour ajouter la chaîne et le protocole de connexion principal de l’appareil.

    String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

  3. Utilisez open pour connecter l’appareil à IoT Hub. Si le client est déjà ouvert, la méthode ne fait rien.

    client.open(true);

Créer un écouteur de rappel de méthode directe

Utilisez subscribeToMethods pour initialiser un écouteur de rappel de méthode directe. subscribeToMethods écoute les méthodes directes entrantes jusqu’à ce que la connexion soit terminée. Le nom et la charge utile de la méthode sont reçus pour chaque appel de méthode directe.

L’écouteur doit appeler DirectMethodResponse pour envoyer un accusé de réception de réponse de méthode à l’application appelante.

Par exemple :

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Remarque

Pour simplifier les choses, 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.

Exemples d’appareils SDK

Le SDK Azure IoT pour Java inclut un exemple de travail pour tester les concepts de l’application d’appareil décrits dans cet article. Pour plus d’informations, consultez Exemple de méthode directe.

Créer une application back-end

Cette section explique comment lancer un redémarrage à distance sur un appareil à l’aide d’une méthode directe.

La classe ServiceClient DeviceMethod contient des méthodes que les services peuvent utiliser pour accéder aux jumeaux des appareils.

Instructions d’importation de service

Utilisez les instructions d’importation de service suivantes pour accéder au SDK Azure IoT pour Java.

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

  • Stratégie d’accès partagé
  • Microsoft Entra

Important

Cet article comprend les étapes à suivre pour se connecter à un service à l’aide d’une signature d’accès partagé. Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification à un service avec Microsoft Entra ID ou des identités managées est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité du cloud.

Se connecter à l’aide d’une stratégie d’accès partagé

Utilisez le constructeur DeviceMethod pour ajouter la chaîne de connexion principale du service et vous connecter à IoT Hub.

Pour invoquer une méthode directe sur un appareil via l’IoT Hub, 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.

En tant que paramètre du constructeur DeviceMethod, fournissez la stratégie d’accès partagé du service. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

Par exemple :

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Java, consultez Authentification Azure avec Java et Azure Identity.

Par souci de simplicité, cette section se concentre sur la description de l’authentification à l’aide d’une clé secrète client.

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

  • Clè secrète client
  • Certificat
  • Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour Java.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Vous pouvez authentifier les informations d’identification de l’application Microsoft Entra en utilisant DefaultAzureCredentialBuilder. Enregistrez les paramètres de connexion tels que l’ID de locataire, l’ID client et les valeurs de la clé secrète client en tant que variables environnementales. Une fois TokenCredential créé, passez-le à ServiceClient ou à un autre générateur en tant que paramètre « credential ».

Dans cet exemple, DefaultAzureCredentialBuilder tente d’authentifier une connexion à partir de la liste décrite dans DefaultAzureCredential. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à un constructeur tel que ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
S’authentifier en utilisant ClientSecretCredentialBuilder

Vous pouvez utiliser ClientSecretCredentialBuilder pour créer des informations d’identification à l’aide des informations de la clé secrète client. Si cette méthode réussit, elle retourne un TokenCredential qui peut être passé à ServiceClient ou à un autre générateur en tant que paramètre « credential ».

Dans cet exemple, les valeurs de l’ID de locataire, de l’ID client et de la clé secrète client d’inscription de l’application Microsoft Entra ont été ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par ClientSecretCredentialBuilder pour générer les informations d’identification.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();
Autres classes d’authentification

Le kit SDK Java inclut également ces classes qui authentifient une application back-end auprès de Microsoft Entra :

Exemples de code

Pour obtenir des exemples fonctionnels d’authentification auprès du service Microsoft Entra, consultez Exemple d’authentification basée sur les rôles.

Appeler une méthode sur un appareil

Appelez DeviceMethod.invoke pour appeler une méthode sur un appareil et retourner l’état du résultat.

Le paramètre de charge utile invoke est facultatif. Utilisez null s’il n’existe aucune charge utile fournie. Le paramètre de charge utile peut prendre différentes formes de données, notamment chaîne, tableau d’octets et HashMap. Pour obtenir des exemples, consultez Tests de méthode directe.

Cet exemple appelle la méthode « redémarrage » pour lancer un redémarrage sur l’appareil. La méthode « redémarrage » est mappée à un écouteur sur l’appareil, comme décrit dans la section Créer un écouteur de rappel de méthode directe de cet article.

Par exemple :

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

Exemples de services Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) Azure IoT pour Java fournit un exemple opérationnel d’applications de service qui gèrent des tâches de méthode directe. Pour plus d’informations, consultez l’article suivant :

  • Kit de développement logiciel (SDK) Python – Python version 3.7 ou ultérieure est recommandé. Veillez à utiliser l’installation 32 bits ou 64 bits comme requis par votre programme d’installation. Lorsque vous y êtes invité pendant l’installation, veillez à ajouter Python à votre variable d’environnement propre à la plateforme.

Vue d’ensemble

Cet article décrit comment utiliser les kits de développement logiciel (SDK) Azure IoT pour Python pour créer le code d’application d’appareil et de service back-end pour les méthodes directes d’appareil.

Installer des packages

La bibliothèque azure-iot-device doit être installée pour créer des applications d’appareil.

pip install azure-iot-device

La bibliothèque azure-iot-hub doit être installée pour créer des applications de service back-end.

pip install azure-iot-hub

Créer une application d’appareil

Cette section explique comment utiliser le code d’application d’appareil pour créer un écouteur de rappel de méthode directe.

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 plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité des connexions.

Instructions d’importation d’appareil

Ajoutez cette instruction d’importation pour accéder à IoTHubDeviceClient et MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Connexion à un appareil

La classe IoTHubDeviceClient contient des méthodes qui peuvent être utilisées pour travailler avec des méthodes directes.

Utilisez create_from_connection_string pour connecter une application à un appareil à l’aide d’une chaîne de connexion d’appareil.

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IoT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

Créer un rappel de méthode directe

Utilisez on_method_request_received pour créer une fonction de gestionnaire ou une coroutine appelée lorsqu’une méthode directe est reçue. L’écouteur est associé à un mot clé nom de méthode, tel que « redémarrage ». Le nom de la méthode peut être utilisé dans une application IoT Hub ou back-end pour déclencher la méthode de rappel sur l’appareil.

La fonction de gestionnaire doit créer un MethodResponse et le transmettre à send_method_response pour envoyer un accusé de réception de réponse de méthode directe à l’application appelante.

Cet exemple montre comment configurer un gestionnaire de méthode directe nommé method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

Dans cet exemple, la méthode de rappel method_request_handler implémente la méthode directe sur l’appareil. Le code est exécuté lorsque la méthode directe « rebootDevice » est appelée à partir d’une application de service. La méthode appelle send_method_response pour envoyer un accusé de réception de réponse de méthode directe à l’application appelante.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

Exemples d’appareils SDK

Le Kit de développement logiciel (SDK) Azure IoT pour Python fournit un exemple fonctionnel d’application d'appareil qui gère les tâches de méthode directe. Pour plus d’informations, consultez la méthode de réception directe.

Créer une application back-end

Cette section décrit comment utiliser une application de service back-end pour appeler une méthode directe sur un appareil.

La classe IoTHubRegistryManager expose toutes les méthodes requises pour créer une application back-end afin d’envoyer des messages à un appareil.

Instructions d’importation de service

Ajoutez ces instructions d’importation pour vous connecter à Iot Hub, envoyer des méthodes directes cloud-à-appareil et recevoir des réponses de méthode directe d’appareil.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

  • Stratégie d’accès partagé
  • Microsoft Entra

Important

Cet article comprend les étapes à suivre pour se connecter à un service à l’aide d’une signature d’accès partagé. Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification à un service avec Microsoft Entra ID ou des identités managées est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité du cloud.

Se connecter à l’aide d’une stratégie d’accès partagé

Connectez-vous à IoT Hub à l’aide de fromConnectionString.

Pour invoquer une méthode directe sur un appareil via l’IoT Hub, 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.

En tant que paramètre de from_connection_string, fournissez la stratégie d’accès partagé service. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

Par exemple :

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Python, consultez Authentifier des applications Python auprès des services Azure à l’aide du Kit de développement logiciel (SDK) Azure pour Python

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

  • Clè secrète client
  • Certificat
  • Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour Python.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Microsoft Entra nécessite ce package d’importation et l’instruction import correspondante :

pip install azure-identity

from azure.identity import DefaultAzureCredential

Dans cet exemple, l’ID de locataire, l’ID client et la clé secrète client d’inscription de l’application Microsoft Entra ont été ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par DefaultAzureCredential pour authentifier l’application. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à une méthode de connexion IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Le jeton AccessToken résultant peut ensuite être passé à from_token_credential pour se connecter à IoT Hub pour n’importe quel client du kit SDK qui accepte les informations d’identification Microsoft Entra :

from_token_credential nécessite deux paramètres :

  • URL du service Azure : l’URL du service Azure doit être au format {Your Entra domain URL}.azure-devices.net sans préfixe https://. Par exemple : MyAzureDomain.azure-devices.net.
  • Jeton d’informations d’identification Azure

Dans cet exemple, les informations d’identification Azure sont obtenues en utilisant DefaultAzureCredential. L’URL et les informations d’identification du service Azure sont ensuite fournies à IoTHubRegistryManager.from_token_credential pour créer la connexion à IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)
Exemples de code

Pour obtenir des exemples d’authentification du service Microsoft Entra, consultez Bibliothèque d’authentification Microsoft (MSAL) pour Python.

Appeler une méthode sur un appareil

Vous pouvez appeler une méthode directe par nom sur un appareil. Le nom de la méthode identifie la méthode. Dans l’exemple d’appareil suivant et précédent illustré dans Créer un rappel de méthode directe, le nom de la méthode directe est « rebootDevice ».

Pour appeler une méthode directe sur un appareil :

  1. Créez un objet CloudToDeviceMethod. Fournissez le nom de la méthode et la charge utile en tant que paramètres.
  2. Appelez invoke_device_method pour appeler une méthode directe sur un appareil. Fournissez l’ID de l’appareil et l’objet de charge CloudToDeviceMethod utile en tant que paramètres.

Cet exemple appelle CloudToDeviceMethod pour invoquer une méthode directe nommée « rebootDevice » sur un appareil. Une fois la méthode directe appelée, la charge utile de réponse de la méthode directe s’affiche.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

Exemples de services Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) Azure IoT pour Python fournit des exemples de travail d’applications de service qui gèrent des tâches de méthode directe. Pour plus d’informations, consultez l’article suivant :

  • Nécessite Node.js version 10.0.x ou ultérieure

Vue d’ensemble

Cet article décrit comment utiliser les kits de développement logiciel (SDK) Azure IoT pour Node.js afin de créer le code d’application de l’appareil et du service back-end pour les méthodes directes de l’appareil.

Créer une application d’appareil

Cette section explique comment utiliser le code d’application d’appareil pour créer un rappel de méthode directe.

Installer les packages du Kit de développement logiciel (SDK)

Le package azure-iot-device contient des objets qui s’interfacent avec les appareils IoT. Exécutez cette commande pour installer le SDK d’appareil azure-iot-device sur votre ordinateur de développement :

npm install azure-iot-device --save

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

Installez les protocoles de transport nécessaires sur votre ordinateur de développement.

Par exemple, cette commande installe le protocole Amqp :

npm install azure-iot-device-amqp --save

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.

Créer un objet client

Créer un objet Client à l’aide du package installé.

Par exemple :

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

Créer un objet de protocole

Créez un objet Protocol à l’aide d’un package de transfert installé.

Cet exemple affecte le protocole AMQP :

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

Ajouter la chaîne de connexion d’appareil et le protocole de transfert

Appelez fromConnectionString pour fournir des paramètres de connexion d’appareil :

  • connStr – Chaîne de connexion de l’appareil.
  • transportCtor : protocole de transport.

Cet exemple utilise le protocole de transfert Amqp :

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Ouvrir la connexion à IoT Hub

Utilisez la méthode ouvrir pour ouvrir la connexion entre un appareil IoT et IoT Hub.

Par exemple :

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Créer un rappel de méthode directe

Appelez onDeviceMethod pour créer une fonction de gestionnaire de rappel ou coroutine appelée lorsqu’une méthode directe est reçue. L’écouteur est associé à un mot clé nom de méthode, tel que « redémarrage ». Le nom de la méthode peut être utilisé dans une application IoT Hub ou back-end pour déclencher la méthode de rappel sur l’appareil.

La fonction de gestionnaire de rappel doit appeler response.send pour envoyer un message d’accusé de réception de réponse à l’application appelante.

Cet exemple montre comment configurer un gestionnaire de méthode directe nommé onReboot appelé lorsque le nom de la méthode directe « redémarrage » est utilisé.

client.onDeviceMethod('reboot', onReboot);

Dans cet exemple, la méthode de rappel onReboot implémente la méthode directe sur l’appareil. Le code est exécuté lorsque la méthode directe « redémarrage » est appelée à partir d’une application de service. La fonction appelle response.send pour envoyer un message d’accusé de réception de réponse à l’application appelante.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

Exemples d’appareils SDK

Le Kit de développement logiciel (SDK) Azure IoT pour Node.js fournit des exemples fonctionnels d’applications d’appareils qui gèrent les tâches de gestion des appareils. Pour plus d’informations, consultez l’article suivant :

Créer une application back-end

Cette section explique comment appeler une méthode directe sur un appareil.

Installer le package de Kit de développement logiciel (SDK) de service

Exécutez cette commande pour installer azure-iothub sur votre machine de développement :

npm install azure-iothub --save

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

  • Stratégie d’accès partagé
  • Microsoft Entra

Important

Cet article comprend les étapes à suivre pour se connecter à un service à l’aide d’une signature d’accès partagé. Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification à un service avec Microsoft Entra ID ou des identités managées est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité du cloud.

Se connecter à l’aide d’une stratégie d’accès partagé

Utilisez fromConnectionString pour vous connecter au hub IoT Hub.

Pour invoquer une méthode directe sur un appareil via l’IoT Hub, 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.

En tant que paramètre, fournissez la chaîne de connexion de CreateFromConnectionStringstratégie d’accès partagé du service. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Node.js, consultez :

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

  • Clè secrète client
  • Certificat
  • Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour JavaScript.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Microsoft Entra nécessite ce package :

npm install --save @azure/identity

Dans cet exemple, l’ID de locataire, l’ID client et la clé secrète client d’inscription de l’application Microsoft Entra ont été ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par DefaultAzureCredential pour authentifier l’application. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à une méthode de connexion IoT Hub.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Le jeton d’informations d’identification résultant peut ensuite être passé à fromTokenCredential pour se connecter à IoT Hub pour n’importe quel client du kit SDK qui accepte les informations d’identification Microsoft Entra :

fromTokenCredential nécessite deux paramètres :

  • URL du service Azure : l’URL du service Azure doit être au format {Your Entra domain URL}.azure-devices.net sans préfixe https://. Par exemple : MyAzureDomain.azure-devices.net.
  • Jeton d’informations d’identification Azure

Dans cet exemple, les informations d’identification Azure sont obtenues en utilisant DefaultAzureCredential. L’URL et les informations d’identification du domaine Azure sont ensuite fournies à Registry.fromTokenCredential pour créer la connexion à IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);
Exemples de code

Pour obtenir des exemples fonctionnels d’authentification auprès du service Microsoft Entra, consultez Exemples d’identité Azure.

Appeler une méthode sur un appareil

Utilisez invokeDeviceMethod pour appeler une méthode directe par nom sur un appareil. Le paramètre de nom de méthode identifie la méthode directe.

Cet exemple appelle la méthode « redémarrage » pour lancer un redémarrage sur l’appareil. La méthode « redémarrage » est mappée à une fonction de gestionnaire de rappel sur l’appareil, comme décrit dans la section Créer un rappel de méthode directe de cet article.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

Exemples de services Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) Azure IoT pour Node.js fournit des exemples fonctionnels d’applications de service qui gèrent les tâches de gestion des appareils. Pour plus d’informations, consultez l’article suivant :