Prise en main des jumeaux d’appareil (Azure CLI)

• INTERFACE DE LIGNE DE COMMANDE
• .NET
• Python
• Node.JS
• Java

Les jumeaux d’appareil sont des documents JSON qui stockent des informations sur l’état des appareils (métadonnées, configurations et conditions). IoT Hub conserve une représentation d’appareil pour chaque appareil que vous y connectez.

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.

Vous pouvez utiliser des jumeaux d’appareil pour répondre aux besoins suivants :

• Stockez les métadonnées d’appareil à partir de votre serveur principal de solution.

• Signaler les informations d’état actuel, telles que les capacités disponibles et les conditions, par exemple la méthode de connectivité utilisée, à partir de votre application d’appareil

• Synchronisez l’état des workflows de longue durée, par exemple les mises à jour de microprogramme et de configuration, entre une application d’appareil et une application back-end.

• Interroger les métadonnées, la configuration ou l’état de vos appareils

Les représentations d’appareil sont conçues pour les synchronisations et pour l’interrogation des configurations et des conditions d’appareil. Pour plus d’informations sur les jumeaux d’appareil, notamment quand utiliser des jumeaux d’appareil, consultez Comprendre les jumeaux d’appareil.

Les hubs IoT stockent des jumeaux d’appareil, qui contiennent les éléments suivants :

• Tags (balises). Métadonnées d’appareil uniquement accessibles par le back-end de solution.

• Propriétés souhaitées (Desired) . Objets JSON modifiables par le back-end de solution et observables par l’application d’appareil.

• Propriétés signalées (Reported) . Objets JSON modifiables par l’application d’appareil et consultables par le back-end de solution.

Les balises et les propriétés ne peuvent pas contenir de tableaux, mais peuvent contenir des objets imbriqués.

L’illustration suivante montre l’organisation des jumeaux d’appareil :

En outre, le serveur principal de solution peut interroger les représentations d’appareil concernant toutes les données ci-dessus. Pour plus d’informations sur les jumeaux d’appareil, consultez Présentation des jumeaux d’appareil. Pour plus d’informations sur l’interrogation, consultez Langage de requête IoT Hub.

Cet article vous montre comment :

• Utilisez un appareil simulé pour signaler son canal de connectivité en tant que propriété signalée sur le jumeau d’appareil.

• Interrogez les appareils en utilisant des filtres sur les étiquettes et les propriétés précédemment créées.

Pour plus d’informations sur l’utilisation des propriétés signalées de jumeau d’appareil, consultez Conseils de communication appareil-à-cloud.

Cet article vous montre comment créer deux sessions Azure CLI :

• Session qui crée un appareil simulé. L’appareil simulé signale son canal de connectivité en tant que propriété signalée sur le jumeau d’appareil correspondant de l’appareil lors de l’initialisation.

• Session qui met à jour les étiquettes du jumeau d’appareil pour l’appareil simulé, puis interroge les appareils à partir de votre hub IoT. Les requêtes utilisent des filtres basés sur les étiquettes et les propriétés précédemment mises à jour dans les deux sessions.

Prérequis

• Azure CLI. Vous pouvez également exécuter toutes les commandes dans ce démarrage rapide à l’aide d’Azure Cloud Shell, un interpréteur de commandes CLI interactif qui s’exécute dans votre navigateur ou dans une application telle que Terminal Windows. Si vous utilisez Cloud Shell, vous n’avez rien à installer. Si vous préférez utiliser l’interface de ligne de commande en local, cet article nécessite Azure CLI version 2.36 ou ultérieure. Exécutez az --version pour trouver la version. Pour installer ou mettre à niveau localement Azure CLI, consultez Installer Azure CLI.

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

• Assurez-vous que le port 8883 est ouvert dans votre pare-feu. Les exemples décrits dans cet article utilisent le protocole MQTT qui communique via le port 8883. Il est possible de bloquer ce port 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).

Préparer le Cloud Shell

Si vous souhaitez utiliser Azure Cloud Shell, vous devez d’abord le lancer et le configurer. Si vous utilisez l’interface CLI localement, passez à la section Préparer deux sessions CLI.

1. Sélectionnez l’icône Cloud Shell dans l’en-tête de page dans le Portail Azure.

   

   Notes

   S’il s’agit de la première fois que vous utilisez Cloud Shell, vous êtes invité à créer un stockage, requis pour utiliser Cloud Shell. Sélectionnez un abonnement pour créer un compte de stockage et un partage Microsoft Azure Files.

2. Utilisez le sélecteur d’environnement dans la barre d’outils Cloud Shell pour sélectionner votre environnement CLI préféré. Cet article utilise l’environnement Bash. Vous pouvez également utiliser l’environnement PowerShell.

   Notes

   Certaines commandes nécessitent une syntaxe ou une mise en forme différente dans les environnements Bash et PowerShell. Pour plus d’informations, consultez Conseils pour l’utilisation réussie d’Azure CLI.

   

Préparer deux sessions CLI

Vous devez ensuite préparer deux sessions Azure CLI. Si vous utilisez le Cloud Shell, vous allez exécuter ces sessions dans des onglets Cloud Shell distincts. Si vous utilisez un client CLI local, vous exécuterez deux instances CLI distinctes. Utilisez les sessions CLI distinctes pour les tâches suivantes :

• La première session simule un appareil IoT qui communique avec votre IoT Hub.
• La deuxième session met à jour votre appareil simulé et interroge votre hub IoT.

1. Si vous utilisez le service Cloud Shell, passez à l’étape suivante. Sinon, exécutez la commande az login dans la première session CLI pour vous connecter à votre compte Azure.

   Si vous utilisez le service Cloud Shell, vous êtes automatiquement connecté à votre compte Azure. Toutes les communications entre votre session Azure CLI et votre hub IoT sont authentifiées et chiffrées. Par conséquent, cet article n’a pas besoin d’une authentification supplémentaire que vous utiliseriez avec un appareil réel, comme une chaîne de connexion. Pour plus d’informations sur la connexion avec Azure CLI, consultez Se connecter avec Azure CLI.

   az login
   

2. Dans la première session CLI, exécutez la commande az extension add. La commande ajoute l’extension Microsoft Azure IoT pour Azure CLI dans votre shell CLI. L’extension ajoute des commandes IoT Hub, IoT Edge et du service IoT Hub Device Provisioning (DPS) à Azure CLI. Après l’installation de l’extension, vous n’avez pas besoin de l’installer à nouveau dans une session Cloud Shell.

   az extension add --name azure-iot
   

   Notes

   Cet article utilise la version la plus récente de l’extension Azure IoT, appelée azure-iot. La version héritée est appelée azure-cli-iot-ext. Une seule version doit être installée à la fois. Vous pouvez utiliser la commande az extension list pour valider les extensions actuellement installées.

   Utilisez az extension remove --name azure-cli-iot-ext pour supprimer la version héritée de l’extension.

   Utilisez az extension add --name azure-iot pour ajouter la nouvelle version de l’extension.

   Pour voir les extensions que vous avez installées, utilisez az extension list.

3. Ouvrez une deuxième session CLI. Si vous utilisez le Cloud Shell dans un navigateur, sélectionnez l’icône Ouvrir une nouvelle session dans la barre d’outils de votre première session CLI. Si vous utilisez l’interface CLI localement, ouvrez une deuxième instance.

   

Créer et simuler un appareil

Dans cette section, vous allez créer une identité d’appareil pour votre hub IoT dans la première session CLI, puis simuler un appareil à l’aide de cette identité d’appareil. L’appareil simulé répond aux travaux que vous planifiez dans la deuxième session CLI.

Créer et démarrer un appareil simulé :

1. Dans la première session CLI, exécutez la commande az iot hub device-identity create, en remplaçant les espaces réservés suivants par leurs valeurs correspondantes. Cette commande crée l’identité de l’appareil pour votre appareil simulé.

   {DeviceName}. Nom de votre appareil simulé.

   {HubName}. Nom de votre IoT Hub.

   az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
   

2. Dans la première session CLI, exécutez la commande az iot device simulate, en remplaçant les espaces réservés suivants par leurs valeurs correspondantes. Cette commande simule l’appareil que vous avez créé à l’étape précédente. La commande configure également l’appareil simulé pour signaler son canal de connectivité en tant que propriété signalée sur le jumeau d’appareil correspondant de l’appareil lors de l’initialisation.

   {DeviceName}. Nom de votre appareil simulé.

   {HubName}. Nom de votre IoT Hub.

   az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                          --init-reported-properties '{"connectivity":{"type": "cellular"}}'
   

   Conseil

   Par défaut, la commande az iot device simulate envoie 100 messages appareil-à-cloud avec un intervalle de 3 secondes entre les messages. La simulation se termine une fois que tous les messages ont été envoyés. Si vous souhaitez que la simulation s’exécute plus longtemps, vous pouvez utiliser le paramètre --msg-count pour spécifier davantage de messages ou le paramètre --msg-interval pour spécifier un intervalle plus long entre les messages. Vous pouvez également réexécuter la commande pour redémarrer l’appareil simulé.

Mettre à jour le jumeau d’appareil

Une fois que vous avez créé une identité d’appareil, un jumeau d’appareil est implicitement créé dans IoT Hub. Dans cette section, vous utilisez la deuxième session CLI pour mettre à jour un ensemble d’étiquettes sur le jumeau d’appareil associé à l’identité d’appareil créée dans la section précédente. Vous pouvez utiliser des étiquettes de jumeau d’appareil pour organiser et gérer des appareils dans vos solutions IoT. Pour plus d’informations sur la gestion des appareils à l’aide des étiquettes, consultez Comment gérer des appareils à l’aide d’étiquettes de jumeau d’appareil dans Azure IoT Hub.

1. Dans la première session CLI, vérifiez que l’appareil simulé est en cours d’exécution. Si ce n’est pas le cas, redémarrez-le en réexécutant la commande az iot device simulate à partir de Créer et simuler un appareil.

2. Dans la deuxième session CLI, exécutez la commande az iot hub device-twin update en remplaçant les espaces réservés suivants par leurs valeurs correspondantes. Dans cet exemple, nous mettons à jour plusieurs étiquettes sur le jumeau d’appareil pour l’identité de l’appareil que nous avons créée dans la section précédente.

   {DeviceName}. Nom de votre appareil.

   {HubName}. Nom de votre IoT Hub.

   az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                                 --tags '{"location":{"region":"US","plant":"Redmond43"}}'
   

3. Dans la deuxième session CLI, confirmez que la réponse JSON affiche les résultats de l’opération de mise à jour. Dans l’exemple de réponse JSON suivant, nous avons utilisé SampleDevice pour l’espace réservé {DeviceName} dans la commande CLI az iot hub device-twin update.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

Interrogez votre hub IoT pour rechercher des jumeaux d’appareil

IoT Hub expose les jumeaux d’appareil pour votre hub IoT en tant que collection de documents appelée appareils. Dans cette section, vous allez utiliser la deuxième session CLI pour exécuter deux requêtes sur le jeu de jumeaux d’appareil pour votre hub IoT : la première requête sélectionne uniquement les jumeaux d’appareil des appareils situés dans l’usine Redmond43 et la deuxième affine la requête pour sélectionner uniquement les appareils qui sont également connectés via un réseau cellulaire. Les deux requêtes retournent uniquement les 100 premiers appareils du jeu de résultats. Pour plus d’informations sur les requêtes de jumeaux d’appareil, consultez Requêtes pour les jumeaux d’appareil et de module IoT Hub.

1. Dans la première session CLI, vérifiez que l’appareil simulé est en cours d’exécution. Si ce n’est pas le cas, redémarrez-le en réexécutant la commande az iot device simulate à partir de Créer et simuler un appareil.

2. Dans la deuxième session CLI, exécutez la commande az iot hub job query en remplaçant les espaces réservés suivants par leurs valeurs correspondantes. Dans cet exemple, nous filtrons la requête pour retourner uniquement les jumeaux d’appareil des appareils situés dans l’usine redmond43.

   {HubName}. Nom de votre IoT Hub.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                    --top 100
   

3. Dans la deuxième session CLI, vérifiez que la réponse JSON affiche les résultats de la requête.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

4. Dans la deuxième session CLI, exécutez la commande az iot hub job query en remplaçant les espaces réservés suivants par leurs valeurs correspondantes. Dans cet exemple, nous filtrons la requête pour retourner uniquement les jumeaux d’appareils situés dans l’usine Redmond43 qui sont également connectés via un réseau cellulaire.

   {HubName}. Nom de votre IoT Hub.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                     AND properties.reported.connectivity.type = 'cellular'" \
                    --top 100
   

5. Dans la deuxième session CLI, vérifiez que la réponse JSON affiche les résultats de la requête. Les résultats de cette requête doivent correspondre à ceux de la requête précédente de cette section.

Dans cet article, vous découvrirez comment :

• Ajout de métadonnées d’appareil en tant qu’étiquettes à partir d’une session Azure CLI
• Simulation d’un appareil qui a signalé les informations sur la connectivité des appareils dans le jumeau d’appareil
• Interrogation des informations sur le jumeau d’appareil en utilisant le langage de requête IoT Hub de type SQL dans une session Azure CLI

Étapes suivantes

Pour découvrir comment :

• Pour envoyer de la télémétrie à partir d’appareils, consultez Démarrage rapide : Envoyer des données de télémétrie à partir d’un appareil IoT Plug-and-Play vers Azure IoT Hub.

• Pour configurer des appareils à l’aide des propriétés souhaitées du jumeau d’appareil, consultez Tutoriel : Configurer vos appareils à partir d’un service back-end.

• Pour contrôler les appareils de manière interactive, comme l’activation d’un ventilateur à partir d’une application contrôlée par l’utilisateur, consultez Démarrage rapide : contrôler un appareil connecté à un IoT Hub.