Bien démarrer avec l’identité de module et le jumeau de module IoT Hub (.NET)

Article
03/22/2023

Les identités de module et les jumeaux de module sont similaires aux identités d’appareil et aux jumeaux d’appareil Azure IoT Hub, mais offrent un plus grand niveau de détail. Contrairement à l’identité d’appareil et au jumeau 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 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 de module permettent d’isoler la configuration et les conditions de chacun de ces composants.

Notes

Les fonctionnalités décrites dans cet article sont uniquement disponibles au niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.

À la fin de cet article, vous disposez de deux applications de console .NET :

CreateIdentities : crée une identité d’appareil, une identité de module et une clé de sécurité associée pour connecter votre appareil et vos clients de module.
UpdateModuleTwinReportedProperties : envoie à votre IoT Hub les propriétés à jour de votre jumeau de module.

Notes

Pour plus d’informations sur les outils SDK disponibles pour créer des applications d’appareil et de back-end, consultez les SDK Azure IoT.

Prérequis

Visual Studio.
Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.

Authentification Module

Vous pouvez utiliser des clés symétriques ou des certificats X.509 pour authentifier les identités de module. Pour l’authentification par certificat X.509, le certificat du module doit avoir son nom commun (Common Name/CN) formaté comme CN=<deviceid>/<moduleid>. Par exemple :

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous allez créer un service back-end qui ajoute un appareil dans le registre des identités, puis ajoute un module à cet appareil. Votre service a besoin de l’autorisation Écriture du registre. Par défaut, chaque hub IoT est créé avec une stratégie d’accès partagé nommée registryReadWrite qui accorde cette autorisation.

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

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

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

Création d’un module d’identité

Dans cette section, vous allez créer une application console .NET qui crée une identité d’appareil et une identité de module dans le registre d’identités de votre Hub. Un appareil ou un module ne peut pas se connecter à Hub, à moins de posséder une entrée dans le registre des identités. Pour plus d’informations, consultez la section Registre des identités du Guide du développeur IoT Hub.

En exécutant cette application console, une clé et un ID uniques sont générés pour chaque appareil et module. Votre appareil et le module utilisent ces valeurs pour s’identifier lorsqu’ils envoient des messages d’appareil-à-cloud à IoT Hub. Les ID sont sensibles à la casse.

Ouvrez Visual Studio et sélectionnez Créer un projet.
Dans Créer un projet, sélectionnez Application console (.NET Framework).
Sélectionnez Suivant pour ouvir Configurer votre nouveau projet. Nommez le projet CreateIdentities, puis sélectionnez Suivant.
Conservez l’option .NET Framework par défaut et sélectionnez Créer pour créer votre projet.
Dans Visual Studio, ouvrez Outils>Gestionnaire de package NuGet>Gérer les packages NuGet pour la solution. Sélectionnez l’onglet Parcourir.
Recherchez Microsoft.Azure.Devices. Sélectionnez-le, puis sélectionnez Installer.

Ajoutez les instructions using suivantes en haut du fichier Program.cs :

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;

Ajoutez les champs suivants à la classe Program . Remplacez la valeur d’espace réservé par la chaîne de connexion IoT Hub pour le hub créé dans la section précédente.
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

Ajoutez le code suivant à la classe Main.

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

Ajoutez les méthodes suivantes à la classe Program :
```
private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}
```
La méthode AddDeviceAsync crée une identité d’appareil avec l’ID myFirstDevice. Si cet ID d’appareil existe déjà dans le registre d’identité, le code récupère simplement les informations d’appareil existantes. L’application affiche ensuite la clé primaire pour cette identité. Vous utilisez cette clé dans l’application de périphérique simulé pour vous connecter à votre Hub.

La méthode AddModuleAsync crée une identité de module avec l’ID myFirstModule sous l’appareil myFirstDevice. Si cet ID de module existe déjà dans le registre d’identité, le code récupère simplement les informations existantes du module. L’application affiche ensuite la clé primaire pour cette identité. Vous utilisez cette clé dans l’application de module simulé pour vous connecter à votre Hub.

Important

L’ID d’appareil étant potentiellement visible dans les journaux d’activité collectés à des fins de support technique et de dépannage, assurez-vous de ne pas utiliser d’informations sensibles en attribuant un nom à votre appareil.
Exécutez cette application et notez la clé de l’appareil et la clé du module.

Notes

Le registre des identités IoT Hub stocke uniquement les identités des appareils et des modules pour permettre un accès sécurisé à Hub. Le registre des identités stocke les ID et les clés d’appareil à utiliser en tant qu’informations d’identification de sécurité. Il stocke également un indicateur activé/désactivé pour chaque appareil pouvant être utilisé pour désactiver l’accès de cet appareil. Si votre application a besoin de stocker d’autres métadonnées spécifiques aux appareils, elle doit utiliser un magasin spécifique aux applications. Il n’y a aucun indicateur d’activation/désactivation pour les identités de module. Pour plus d’informations, reportez-vous au Guide du développeur IoT Hub.

Mettre à jour le jumeau de module à l’aide du SDK d’appareil .NET

Nous allons maintenant tenter d’établir une communication entre votre appareil simulé et le cloud. Une fois que vous avez créé une identité de module, un jumeau de module est implicitement créé dans IoT Hub. Dans cette section, vous allez créer sur votre appareil simulé une application de console .NET qui met à jour les propriétés déclarées du jumeau de module.

Pour récupérer votre chaîne de connexion de module, accédez à votre hub IoT, puis sélectionnez Appareils. Trouvez et sélectionnez myFirstDevice pour l’ouvrir, puis myFirstModule pour l’ouvrir. Dans Détails de l’identité de module, copiez la Chaîne de connexion (clé primaire) et enregistrez-la pour l’application console.

Dans Visual Studio, ajoutez un nouveau projet à votre solution en sélectionnant Fichier>Nouveau>Projet. Dans Créer un nouveau projet, sélectionnez Application console (.NET Framework), puis Suivant.
Dans Configurer votre nouveau projet, nommez le projet UpdateModuleTwinReportedProperties, puis sélectionnez Suivant.
Conservez l’option .NET Framework par défaut et sélectionnez Créer pour créer votre projet.
Dans Visual Studio, ouvrez Outils>Gestionnaire de package NuGet>Gérer les packages NuGet pour la solution. Sélectionnez l’onglet Parcourir.
Recherchez et sélectionnez Microsoft.Azure.Devices.Client, puis sélectionnez Installer.

Ajoutez les instructions using suivantes en haut du fichier Program.cs :

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

Ajoutez les champs suivants à la classe Program . Remplacez la valeur de l’espace réservé par la chaîne de connexion du module.

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

Ajoutez la méthode suivante OnDesiredPropertyChanged à la classe Program :

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

Ajoutez les lignes suivantes à la méthode Main :

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

Maintenant, vous savez comment récupérer le jumeau de module et mettre à jour les propriétés déclarées avec le protocole AMQP.

Si vous le souhaitez, vous pouvez ajouter ces instructions à la méthode Main pour envoyer un événement à IoT Hub à partir de votre module. Placez ces lignes sous le bloc try catch.

Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");

Exécuter les applications

Vous pouvez maintenant exécuter les applications.

Dans Visual Studio, dans l’Explorateur de solutions, cliquez avec le bouton droit sur votre solution, puis sélectionnez Définir les projets de démarrage.
Sous Propriétés communes, sélectionnez Projet de démarrage.
Sélectionnez Plusieurs projets de démarrage, puis choisissez l’action Démarrer pour les applications et OK pour accepter vos modifications.
Appuyez sur F5 pour démarrer les applications.

Étapes suivantes

Pour continuer la prise en main de IoT Hub et explorer les autres scénarios IoT, consultez les articles suivants :

Bien démarrer avec l’identité de module et le jumeau de module IoT Hub (.NET)

Prérequis

Authentification Module

Obtenir la chaîne de connexion du hub IoT

Création d’un module d’identité

Mettre à jour le jumeau de module à l’aide du SDK d’appareil .NET

Exécuter les applications

Étapes suivantes

Ressources supplémentaires