Planifier et diffuser des travaux (Azure CLI)

Article
03/16/2023

Utilisez Azure IoT Hub pour planifier et suivre des travaux qui mettent à jour des millions d’appareils. Utilisez les travaux pour :

Mettre à jour les propriétés souhaitées
Mettre à jour les balises
Appeler des méthodes directes

Sur le plan conceptuel, un travail encapsule l’une de ces actions et suit la progression de l’exécution par rapport à un ensemble d’appareils. L’ensemble d’appareils avec lesquels un travail interagit est défini par une requête de jumeau d’appareil. Par exemple, à l’aide d’un travail, une application principale peut appeler une méthode de redémarrage sur 10 000 appareils, spécifiée par une requête de représentation d’appareil et planifiée dans l’avenir. Cette application peut ensuite suivre la progression à mesure que chacun de ces appareils reçoit et exécute la méthode de redémarrage.

Pour en savoir plus sur chacune de ces fonctionnalités, consultez les articles suivants :

Jumeau d’appareil et propriétés : Prise en main des représentations d’appareils (Node) et Comprendre et utiliser les jumeaux d’appareil IoT Hub
Méthodes directes : Guide du développeur IoT Hub - méthodes directes

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.

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

Session qui crée un appareil simulé. L’appareil simulé est configuré pour retourner un code d’état et une charge utile JSON lorsqu’une méthode directe est appelée.
Session qui crée deux travaux planifiés. Le premier travail appelle une méthode directe et le deuxième travail met à jour une propriété de jumeau d’appareil souhaitée sur l’appareil simulé créé dans l’autre session.

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 hub IoT dans votre abonnement Azure. Créez-en un avec l’interface CLI ou le portail Azure.
Assurez-vous que le port 8883 est ouvert dans votre pare-feu. L’exemple d’appareil décrit dans cet article utilise le protocole MQTT, qui communique via 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).

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.

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.
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 planifie les travaux de votre appareil simulé avec votre hub IoT.

Notes

Azure CLI nécessite que vous soyez connecté à votre compte Azure. Si vous utilisez le Cloud Shell, vous êtes automatiquement connecté à votre compte Azure. Si vous utilisez un client CLI local, vous devez vous connecter à chaque session CLI. Toutes les communications entre votre session d’interpréteur de commandes 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 à Azure CLI, consultez Se connecter avec Azure CLI.

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.
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é :

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} 
```
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. L’appareil simulé est configuré pour retourner un code d’état et une charge utile chaque fois qu’une méthode directe est appelée.

{DeviceName}. Nom de votre appareil simulé.

{HubName}. Nom de votre IoT Hub.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --method-response-code 201 \
                       --method-response-payload '{"result":"Direct method successful"}'
```
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é.

Planifier un travail pour appeler une méthode directe

Dans cette section, vous allez planifier un travail dans la deuxième session CLI pour appeler une méthode directe sur l’appareil simulé en cours d’exécution dans la première session CLI.

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.
Dans la deuxième session CLI, exécutez la commande az iot hub job create, en remplaçant les espaces réservés suivants par leurs valeurs correspondantes. Dans cet exemple, il n’existe aucune méthode préexistante pour l’appareil. La commande planifie un travail qui appelle un exemple de nom de méthode sur l’appareil simulé, en fournissant une valeur Null pour la charge utile de la méthode. La méthode fournit un code d’état et une charge utile dans sa réponse.

{HubName}. Nom de votre IoT Hub.

{JobName}. Nom de votre travail planifié. Les noms de travaux étant uniques, choisissez un nom de travail différent chaque fois que vous exécutez cette commande.

{MethodName}. Nom de votre méthode directe. L’appareil simulé n’a pas de méthode préexistante. Vous pouvez donc choisir le nom souhaité pour cette commande.

{DeviceName}. Nom de votre appareil simulé.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleDeviceMethod \
                      --method-name {MethodName} --method-payload 'null' \
                      --query-condition "deviceId = '{DeviceName}'"
```
Conseil

Lors de la planification d’une commande az iot hub job create qui appelle une méthode directe, vous devez spécifier des valeurs pour les deux paramètres facultatifs, --method-name et --method-payload. Pour les méthodes directes qui n’acceptent pas de charge utile, spécifiez null pour le paramètre --method-payload.
Dans la première session CLI, vérifiez que la sortie affiche l’appel de méthode. Dans la capture d’écran suivante, nous avons utilisé SampleDevice et SampleMethod pour les espaces réservés {DeviceName} et {MethodName}, respectivement, dans la commande CLI az iot hub job create de l’étape précédente.

Planifier un travail pour mettre à jour les propriétés d’un jumeau d’appareil

Dans cette section, vous allez planifier un travail dans la deuxième session CLI pour mettre à jour une propriété de jumeau d’appareil souhaitée sur l’appareil simulé s’exécutant dans la première session CLI.

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.
Dans la deuxième session CLI, exécutez la commande az iot hub job create, en remplaçant les espaces réservés suivants par leurs valeurs correspondantes. Dans cet exemple, nous prévoyons un travail pour définir la valeur de la propriété BuildingNo de jumeau souhaitée sur 45 pour notre appareil simulé.

{HubName}. Nom de votre IoT Hub.

{JobName}. Nom de votre travail planifié. Les noms de travaux étant uniques, choisissez un nom de travail différent chaque fois que vous exécutez cette commande.

{DeviceName}. Nom de votre appareil simulé.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleUpdateTwin \
                      --twin-patch '{"properties":{"desired": {"BuildingNo": 45}}}' \
                      --query-condition "deviceId = '{DeviceName}'"
```
Dans la première session CLI, vérifiez que la sortie affiche la mise à jour réussie pour la propriété de jumeau d’appareil signalée, indiquant que la propriété de jumeau d’appareil souhaitée a également été mise à jour.

Étapes suivantes

Dans cet article, vous avez utilisé Azure CLI pour simuler un appareil et planifier des travaux pour exécuter une méthode directe et mettre à jour les propriétés du jumeau d’appareil pour cet appareil simulé.

Pour continuer à explorer le hub IoT et les modèles de gestion des appareils, mettez à jour une image dans le Tutoriel sur le service Device Update pour IoT Hub : Utilisation de l’image de référence Raspberry Pi 3 B+.

Partager via