Gestion automatique des appareils et des modules IoT

Prerequisites

• Un abonnement Azure actif. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

• Un hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans la section Créer un hub IoT de Créer et gérer des hubs Azure IoT.

Implémenter des jumeaux

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

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

Utiliser des balises pour cibler des jumeaux

Avant de créer une configuration, vous devez spécifier les appareils ou modules que vous souhaitez affecter. Azure IoT Hub identifie les appareils à l’aide de balises dans le jumeau d’appareil 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 manière logique pour votre solution. Par exemple, si vous gérez des appareils à différents emplacements, ajoutez les balises suivantes à un jumeau d’appareil :

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

Créer une configuration

Vous pouvez créer un maximum de 100 configurations automatiques sur des hubs IoT de niveau standard ; 10 sur les hubs IoT de niveau gratuit. Pour en savoir plus, consultez les quotas et les limitations IoT Hub.

1. Accédez à votre IoT Hub dans le Portail Azure.

2. Dans le menu du service, sous Gestion des appareils, sélectionnez Configurations + Déploiements.

3. Sélectionnez Ajouter et choisissez Configuration de jumeau d'appareil ou Configuration de jumeau de module dans la liste déroulante.

   

Il existe cinq étapes pour créer une configuration. Les sections suivantes parcourent chacune d’elles.

Nom et étiquette

1. Entrez un nom unique pour votre configuration. Le nom peut comporter jusqu’à 128 caractères et inclure des lettres minuscules et les caractères spéciaux suivants : -+%_*!'. Les espaces ne sont pas autorisés.
2. Ajoutez des étiquettes pour organiser et décrire votre configuration. Les étiquettes sont des paires clé-valeur, telles que HostPlatform, Linux ou Version, 3.0.1.
3. Sélectionnez Suivant pour continuer.

Paramètres de jumeau

Définissez le contenu dans les propriétés souhaitées du jumeau d’appareil ou du jumeau de module ciblé en fournissant deux entrées pour chaque paramètre. Tout d’abord, spécifiez le chemin du jumeau, qui pointe vers la section JSON dans les propriétés souhaitées du jumeau à mettre à jour. Ensuite, entrez le contenu JSON à insérer à cet emplacement.

Par exemple, vous pouvez définir le chemin du jumeau sur properties.desired.chiller-water, puis fournir le contenu JSON suivant :

{
  "temperature": 66,
  "pressure": 28
}

Vous pouvez également définir des paramètres individuels en spécifiant le chemin du jumeau complet et la valeur sans crochets. Par exemple, avec le chemin jumeau properties.desired.chiller-water.temperature, définissez le contenu sur 66. Créez ensuite un paramètre de jumeau pour la propriété de pression.

Si deux configurations ou plus ciblent le même chemin jumeau, le contenu de la configuration de priorité la plus élevée s'applique (la priorité est définie à l'étape 4).

Si vous souhaitez supprimer une propriété existante, spécifiez la valeur de la propriété sur null.

Vous pouvez ajouter d’autres paramètres en sélectionnant Ajouter un paramètre de jumeau d’appareil ou ajouter un paramètre de jumeau de module.

Appareils ou modules cibles

Utilisez la propriété tags de vos jumeaux pour cibler les appareils ou modules spécifiques qui doivent recevoir cette configuration. Vous pouvez également cibler des propriétés signalées pour le jumeau.

Les configurations d’appareil automatiques peuvent uniquement cibler des balises de jumeau d’appareil, et les configurations de Module automatiques peuvent uniquement cibler des balises de jumeau de Module.

Étant donné que plusieurs configurations peuvent cibler le même appareil ou module, chaque configuration a besoin d’un numéro de priorité. En cas de conflit, la configuration avec la priorité la plus élevée gagne.

1. Entrez un entier positif pour la priorité de configuration. La valeur numérique la plus élevée est considérée comme la priorité la plus élevée. Si deux configurations ont le même numéro de priorité, celle créée le plus récemment gagne.

2. Entrez une condition cible pour déterminer quels appareils ou modules sont ciblés avec cette configuration. La condition est basée sur des étiquettes jumelles ou des propriétés déclarées jumelles et doit respecter le format d'expression.

   • Pour la configuration automatique de l’appareil, vous pouvez spécifier uniquement l'étiquette ou la propriété rapportée que vous souhaitez cibler. Par exemple, tags.environment='test' ou properties.reported.chillerProperties.model='4000x'. Vous pouvez spécifier * pour cibler tous les appareils.

   • Pour la configuration automatique des modules, utilisez une requête pour spécifier des balises ou des propriétés signalées des modules inscrits auprès du hub IoT. Par exemple, from devices.modules where tags.environment='test' ou from devices.modules where properties.reported.chillerProperties.model='4000x'. Le caractère générique ne peut pas être utilisé pour cibler tous les modules.

Metrics

Les métriques fournissent des décomptes récapitulatives des différents états qu’un appareil ou un module peut renvoyer après l’application du contenu de configuration. Par exemple, vous pouvez créer une métrique pour les modifications des paramètres en attente, une métrique pour les erreurs et une métrique pour les modifications de paramètres réussies.

Chaque configuration peut avoir jusqu’à cinq métriques personnalisées.

1. Entrez un nom pour le nom de la métrique.

2. Entrez une requête pour les critères de métrique. La requête est basée sur les propriétés signalées du jumeau d’appareil. La métrique représente le nombre de lignes retournées par la requête.

   Par exemple:

   SELECT deviceId FROM devices 
     WHERE properties.reported.chillerWaterSettings.status='pending'
   

   Vous pouvez inclure une clause que la configuration a été appliquée, par exemple :

   /* Include the double brackets. */
   SELECT deviceId FROM devices 
     WHERE configurations.[[yourconfigname]].status='Applied'
   

   Si vous créez une métrique pour générer un rapport sur les modules configurés, sélectionnez moduleId à partir de devices.modules. Par exemple:

   SELECT deviceId, moduleId FROM devices.modules
     WHERE properties.reported.lastDesiredStatus.code = 200
   

Vérifier la configuration

Passez en revue vos informations de configuration, puis sélectionnez Envoyer.

Surveiller une configuration

Pour afficher les détails d’une configuration et surveiller les appareils qui l’exécutent, procédez comme suit :

1. Accédez à votre IoT Hub dans le Portail Azure.

2. Dans le menu du service, sous Gestion des appareils, sélectionnez Configurations + Déploiements.

3. Inspectez la liste de configuration. Pour chaque configuration, vous pouvez afficher les détails suivants :

   • ID : nom de la configuration.

   • Condition cible : requête utilisée pour définir des appareils ou des modules ciblés.

   • Priorité : numéro de priorité affecté à la configuration.

   • Heure de création : horodatage à partir duquel la configuration a été créée. Cet horodatage est utilisé pour rompre les liens lorsque deux configurations ont la même priorité.

   • Métriques système : métriques calculées par IoT Hub et qui ne peuvent pas être personnalisées par les développeurs. Ciblé spécifie le nombre de jumeaux d'appareil remplissant la condition cible. S'applique précise le nombre de jumeaux d'appareil modifiés par la configuration, ce qui peut comprendre des modifications partielles si une configuration distincte de priorité plus élevée a également effectué des changements.

   • Indicateurs de performance personnalisés : indicateurs de performance spécifiés par le développeur sous forme de requêtes portant sur les propriétés signalées du jumeau. Jusqu’à cinq métriques personnalisées peuvent être définies par configuration.

4. Sélectionnez la configuration à surveiller.

5. Inspectez les détails de la configuration. Vous pouvez utiliser des onglets pour afficher des détails spécifiques sur les appareils qui ont reçu la configuration.

   • Appareils cibles ou modules cibles : les appareils ou les modules qui correspondent à la condition cible.

   • Métriques : liste des métriques système et des métriques personnalisées. Vous pouvez afficher une liste d’appareils ou de modules qui sont comptés pour chaque métrique en sélectionnant la métrique dans la liste déroulante, puis en sélectionnant Afficher les appareils ou les modules d’affichage.

   • Étiquettes : paires clé-valeur utilisées pour décrire une configuration. Les étiquettes n’ont aucun impact sur les fonctionnalités.

   • Paramètres de jumeau d’appareil ou paramètres de jumeau de module : paramètres de jumeau définis par la configuration, le cas échéant.

Modifier une configuration

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

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

• Si un jumeau ne répond pas à l’ancienne condition cible, mais répond à la nouvelle condition cible et que cette configuration est la priorité la plus élevée pour ce jumeau, cette configuration est appliquée.

• Si un jumeau en cours d’exécution de cette configuration ne répond plus à la condition cible, les paramètres de la configuration sont supprimés et le jumeau est modifié par la configuration de priorité la plus élevée suivante.

• Si un jumeau en cours d’exécution de cette configuration ne répond plus à la condition cible et ne répond pas à la condition cible d’autres configurations, les paramètres de la configuration sont supprimés et aucune autre modification n’est apportée sur le jumeau.

Pour modifier une configuration, procédez comme suit :

1. Accédez à votre IoT Hub dans le Portail Azure.
2. Dans le menu du service, sous Gestion des appareils, sélectionnez Configurations + Déploiements.
3. Sélectionnez la configuration à modifier.
4. Vous pouvez apporter des mises à jour aux champs suivants : priorité, métriques, condition cible et étiquettes.
5. Cliquez sur Enregistrer.
6. Suivez les étapes décrites dans Surveiller une configuration pour surveiller le déploiement des modifications.

Supprimer une configuration

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

1. Accédez à votre IoT Hub dans le Portail Azure.
2. Dans le menu du service, sous Gestion des appareils, sélectionnez Configurations + Déploiements.
3. Utilisez la case à cocher pour sélectionner la configuration à supprimer.
4. Sélectionnez Supprimer.
5. Une invite vous demande de confirmer la suppression.

Prerequisites

• Un abonnement Azure actif. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

• Un hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans la section Créer un hub IoT de Créer et gérer des hubs Azure IoT.

• Azure CLI dans votre environnement. Au minimum, votre version d’Azure CLI doit être 2.0.70 ou ultérieure. Utilisez az –-version pour valider. Cette version prend en charge les commandes d’extension az et introduit le framework de commandes Knack.

• Extension IoT pour Azure CLI.

Implémenter des jumeaux

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

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

Utiliser des balises pour cibler des jumeaux

Avant de créer une configuration, vous devez spécifier les appareils ou modules que vous souhaitez affecter. Azure IoT Hub identifie les appareils et utilise des balises dans le jumeau d’appareil 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 toute façon qui est logique pour votre solution. Par exemple, si vous gérez des appareils à différents emplacements, ajoutez les balises suivantes à un jumeau d’appareil :

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

Définir le contenu et les métriques cibles

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 à l’aide d’Azure CLI, enregistrez le contenu cible et les métriques localement en tant que fichiers .txt. Vous utilisez les chemins d’accès au fichier dans une section ultérieure lorsque vous exécutez la commande pour appliquer la configuration à votre appareil.

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

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

Les configurations de module automatique se comportent de la même façon, 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étriques :

{
  "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étrique pour les modules sont également similaires aux requêtes pour les appareils, mais vous sélectionnez pour moduleId depuis 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 des hubs IoT de niveau standard ; 10 sur les hubs IoT de niveau gratuit. Pour en savoir plus, consultez les quotas et la régulation IoT Hub.

Vous configurez des appareils cibles en créant une configuration qui se compose du contenu et des métriques cibles. 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éée dans le hub IoT. Donnez à votre configuration un nom unique pouvant atteindre 128 caractères. Les lettres minuscules et les caractères spéciaux suivants sont autorisés : -+%_*!'. Les espaces ne sont pas autorisés.

• -- étiquettes : ajoutez des étiquettes pour suivre votre configuration. Les étiquettes sont des paires Nom, Valeur qui décrivent votre déploiement. Par exemple, HostPlatform, Linux ou Version, 3.0.1

• -- contenu : JSON inline ou chemin du contenu cible à définir en tant que propriétés de jumeau souhaitées.

• -- nom du hub : nom du hub IoT dans lequel la configuration est créée. Le hub doit se trouver dans l’abonnement actuel. Basculer vers l’abonnement souhaité avec la commande az account set -s [subscription name]

• -- target-condition : entrez une condition cible pour déterminer quels appareils ou modules sont ciblés avec 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'.

• -- priorité : entier positif. Si deux configurations ou plus sont ciblées sur le même appareil ou module, la configuration avec la valeur numérique la plus élevée pour Priority s’applique.

• -- métriques : chemin de fichier vers les requêtes de métriques. Les métriques fournissent des décomptes récapitulatives des différents états qu’un appareil ou un module peut renvoyer après l’application du contenu de configuration. Par exemple, vous pouvez créer une métrique pour les modifications des 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 qui existe dans le hub IoT.

• -- hub-name : nom du hub IoT dans lequel la configuration existe. Le hub doit se trouver 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é de métriques 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 jumeaux de module dans IoT Hub qui correspondent à la condition de ciblage.

• appliedCount : une métrique système spécifie le nombre d’appareils ou de modules auxquels le contenu cible est appliqué.

• Votre métrique personnalisée : toutes les métriques que vous avez définies sont des métriques utilisateur.

Vous pouvez afficher la liste des ID d’appareil, des ID de module ou des 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 afficher la liste des ID d’appareil ou des ID de module, par exemple appliedCount.

• -- hub-name : nom du hub IoT dans lequel le déploiement existe. Le hub doit se trouver dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].

• -- type de métrique : 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

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

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

• Si un jumeau ne répond pas à l’ancienne condition cible, mais répond à la nouvelle condition cible et que cette configuration est la priorité la plus élevée pour ce jumeau, cette configuration est appliquée.

• Si un jumeau en cours d’exécution de cette configuration ne répond plus à la condition cible, les paramètres de la configuration sont supprimés et le jumeau est modifié par la configuration de priorité la plus élevée suivante.

• Si un jumeau en cours d’exécution de cette configuration ne répond plus à la condition cible et ne répond pas à la condition cible d’autres configurations, les paramètres de la configuration sont supprimés et aucune autre modification n’est apporté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 qui existe dans le hub IoT.

• -- hub-name : nom du hub IoT dans lequel la configuration existe. Le hub doit se trouver dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].

• -- set - Mettre à jour une propriété dans la configuration. Vous pouvez mettre à jour les propriétés suivantes :

  • targetCondition : par exemple, targetCondition=tags.location.state='Oregon'

  • labels

  • priority

Supprimer une configuration

Lorsque vous supprimez une configuration, chaque jumeau d’appareil ou de module adopte sa prochaine configuration à priorité élevée. Si les jumeaux ne répondent pas à la condition cible d’une 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 qui existe dans le hub IoT.

• -- hub-name : nom du hub IoT dans lequel la configuration existe. Le hub doit se trouver dans l’abonnement actuel. Basculez vers l’abonnement souhaité avec la commande az account set -s [subscription name].