Gestion automatique des Modules et des appareils IoT avec Azure CLI

Article
03/19/2023

La gestion automatique des appareils dans Azure IoT Hub automatise une grande partie des tâches répétitives et complexes liées à la gestion de grandes flottes d’appareils. Avec la gestion automatique des appareils, vous pouvez cibler un ensemble d’appareils en fonction de leurs propriétés, définir la configuration souhaitée et laisser IoT Hub mettre à jour les appareils quand ils se trouvent dans l’étendue. Cette opération est effectuée à l’aide d’une configuration d’appareil automatiqueou d’une configuration de Module automatique, qui vous permet de récapituler les données d’achèvement et de conformité, de gérer la fusion et les conflits, et de déployer les configurations de façon progressive.

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 gestion automatique des appareils fonctionne en mettant à jour un ensemble de jumeaux d’appareil ou des jumeaux de Module avec les propriétés souhaitées et en communiquant un rapport récapitulatif basé sur les propriétés signalées du jumeau. Cette approche introduit un nouveau document de classe JSON appelé configuration qui comprend trois parties :

La condition cible définit l’étendue des jumeaux d’appareil ou jumeaux de Module à mettre à jour. La condition cible est spécifiée en tant que requête sur les balises de jumeaux d’appareil et/ou sur les propriétés signalées.
Le contenu cible définit les propriétés souhaitées à ajouter ou à mettre à jour dans les jumeaux d’appareil ou de Module ciblés. Le contenu inclut un chemin de la section des propriétés souhaitées à changer.
Les métriques définissent les nombres récapitulatifs des différents états de configuration tels que Réussite, En cours et Erreur. Les indicateurs de performance personnalisés sont spécifiés en tant que requêtes sur les propriétés signalées du jumeau. Les indicateurs de performance système sont des indicateurs de performance par défaut qui mesurent l’état de la mise à jour des jumeaux, comme le nombre de jumeaux qui sont ciblés et le nombre de jumeaux qui ont été correctement mis à jour.

Les configurations automatiques s’exécutent pour la première fois peu de temps après la création de la configuration, puis à cinq minutes d’intervalle. Les requêtes relatives aux indicateurs de performance s’exécutent à chaque exécution de la configuration automatique. Un maximum de 100 configurations automatiques est pris en charge sur les hubs IoT de niveau standard ; dix hubs IoT de niveau gratuit. Les limites de la limitation s’appliquent également. Pour plus d’informations, consultez Quotas et limitation.

Prérequis pour l’interface CLI

Un hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans Créer un hub IoT.
Azure CLI dans votre environnement. Vous devez utiliser Azure CLI version 2.0.70 ou ultérieure. Utilisez az –-version pour valider. Cette version prend en charge les commandes d’extension az et introduit l’infrastructure de la commande Knack.
Extension IoT pour Azure CLI.

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.

Implémenter des jumeaux

Les configurations d’appareil automatiques nécessitent l’utilisation de jumeaux d’appareil pour synchroniser l’état entre les appareils et le cloud. Pour en savoir plus, consultez Comprendre et utiliser les jumeaux d’appareil IoT Hub.

Les configurations de Module automatiques nécessitent l’utilisation de jumeaux de Module pour synchroniser l’état entre les Modules et le cloud. Pour en savoir plus, consultez Comprendre et utiliser les jumeaux de Module IoT Hub.

Utiliser des balises pour cibler des jumeaux

Avant de pouvoir créer une configuration, vous devez spécifier les appareils ou les Modules concernés. Azure IoT Hub identifie des appareils et utilise des balises dans le jumeau de Module et identifie les Modules à l’aide de balises dans le jumeau de Module. Chaque appareil ou module peut avoir plusieurs balises, et vous pouvez les définir de la manière qui correspond le mieux à votre solution. Par exemple, si vous gérez des appareils à différents emplacements, ajoutez les étiquettes suivantes à un jumeau d’appareil :

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

Définir le contenu cible et les métriques

Le contenu cible et les requêtes de métriques sont spécifiés sous forme de documents JSON qui décrivent les propriétés souhaitées du jumeau d’appareil ou de Module à définir et les propriétés indiquées à mesurer. Pour créer une configuration automatique avec Azure CLI, enregistrez le contenu cible et les métriques localement dans des fichiers .txt. Vous utiliserez les chemins des fichiers dans une section ultérieure, au moment d’exécuter la commande pour appliquer la configuration à votre appareil.

Voici un exemple de contenu cible de base pour une configuration d’appareil automatique :

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Les configurations automatiques de Module se comportent de façon similaire, mais vous ciblez moduleContent au lieu de deviceContent.

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Voici des exemples de requêtes de métrique :

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

Les requêtes de métriques pour les Modules sont également similaires aux requêtes pour les appareils, mais vous sélectionnez pour moduleId dans devices.modules. Par exemple :

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

Créer une configuration

Vous pouvez créer un maximum de 100 configurations automatiques sur les hubs IoT de niveau standard ; dix hubs IoT de niveau gratuit. Pour plus d’informations, consultez Quotas et limitation.

Vous configurez des appareils cibles en créant une configuration composée du contenu cible et des métriques. Utilisez la commande suivante pour créer une configuration :

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

--config-id : nom de la configuration à créer dans le hub IoT. Donnez à votre configuration un nom unique comportant 128 caractères au maximum. Les lettres minuscules et les caractères spéciaux suivants sont autorisés : -+%_*!'. Les espaces ne sont pas autorisés.
--labels : ajoutez des étiquettes pour faciliter le suivi de votre configuration. Les étiquettes sont des paires Nom, Valeur qui décrivent votre déploiement. Par exemple, HostPlatform, Linux ou Version, 3.0.1.
--content : JSON inline ou chemin du contenu cible à définir en tant que propriétés de jumeau souhaitées.
--hub-name : nom du hub IoT dans lequel la configuration sera créée. Le hub doit être dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].
--target-condition : entrez une condition cible pour déterminer quels sont les appareils ou Modules ciblés par cette configuration. Pour une configuration d’appareil automatique, la condition est basée sur les balises de jumeau d’appareil ou sur les propriétés souhaitées du jumeau d’appareil et doit correspondre au format de l’expression. Par exemple, tags.environment='test' ou properties.desired.devicemodel='4000x'. Pour la configuration de Module automatique, la condition est basée sur les balises ou les propriétés souhaitées d’un jumeau de Module. Par exemple, from devices.modules where tags.environment='test' ou from devices.modules where properties.reported.chillerProperties.model='4000x'.
--priority : entier positif. Si deux ou plusieurs configurations sont ciblées sur le même appareil ou Module, la configuration ayant la valeur numérique la plus élevée pour Priority s’applique.
--metrics : chemin des requêtes de métriques. Les métriques fournissent des nombres récapitulatifs des différents états qu’un appareil ou Module peut signaler après l’application d’un contenu de configuration. Par exemple, vous pouvez créer une métrique pour les modifications de paramètres en attente, une métrique pour les erreurs et une métrique pour les modifications de paramètres réussies.

Surveiller une configuration

Utilisez la commande suivante pour afficher le contenu d’une configuration :

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

--config-id : nom de la configuration existante dans le hub IoT.
--hub-name : nom du hub IoT dans lequel la configuration existe. Le hub doit être dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].

Inspectez la configuration dans la fenêtre de commande. La propriété metrics répertorie un nombre pour chaque métrique évaluée par chaque hub :

targetedCount : métrique système qui spécifie le nombre de jumeaux d’appareil ou de Module dans le hub IoT qui correspondent à la condition de ciblage.
appliedCount : métrique système qui spécifie le nombre d’appareils ou de Modules pour lesquels le contenu cible a été appliqué.
Votre métrique personnalisée : les métriques que vous avez définies sont des métriques utilisateur.

Vous pouvez afficher une liste d’ID d’appareil, d’ID de Module ou d’objets pour chacune des métriques à l’aide de la commande suivante :

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type]

--config-id : nom du déploiement qui existe dans le hub IoT.
--metric-id : nom de la métrique pour laquelle vous souhaitez voir la liste des ID d’appareil ou de Module, par exemple appliedCount.
--hub-name : nom du hub IoT dans lequel le déploiement existe. Le hub doit être dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].
--metric-type : le type de métrique peut être system ou user. Les métriques système sont targetedCount et appliedCount. Toutes les autres métriques sont des métriques utilisateur.

Modifier une configuration

Quand vous modifiez une configuration, les modifications sont répliquées immédiatement sur tous les appareils ciblés.

Si vous mettez à jour la condition cible, les mises à jour suivantes se produisent :

Si un jumeau ne remplissait pas l’ancienne condition cible, mais qu’il remplit la nouvelle condition cible et que cette configuration a la priorité la plus élevée pour ce jumeau, cette configuration est appliquée.
Si un jumeau exécutant cette configuration ne remplit plus la condition cible, les paramètres de la configuration sont supprimés et le jumeau est Modifié par la configuration ayant la priorité la plus élevée suivante.
Si un jumeau exécutant cette configuration ne remplit plus la condition cible et ne remplit pas la condition cible des autres configurations, les paramètres de la configuration sont supprimés et aucune autre Modification n’est effectuée sur le jumeau.

Utilisez la commande suivante pour mettre à jour une configuration :

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

--config-id : nom de la configuration existante dans le hub IoT.
--hub-name : nom du hub IoT dans lequel la configuration existe. Le hub doit être dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].
--set : met à jour une propriété dans la configuration. Vous pouvez mettre à jour les propriétés suivantes :
- targetCondition : par exemple, targetCondition=tags.location.state='Oregon'
- étiquettes
- priority

Supprimer une configuration

Quand vous supprimez une configuration, tous les jumeaux d’appareil ou de Module prennent leur configuration suivante dans l’ordre de priorité. Si des jumeaux ne remplissent la condition cible d’aucune autre configuration, aucun autre paramètre n’est appliqué.

Utilisez la commande suivante pour supprimer une configuration :

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name]

--config-id : nom de la configuration existante dans le hub IoT.
--hub-name : nom du hub IoT dans lequel la configuration existe. Le hub doit être dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].

Étapes suivantes

Dans cet article, vous avez découvert comment configurer et superviser des appareils IoT à grande échelle.

Pour savoir comment gérer les identités d’appareil IoT Hub en bloc, consultez Importer et exporter en bloc des identités d’appareils IoT Hub.

Partager via