Partager via

Prise en main des identités de module IoT Hub et des jumeaux d’identité de module

  • Article

Les identités de module et les jumeaux d’identité de module sont similaires aux identités d’appareil et aux jumeaux d’appareil Azure IoT Hub, mais offrent une meilleure granularité. Contrairement aux identités d’appareil et aux jumeaux d’appareil Azure IoT Hub qui permettent à l’application back-end de configurer un appareil et d’obtenir une visibilité sur les conditions de l’appareil, une identité de module et un jumeau d’identité de module fournissent ces capacités pour les composants individuels d’un appareil. Sur les appareils compatibles qui intègrent plusieurs composants, par exemple des appareils basés sur un système d’exploitation ou des appareils avec un microprogramme, les identités de module et les jumeaux d’identité de module permettent d’isoler la configuration et les conditions de chacun de ces composants. Pour plus d'informations, consultez Comprendre les jumeaux de module Azure IoT Hub.

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.

Cet article explique comment développer deux types d’applications :

  • Applications d’appareil qui affichent et mettent à jour les propriétés signalées du jumeau d’identité de module et gèrent les demandes de mise à jour des propriétés souhaitées.
  • Applications de service qui peuvent lire et définir les propriétés souhaitées de l’identité de module.

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 IoT Hub

  • Une identité de module d’appareil IoT Hub

  • 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 les Kits de développement logiciel (SDK) Azure IoT pour .NET afin de créer du code d’application de service back-end et d’appareil pour les jumeaux d’identité de module.

Créer une application d’appareil

Cette section explique comment utiliser le code d’application d’appareil pour :

  • Récupérer un jumeau d’identité de module et examiner les propriétés signalées
  • Mettre à jour les propriétés du jumeau d’identité de module signalées
  • Créer un gestionnaire de rappel de mise à jour de propriété souhaitée du module

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 ModuleClient expose toutes les méthodes nécessaires pour interagir avec les jumeaux d’identité de module à partir de l’appareil.

Connectez-vous à l’appareil à l’aide de la méthode CreateFromConnectionString avec la chaîne de connexion d’identité du module.

L’appel de CreateFromConnectionString sans paramètre de transport se connecte à l’aide du transport AMQP par défaut.

Cet exemple se connecte à l’appareil à l’aide du transport AMQP par défaut.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Récupérer un jumeau d’identité de module et examiner les propriétés

Appelez GetTwinAsync pour récupérer les propriétés actuelles du jumeau d’identité de module dans un objet Twin.

Cet exemple récupère et affiche les propriétés du jumeau d’identité de module au format JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

Mettre à jour les propriétés signalées du jumeau d’identité de module

Pour mettre à jour une propriété signalée de jumeau :

  1. Créez un objet TwinCollection pour la mise à jour de propriété signalée
  2. Mettez à jour une ou plusieurs propriétés signalées dans l’objet TwinCollection
  3. Utilisez UpdateReportedPropertiesAsync pour envoyer (push) les modifications de propriété signalées au service IoT Hub

Par exemple :

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Créer un gestionnaire de rappel de mise à jour de propriété souhaitée

Passez le nom de méthode du gestionnaire de rappel à SetDesiredPropertyUpdateCallbackAsync pour créer un gestionnaire de rappel de mise à jour de propriété souhaité qui s’exécute lorsqu’une propriété souhaitée est modifiée dans le jumeau d’identité du module.

Par exemple, cet appel configure le système pour notifier une méthode nommée OnDesiredPropertyChangedAsync chaque fois qu’une propriété de module souhaitée est modifiée.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Les propriétés de jumeau d’identité de module sont passées à la méthode de rappel en tant que TwinCollection et peuvent être examinées comme des structures KeyValuePair.

Cet exemple reçoit les mises à jour de propriété souhaitées sous la forme de TwinCollection, puis effectue une boucle et imprime les mises à jour de collection KeyValuePair. Après avoir effectué une boucle dans la collection KeyValuePair, le code appelle UpdateReportedPropertiesAsync pour mettre à jour la propriété signalée DateTimeLastDesiredPropertyChangeReceived pour conserver la dernière heure de mise à jour.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Exemple de module de Kit de développement logiciel (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 jumeau d’identité de module. Pour plus d’informations, consultez l’article suivant :

Créer une application back-end

Cette section explique comment lire et mettre à jour les champs d’identité du module.

La classe RegistryManager expose toutes les méthodes nécessaires pour créer une application back-end pour interagir avec des jumeaux d’identité de module à partir du service.

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;

Connexion à IoT Hub

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 à IoT Hub à l’aide de CreateFromConnectionString.

La méthode UpdateModuleAsync utilisée dans cette section nécessite l’autorisation de stratégie d'accès partagé Service Connect pour ajouter les propriétés souhaitées à un module. En tant que paramètre pour CreateFromConnectionString, fournissez une chaîne de connexion de stratégie d’accès partagé qui inclut l’autorisation Service Connect. 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 :

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.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, il est recommandé d’utiliser une autre méthode dans un environnement de production, y compris des TokenCredential spécifiques ou des ChainedTokenCredential simplifiées. 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.

Lire et mettre à jour les champs d’identité du module

Appelez GetModuleAsync pour récupérer les champs de jumeau d’identité de module actuel dans un objet Module.

La classe Module inclut properties qui correspondent aux sections d’un jumeau d’identité de module. Utilisez les propriétés de classe Module pour afficher et mettre à jour les champs de jumeau d’identité de module. Vous pouvez utiliser les propriétés de l’objet Module pour mettre à jour plusieurs champs avant d’écrire les mises à jour sur l’appareil à l’aide de UpdateModuleAsync.

Après avoir effectué des mises à jour de champ de jumeau d’identité de module, appelez UpdateModuleAsync pour écrire des mises à jour de champ d’objet Module sur un appareil. Utilisez la logique try et catch avec un gestionnaire d’erreurs pour intercepter les erreurs de correctif mal mis en forme à partir de UpdateModuleAsync.

Cet exemple récupère un module dans un objet Module, met à jour la propriété module LastActivityTime, puis met à jour le module dans IoT Hub à l’aide de UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

Autre API de module

Exemple de service de SDK

Le Kit de développement logiciel (SDK) Azure IoT pour .NET fournit un exemple fonctionnel d’application de service qui gère les tâches de jumeau d’identité de module. Pour plus d’informations, consultez Tests E2E du Gestionnaire de Registre.

  • 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 afin de créer du code d’application de service back-end et d’appareil pour les jumeaux d’identité de module.

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

La bibliothèque msrest est utilisée pour intercepter les exceptions HTTPOperationError.

pip install msrest

Créer une application d’appareil

Cette section explique comment utiliser le code d’application d’appareil pour :

  • Récupérer un jumeau d’identité de module et examiner les propriétés signalées
  • Mettre à jour les propriétés signalées du jumeau d’identité de module
  • Créer un gestionnaire de rappel de mise à jour de propriété souhaitée du jumeau d’identité de module

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.

Importer des instructions

Ajoutez cette instruction import pour utiliser la bibliothèque d’appareils.

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

Connexion à un appareil

La classe IoTHubModuleClient contient des méthodes qui peuvent être utilisées pour travailler avec des jumeaux d’identité de module.

Pour connecter une application à un appareil :

  1. Appeler create_from_connection_string pour ajouter la chaîne de connexion d’identité de module
  2. Appelez connect pour connecter le client d’appareil à un hub Azure IoT
# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

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

# connect the application to the device
await device_client.connect()

Récupérer un jumeau d’identité de module et examiner les propriétés

Appelez get_twin pour récupérer le jumeau d’identité de module à partir du service Azure IoT Hub. Les informations de jumeau sont placées dans une variable qui peut être examinée.

Cet exemple récupère le jumeau d’appareil et utilise la commande print pour afficher le jumeau d’appareil au format JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Mettre à jour les propriétés signalées du jumeau d’identité de module

Vous pouvez appliquer un correctif pour mettre à jour les propriétés signalées du jumeau d’identité de module au format JSON.

Pour appliquer un correctif pour mettre à jour les propriétés signalées :

  1. Affectez un correctif JSON de propriété signalée à une variable.
  2. Appelez patch_twin_reported_properties pour appliquer le correctif JSON aux propriétés signalées.

Par exemple :

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Créer un gestionnaire de rappel de mise à jour de propriété souhaitée du jumeau d’identité de module

Appelez on_twin_desired_properties_patch_received pour créer une fonction de gestionnaire ou une coroutine appelée lorsqu’un correctif de propriétés souhaitées de jumeau d’identité de module est reçu. Le gestionnaire prend un argument, qui est le correctif de jumeau sous la forme d’un objet de dictionnaire JSON.

Cet exemple montre comment configurer un gestionnaire de correctifs de propriétés souhaitées nommé twin_patch_handler.

Par exemple :

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

Le twin_patch_handler reçoit et imprime les mises à jour de propriétés souhaitées JSON.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Exemples d’appareils SDK

Le Kit de développement logiciel (SDK) Azure IoT pour Python fournit un exemple fonctionnel d’applications d’appareil qui gèrent les tâches de jumeau d’identité de module :

Créer une application back-end

Cette section explique comment créer une application back-end pour récupérer et mettre à jour les propriétés souhaitées du jumeau d’identité de module.

La classe IoTHubRegistryManager expose toutes les méthodes nécessaires pour créer une application back-end pour interagir avec des jumeaux d’identité de module à partir du service.

Instructions d’importation de service

Ajoutez cette instruction import pour utiliser la bibliothèque de service.

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

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.

La méthode update_module_twin utilisée dans cette section nécessite l’autorisation de stratégie d'accès partagé Service Connect pour ajouter les propriétés souhaitées à un module. En tant que paramètre pour from_connection_string, fournissez une chaîne de connexion de stratégie d’accès partagé qui inclut l’autorisation Service Connect. 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 shared access policy 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 du Kit de développement logiciel (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, il est recommandé d’utiliser une autre méthode dans un environnement de production, y compris des TokenCredential spécifiques ou des ChainedTokenCredential simplifiées. 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 cliente 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, la clé secrète client d’inscription de l’application Microsoft Entra, l’ID client et l’ID de locataire 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 AccessToken résultant peut ensuite être passé à from_token_credential pour se connecter à IoT Hub pour n’importe quel client du Kit de développement logiciel (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 à l’aide de 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.

Récupérer et mettre à jour les propriétés souhaitées du jumeau d’identité de module

Vous pouvez mettre à jour les propriétés souhaitées à partir d’une application back-end à l’aide de update_module_twin.

Pour récupérer et mettre à jour les propriétés souhaitées du jumeau d’identité de module :

  1. Appelez get_module_twin pour obtenir la version actuelle du jumeau d’identité de module.
  2. Utilisez la classe Twin pour ajouter les propriétés souhaitées au format JSON.
  3. Appelez update_module_twin pour appliquer le correctif au jumeau d’appareil. Vous pouvez également utiliser replace_module_twin pour remplacer les propriétés et balises souhaitées pour un jumeau d’identité de module.

Cet exemple met à jour la propriété souhaitée telemetryInterval pour 122.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

Exemple de service de SDK

Le Kit de développement logiciel (SDK) Azure IoT pour Python fournit un exemple fonctionnel d’application de service qui gère les tâches de jumeau de module d’identité d’appareil. Pour plus d’informations, consultez Tester le Gestionnaire de Registre IoTHub.

  • 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 du code d’application de service back-end et d’appareil pour les jumeaux d’identité de module.

Créer une application d’appareil

Cette section explique comment utiliser le package de azure-iot-device dans le SDK Azure IoT pour Node.js pour créer une application d’appareil pour :

  • Récupérer un jumeau d’identité de module et examiner les propriétés signalées
  • Mettre à jour les propriétés de jumeau signalées par l’identité du module
  • Recevoir une notification de modifications de propriété souhaitées du jumeau d’identité de module

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.

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

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

Le package azure-iot-device contient des objets qui s’interfacent avec les appareils IoT. La classe Twin inclut des objets spécifiques aux jumeaux. Cette section décrit le code de classe Client utilisé pour lire et écrire des données de jumeau d’identité de module d’appareil.

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 d’appareil.

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 du module d’identité IoT Hub.
  • transportCtor : protocole de transport.

Cet exemple utilise le protocole de transfert Amqp :

const deviceConnectionString = "{IoT hub identity module 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 une 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);
  }
})

Récupérer un jumeau d’identité de module et examiner les propriétés signalées

Appelez getTwin pour récupérer les informations actuelles du jumeau d’identité de module dans un objet Twin.

Le code de l’appareil peut ensuite accéder aux propriétés du jumeau d’identité de module.

Par exemple :

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Mettre à jour les propriétés signalées du jumeau d’identité de module

Utilisez update pour mettre à jour les propriétés signalées par l’appareil. Incluez un correctif au format JSON comme premier paramètre, et une méthode de rappel d’état d’exécution de fonction comme deuxième paramètre de la méthode.

Dans cet exemple, un correctif de jumeau d’identité de module au format JSON est stocké dans la variable patch. Le correctif contient une valeur de mise à jour connectivity du jumeau d’identité du module de cellular. Le correctif et le gestionnaire d’erreurs sont passés à la méthode update. En cas d’erreur, un message d’erreur de console s’affiche.

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Recevoir une notification de modifications de propriété souhaitées du jumeau d’identité de module

Créez un détecteur d’événements de mise à jour de propriété souhaitée de jumeau d’identité de module qui s’exécute lorsqu’une propriété souhaitée est modifiée en passant le nom de méthode du gestionnaire de rappel à twin.on.

Le détecteur d’événements de propriété souhaitée peut prendre la forme suivante :

  • Recevoir tous les correctifs avec un seul gestionnaire d’événements
  • Recevoir un événement si quelque chose change sous un regroupement de propriétés
  • Recevoir un événement pour une modification de propriété unique

Recevoir tous les correctifs avec un seul gestionnaire d’événements

Vous pouvez créer un écouteur pour recevoir toute modification de propriété souhaitée.

Cet exemple de code génère toutes les propriétés reçues par le service.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Recevoir un événement si quelque chose change sous un regroupement de propriétés

Vous pouvez créer un écouteur pour recevoir un événement si quelque chose sous un regroupement de propriétés change.

Par exemple :

  1. Les propriétés minTemperature et maxTemperature se trouvent sous un regroupement de propriétés nommé properties.desired.climate changes.

  2. Une application de service back-end applique ce correctif pour mettre à jour les propriétés souhaitées minTemperature et maxTemperature :

    const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };

  3. Ce code configure un détecteur d’événements de modification de propriété souhaitée qui déclenche toutes les modifications dans le regroupement de propriétés properties.desired.climate. S’il existe une modification de propriété souhaitée dans ce groupe, les messages de modification de température minimale et maximale sont affichés dans la console :

    twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});

Recevoir un événement pour une modification de propriété unique

Vous pouvez configurer un écouteur pour une modification de propriété unique. Dans cet exemple, le code de cet événement est exécuté uniquement si la valeur booléenne fanOn fait partie du correctif. Le code génère le nouvel état de fanOn souhaité chaque fois que le service le met à jour.

  1. Une application back-end applique ce correctif de propriété souhaitée :

     const twinPatch2 = {
  properties: {
    desired: {
      climate: {
        hvac: {
          systemControl: { fanOn: true, },
        },
      },
    },
  },
};

  2. L’écouteur se déclenche uniquement lorsque la propriété fanOn change :

     twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
     console.log('setting fan state to ' + fanOn);
  });

Exemple complet

Cet exemple encapsule les principes de cette section, notamment l’imbrication de fonctions de rappel à plusieurs niveaux.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Exemples pour le SDK d’appareils

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

Créer une application back-end

Cette section explique comment créer une application back-end qui récupère un jumeau d’identité de module et met à jour les propriétés souhaitées.

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

Créer un objet Registry

La classe Registry expose toutes les méthodes nécessaires pour interagir avec les jumeaux d’identité de module à partir d’une application back-end.

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

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.

La méthode update utilisée dans cette section nécessite l’autorisation de stratégie d'accès partagé Service Connect pour ajouter les propriétés souhaitées à un module. En tant que paramètre pour fromConnectionString, fournissez une chaîne de connexion de stratégie d’accès partagé qui inclut l’autorisation Service Connect. 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é.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

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 du Kit de développement logiciel (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, il est recommandé d’utiliser une autre méthode dans un environnement de production, y compris des TokenCredential spécifiques ou des ChainedTokenCredential simplifiées. 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 cliente 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, la clé secrète client d’inscription de l’application Microsoft Entra, l’ID client et l’ID de locataire 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 de développement logiciel (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 à l’aide de 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 du service Microsoft Entra, consultez Exemples d’identité Azure.

Récupérer un jumeau d’identité de module et mettre à jour les propriétés souhaitées

Vous pouvez créer un correctif qui contient des mises à jour de propriétés souhaitées pour un jumeau d’identité de module.

Pour mettre à jour un jumeau d’identité de module :

  1. Appelez getModuleTwin pour récupérer l’objet Twin de l’appareil.

  2. Mettez en forme un correctif qui contient la mise à jour du jumeau d’identité de module. Le correctif est mis en forme au format JSON, comme décrit dans classe Twin. Un correctif de service back-end contient les mises à jour de propriétés souhaitées. Pour plus d’informations sur le format des correctifs, consultez Format de balises et de propriétés.

  3. Appelez update pour mettre à jour le jumeau d’identité du module avec le correctif.

Dans cet exemple, le jumeau d’identité de module est récupéré pour myDeviceId et myModuleId. Ensuite, un correctif est appliqué aux jumeaux qui contiennent des informations climate.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Exemples du Kit de développement logiciel (SDK) de service

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 jumeau d’identité de module. Pour plus d’informations, consultez l’article suivant :