Gérer des groupes d’appareils pour Azure Device Update pour IoT Hub

Azure Device Update pour IoT Hub permet de déployer des mises à jour sur des groupes d’appareils IoT définis par l’utilisateur. Chaque appareil géré par Device Update est membre d’un groupe d’appareils, mais la définition de groupes d’appareils est facultative. Vous pouvez également effectuer le déploiement sur le groupe d’appareils par défaut fourni par Device Update.

Si vous créez des valeurs d’étiquettes Device Update définies par l’utilisateur et que vous les attribuez à des appareils, Device Update crée automatiquement des groupes en fonction des étiquettes affectées et des propriétés de compatibilité des appareils. Pour chaque groupe d’appareils, Device Update peut créer plusieurs sous-groupes avec des classes d’appareil différentes. Device Update place les appareils qui n’ont aucune étiquette dans le groupe d’appareils default.

Cet article décrit comment utiliser le Portail Azure ou Azure CLI pour créer et gérer des étiquettes et des groupes d’appareils Device Update définis par l’utilisateur. Pour déployer des mises à jour sur des groupes d’appareils définis par l’utilisateur ou le groupe d’appareils par défaut, consultez Déployer une mise à jour d’appareil.

Prérequis

Azure portal

• Instance Standard (S1) ou ultérieure d’Azure IoT Hub avec Device Update pour IoT Hub activé.
• Un dispositif IoT ou un simulateur approvisionné pour la mise à jour des appareils au sein du hub IoT.
• Agent Device Update installé et démarré sur l’appareil en tant qu’identité au niveau du module ou de l’appareil.
• Une mise à jour importée pour l’appareil configuré.

Azure CLI

• Instance Standard (S1) ou ultérieure d’Azure IoT Hub avec Device Update pour IoT Hub activé.

• Un dispositif IoT ou un simulateur approvisionné pour la mise à jour des appareils au sein du hub IoT.

• Agent Device Update installé et démarré sur l’appareil en tant qu’identité au niveau du module ou de l’appareil.

• Une mise à jour importée pour l’appareil configuré.

• Environnement Bash dans Azure Cloud Shell pour exécuter les commandes Azure CLI. Sélectionnez Lancer Cloud Shell pour ouvrir Cloud Shell, ou sélectionnez l’icône Cloud Shell dans la barre d’outils supérieure du portail Azure.

  

  Remarque

  Si vous préférez, vous pouvez exécuter les commandes Azure CLI localement :

  1. Installez l’interface de ligne de commande Azure. Exécutez version az pour afficher la version d’Azure CLI installée et les bibliothèques dépendantes, puis exécutez az upgrade pour installer la dernière version.
  2. Connectez-vous à Azure en exécutant az login.
  3. Installez l’extension azure-iot lorsque vous y êtes invité lors de la première utilisation. Pour vous assurer que vous utilisez la dernière version de l’extension, exécutez az extension update --name azure-iot.

Ajouter des étiquettes à vos appareils

Pour attribuer un groupe d’appareils Device Update, vous ajoutez l’étiquette ADUGroup à un ensemble cible d’appareils connectés à Device Update dans IoT Hub. Ajoutez l’étiquette au jumeau d’appareil si votre agent Device Update est approvisionné avec une identité d’appareil ou au jumeau de module correspondant si l’agent Device Update est approvisionné avec une identité de module.

L’étiquette Device Update ADUGroup utilise un format clé-valeur, comme illustré dans l’exemple de jumeau d’appareil ou de module suivant :

"etag": "",
"deviceId": "",
"deviceEtag": "",
"version": <version>,
"tags": {
   "ADUGroup": "<CustomTagValue>"
}

Pour plus d’informations et des exemples de syntaxe JSON de jumeau, consultez Comprendre et utiliser des jumeaux d’appareil ou Comprendre et utiliser des jumeaux de module.

L’étiquette ADUGroup présente les propriétés et limitations suivantes :

• Un appareil ne peut avoir qu’une seule étiquette ADUGroup et ne peut appartenir qu’à un seul groupe Device Update à la fois. L’ajout d’une autre étiquette nommée ADUGroup remplace la valeur ADUGroup existante.
• Vous pouvez utiliser n’importe quelle valeur d’étiquette, à l’exception des valeurs réservées Uncategorized et $default.
• La valeur de l’étiquette ne peut pas dépasser 200 caractères.
• La valeur de l’étiquette peut contenir des caractères alphanumériques et les caractères spéciaux suivants : . - _ ~.
• Les valeurs de nom de groupe et de nom d’étiquette ADUGroup respectent la casse.

Les sections suivantes décrivent plusieurs façons d’ajouter et de mettre à jour l’étiquette.

Ajouter des étiquettes avec des SDK

Vous pouvez mettre à jour le jumeau d’appareil ou de module avec l’étiquette appropriée en utilisant RegistryManager après avoir inscrit l’appareil auprès de Device Update. Pour plus d’informations, consultez les articles suivants :

• Prise en main des représentations d’appareils avec .NET
• Comprendre le format des étiquettes et des propriétés

Ajouter des étiquettes à l’aide de travaux

Vous pouvez planifier des travaux pour ajouter ou mettre à jour des étiquettes Device Update sur plusieurs appareils. Pour obtenir des exemples d’opérations de travail, consultez Planifier des travaux sur plusieurs appareils. Vous pouvez mettre à jour des jumeaux d’appareil ou des jumeaux de module à l’aide de travaux, selon que l’agent Device Update est approvisionné avec une identité d’appareil ou de module. Pour plus d’informations, consultez Planifier et diffuser des travaux.

Remarque

Cette opération est comptabilisée dans votre quota de messages IoT Hub. Si vous modifiez 50 000 étiquettes ou plus de jumeau d’appareil ou de module à la fois, vous risquez de dépasser votre quota quotidien de messages IoT Hub et de devoir acheter des unités IoT Hub supplémentaires. Pour plus d’informations, consultez Quotas et limites.

Ajouter des étiquettes en mettant à jour des jumeaux

Vous pouvez également ajouter ou mettre à jour l’étiquette ADUGroup directement dans le jumeau d’appareil ou de module.

Azure portal

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

2. Dans le volet de navigation de gauche, sous Gestion des appareils, sélectionnez Appareils. Si vous disposez d’un appareil IoT Edge, sélectionnez IoT Edge à la place.

3. Dans la page Appareils, sélectionnez votre appareil.

4. Dans la page de l’appareil, sélectionnez Jumeau d’appareil dans le menu supérieur ou sélectionnez l’identité de module sous Identités de module, puis sélectionnez le jumeau de module.

5. Dans le jumeau, ajoutez l’étiquette ADUGroup avec une valeur définie par l’utilisateur, comme suit. Pour mettre à jour une valeur d’étiquette ADUGroup existante, remplacez-la par une autre valeur définie par l’utilisateur.

       "tags": {
               "ADUGroup": "<CustomTagValue>"
               }
   

6. Cliquez sur Enregistrer.

Azure CLI

Utilisez az iot hub device-twin update ou az iot hub module-twin update pour ajouter l’étiquette ADUGroup au jumeau d’appareil ou de module avec une valeur appropriée. Pour les deux commandes update, l’argument --tags accepte le JSON inline ou un chemin d’accès à un fichier JSON.

Par exemple :

az iot hub module-twin update \
    --hub-name <IoT hub name> \
    --device-id <device name> \
    --module-id <module name> \
    --tags '{"ADUGroup": "<custom_tag_value"}'

Afficher les groupes d’appareils

Azure portal

1. Dans le Portail Azure, naviguez jusqu’au hub IoT connecté à votre instance Device Update.

2. Dans le volet de navigation de gauche, sous Gestion des appareils, sélectionnez l’option Mises à jour.

3. Sélectionnez l’onglet Groupes et déploiements.

   

Une fois que vous avez créé un groupe, le graphique de conformité et la liste des groupes sont mis à jour. Le graphique de conformité de Device Update montre le nombre d’appareils dans différents états de conformité : À la mise à jour la plus récente, Nouvelles mises à jour disponibles et Mises à jour en cours. Pour plus d’informations, consultez Conformité de Device Update.

Les groupes Device Update existants et toutes les mises à jour disponibles pour les appareils de ces groupes s’affichent dans la liste des groupes. Les appareils qui ne répondent pas aux exigences de classe d’appareil du groupe s’affichent dans un groupe non valide correspondant. Vous pouvez déployer la meilleure mise à jour disponible pour un groupe à partir de cette vue en sélectionnant Déployer en regard du groupe.

Azure CLI

Utilisez az iot du device group list pour afficher tous les groupes d’appareils dans une instance Device Update.

az iot du device group list \
    --account <Device Update account name> \
    --instance <Device Update instance name>

Vous pouvez utiliser l’argument --order-by pour organiser la liste retournée en fonction d’aspects tels que l’ID de groupe, le nombre d’appareils ou le nombre de sous-groupes avec de nouvelles mises à jour disponibles.

Afficher les détails de l’appareil pour un groupe

Azure portal

1. Sous l’onglet Groupes et déploiements, sélectionnez le nom du groupe.

   La page Détails du groupe affiche le graphique de conformité des mises à jour avec le nombre d’appareils membres du groupe dans différents états de conformité, ainsi que la liste des appareils membres du groupe avec leurs propriétés de mise à jour d’appareil.

   

2. Sélectionnez un appareil individuel dans un groupe pour accéder à sa page de détails d’appareil dans IoT Hub.

   

   

Azure CLI

Utilisez az iot du device group show pour afficher les détails d’un groupe d’appareils spécifique.

• L’indicateur facultatif --best-updates renvoie une liste des meilleures mises à jour disponibles pour le groupe d’appareils, y compris le nombre d’appareils qui ont besoin de chaque mise à jour.

• L’indicateur facultatif --update-compliance retourne des informations de conformité pour le groupe d’appareils, notamment le nombre d’appareils qui disposent de la dernière mise à jour, qui ont besoin de nouvelles mises à jour ou sur lesquels des mises à jour sont en cours.

az iot du device group show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <value of the ADUGroup tag for this group>
    --best-updates
    --update-compliance

Supprimer un appareil d’un groupe d’appareils

Pour supprimer un appareil d’un groupe d’appareils, remplacez la valeur de l’étiquette ADUGroup par null dans le jumeau, puis sélectionnez Enregistrer.

    "tags": {
            "ADUGroup": "null"
            }

Cette action supprime l’étiquette de groupe du jumeau d’appareil et supprime l’appareil du groupe d’appareils.

Supprimer un groupe d’appareils

Device Update crée automatiquement des groupes d’appareils, mais au lieu de nettoyer automatiquement les groupes d’appareils, classes d’appareils et déploiements, il les conserve pour fournir des enregistrements historiques ou répondre à d’autres besoins des utilisateurs. Vous pouvez supprimer des groupes d’appareils via le Portail Azure en sélectionnant et en supprimant individuellement les groupes, ou en appelant la commande Azure CLI az iot du device group delete sur le groupe.

Pour être supprimé, un groupe doit répondre aux exigences suivantes :

• Ne doit pas être un groupe default.
• Ne doit pas avoir d’appareils membres. Autrement dit, aucun appareil approvisionné dans l’instance Device Update ne peut avoir une étiquette ADUGroup avec une valeur correspondant au nom du groupe.
• Ne doit pas être associé à un déploiement actif ou annulé.

Remarque

Si vous ne parvenez pas à supprimer un groupe qui répond aux exigences précédentes, vérifiez si des appareils non sains sont étiquetés comme faisant partie du groupe. Les appareils non sains ne peuvent pas recevoir de déploiement. Ils n’apparaissent donc pas directement dans la liste des appareils membres d’un groupe.

Pour vérifier si vous avez des appareils non sains :

1. Accédez à votre IoT Hub dans le portail Azure.
2. Sélectionnez Mises à jour dans le volet de navigation de gauche, puis sélectionnez l’onglet Diagnostics.
3. Développez la section Rechercher les appareils manquants.

Si vous avez des appareils non sains étiquetés comme faisant partie du groupe, vous devez modifier la valeur de l’étiquette ou supprimer l’appareil avant de pouvoir supprimer le groupe.

Si un appareil est à nouveau attribué à un nom de groupe supprimé, Device Update recrée automatiquement le groupe, mais sans aucun historique d’appareil ou de déploiement associé.

Contenu connexe

• Groupes d’appareils
• Conformité de Device Update
• Déployer une mise à jour