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

Article
03/19/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 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, les identités de module et les jumeaux de module fournissent ces fonctionnalités pour les composants individuels d’un appareil. Sur les appareils compatibles qui intègrent plusieurs composants, par exemple des appareils sur un système d’exploitation ou des appareils avec un microprogramme, ils 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 ce tutoriel, vous disposerez de trois applications Python :

CreateModule : crée une identité d’appareil, une identité de module et des clés de sécurité associées pour connecter votre appareil et vos clients de module.
UpdateModuleTwinDesiredProperties : envoie à votre hub IoT les propriétés souhaitées de votre jumeau de module mises à jour.
ReceiveModuleTwinDesiredPropertiesPatch : reçoit le correctif des propriétés souhaitées du jumeau de module sur votre appareil.

Notes

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

Prérequis

Un compte Azure actif. (Si vous ne possédez pas de compte, vous pouvez créer un compte gratuit en quelques minutes seulement.)
Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.
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.

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) dans un 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. Ce service nécessite l’autorisation Écriture du registre (qui comprend également Lecture du registre). Vous créerez aussi un service qui ajoute les propriétés souhaitées au jumeau de module pour le module nouvellement créé. Ce service a besoin de l’autorisation Connexion de service. Bien qu’il existe des stratégies d’accès partagé par défaut qui accordent ces autorisations individuellement, dans cette section, vous allez créer une stratégie d’accès partagé personnalisée qui contient ces deux autorisations.

Pour créer une stratégie d’accès partagé qui accorde des autorisations de connexion de service et d’écriture du registre, et obtenir une chaîne de connexion pour cette stratégie, 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 le menu au-dessus de la liste des stratégies, sélectionnez Ajouter une stratégie d'accès partagé.
Sous Ajouter une stratégie d’accès partagé, entrez un nom descriptif pour votre stratégie, par exemple serviceAndRegistryReadWrite. Sous Autorisations, sélectionnez Écriture du registre et Connexion du service, puis sélectionnez Ajouter. (l’autorisation Lecture du registre est incluse automatiquement lorsque vous sélectionnez Écriture du Registre).
Sélectionnez votre nouvelle stratégie dans la liste des stratégies.
Sous Clés d’accès partagé, sélectionnez l’icône de copie pour la Chaîne de connexion principale et 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éer une identité d’appareil et une identité de module dans IoT Hub

Dans cette section, vous allez créer une application de service Python qui crée une identité d’appareil et une identité de module dans le registre des identités de votre hub IoT. Un appareil ou un module ne peut se connecter à un hub IoT que s’il a une entrée dans le registre des identités. Pour plus d’informations, consultez Comprendre le registre des identités dans votre IoT Hub. En exécutant cette application console, une clé et un ID uniques sont générés pour chaque appareil et module. L’ID et la clé respectent la casse. Votre appareil et le module utilisent ces valeurs pour s’identifier lorsqu’ils envoient des messages d’appareil-à-cloud à IoT Hub.

À partir de votre invite de commandes, exécutez la commande suivante pour installer le package azure-iot-hub :
```
pip install azure-iot-hub
```
À partir de votre invite de commandes, exécutez la commande suivante pour installer le package msrest : Vous avez besoin de ce package pour intercepter les exceptions HTTPOperationError.
```
pip install msrest
```
À l’aide d’un éditeur de texte, créez un fichier nommé CreateModule.py dans votre répertoire de travail.

Ajoutez le code suivant à votre fichier Python. Remplacez YourIoTHubConnectionString par la chaîne de connexion que vous avez copiée dans Obtenir la chaîne de connexion du hub IoT.

import sys
from msrest.exceptions import HttpOperationError
from azure.iot.hub import IoTHubRegistryManager

CONNECTION_STRING = "YourIotHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    try:
        # CreateDevice - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        device_state = "enabled"
        new_device = iothub_registry_manager.create_device_with_sas(
            DEVICE_ID, primary_key, secondary_key, device_state
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the device already exists.
            new_device = iothub_registry_manager.get_device(DEVICE_ID)
        else:
            raise

    print("device <" + DEVICE_ID +
          "> has primary key = " + new_device.authentication.symmetric_key.primary_key)

    try:
        # CreateModule - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        managed_by = ""
        new_module = iothub_registry_manager.create_module_with_sas(
            DEVICE_ID, MODULE_ID, managed_by, primary_key, secondary_key
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the module already exists.
            new_module = iothub_registry_manager.get_module(DEVICE_ID, MODULE_ID)
        else:
            raise

    print("device/module <" + DEVICE_ID + "/" + MODULE_ID +
          "> has primary key = " + new_module.authentication.symmetric_key.primary_key)

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

À l’invite de commandes, exécutez la commande suivante :
```
python CreateModule.py
```

Cette application crée une identité d’appareil avec l’ID myFirstDevice et une identité de module avec l’ID myFirstModule sous l’appareil myFirstDevice. (Si l’ID de module ou d’appareil existe déjà dans le registre des identités, le code récupère simplement les informations existantes du module ou de l’appareil). L’application affiche l’ID et la clé primaire pour chaque identité.

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é à IoT 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, consultez Comprendre le registre des identités dans votre IoT Hub.

Mettre à jour le jumeau de module à l’aide du SDK de service Python

Dans cette section, vous allez créer une application de service Python qui met à jour les propriétés souhaitées du jumeau de module.

À l’invite de commandes, exécutez la commande suivante pour installer le package azure-iot-hub. Vous pouvez ignorer cette étape si vous avez installé le package azure-iot-hub dans la section précédente.
```
pip install azure-iot-hub
```
À l’aide d’un éditeur de texte, créez un fichier nommé UpdateModuleTwinDesiredProperties.py dans votre répertoire de travail.

Ajoutez le code suivant à votre fichier Python. Remplacez YourIoTHubConnectionString par la chaîne de connexion que vous avez copiée dans Obtenir la chaîne de connexion du hub IoT.

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

CONNECTION_STRING = "YourIoTHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module 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 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" )

Recevoir les mises à jour du côté appareil

Dans cette section, vous allez créer une application Python pour obtenir la mise à jour des propriétés souhaitées du jumeau de module sur votre appareil.

Obtenez la chaîne de connexion de votre module. Dans le portail Azure, accédez à votre hub IoT et sélectionnez Appareils dans le volet gauche. Sélectionnez myFirstDevice dans la liste des appareils et ouvrez-le. Sous Identités de module, sélectionnez myFirstModule. Sélectionnez l’icône de copie pour Chaîne de connexion (clé primaire). Vous avez besoin de cette chaîne de connexion dans une étape suivante.
À partir de votre invite de commandes, exécutez la commande suivante pour installer le package azure-iot-device :
```
pip install azure-iot-device
```
À l’aide d’un éditeur de texte, créez un fichier nommé ReceiveModuleTwinDesiredPropertiesPatch.py dans votre répertoire de travail.

Ajoutez le code suivant à votre fichier Python. Remplacez YourModuleConnectionString par la chaîne de connexion de module que vous avez copiée à l’étape 1.

import time
from azure.iot.device import IoTHubModuleClient

CONNECTION_STRING = "YourModuleConnectionString"


def twin_patch_handler(twin_patch):
    print("")
    print("Twin desired properties patch received:")
    print(twin_patch)


def main():
    print ("Starting the IoT Hub Python sample...")
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Attach the handler to the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler

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

if __name__ == '__main__':
    main()

Exécuter les applications

Dans cette section, vous allez exécuter l’application d’appareil ReceiveModuleTwinDesiredPropertiesPatch, puis exécuter l’application de service UpdateModuleTwinDesiredProperties pour mettre à jour les propriétés souhaitées de votre module.

Ouvrez une invite de commandes et exécutez l’application d’appareil :
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
Ouvrez une invite de commandes distincte et exécutez l’application de service :
```
python UpdateModuleTwinDesiredProperties.py
```
Notez que la propriété souhaitée TelemetryInterval apparaît dans le jumeau de module mis à jour dans la sortie de votre application de service :

La même propriété apparaît dans le correctif des propriétés souhaitées reçu dans la sortie de votre application d’appareil :

Étapes suivantes

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

Partager via

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

Prérequis

Authentification Module

Obtenir la chaîne de connexion du hub IoT

Créer une identité d’appareil et une identité de module dans IoT Hub

Mettre à jour le jumeau de module à l’aide du SDK de service Python

Recevoir les mises à jour du côté appareil

Exécuter les applications

Étapes suivantes

Commentaires

Commentaires

Ressources supplémentaires