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

Avant de commencer, notez les prérequis suivants :

• Les appareils doivent être correctement inscrits à Device Update avant de pouvoir être attribués à un groupe.
• Les appareils doivent signaler un identifiant de modèle Plug-and-Play pris en charge. Pour une liste des identifiants de modèles pris en charge, voir Modèles de mise à jour de périphérique.
• Pour les scénarios IoT Edge, l’agent de mise à jour de l’appareil s’exécute comme un module et doit rapporter l’ID du modèle via l’identité appropriée.

Ajouter des étiquettes à vos appareils

Pour assigner un groupe de dispositifs Device Update, ajoutez le ADUGroup tag à 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 des jumeaux, consultez Comprendre et utiliser des jumeaux d’appareils 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 du nom de balise ADUGroup et du nom de groupe sont sensibles à 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 jumeaux 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 les jumeaux d’appareil ou de module à l’aide de tâches, selon que l’agent Device Update a été approvisionné avec une identité d’appareil ou de module. Pour plus d’informations, consultez Planifier et diffuser des travaux.

Ajouter des étiquettes en mettant à jour des jumeaux

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

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

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

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

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 comporter aucun appareil membre. 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é.

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

Troubleshooting

Si vous attribuez une balise à un appareil mais ne voyez pas de groupe, essayez les étapes de dépannage suivantes :

• Vérifiez que le tag est bien configuré.
• Vérifiez que l’appareil contient un identifiant de modèle Plug-and-Play valide ainsi qu’un tag valideADUGroup.
• Confirmez que les routes des messages IoT Hub sont correctement configurées. Pour plus d’informations, voir Acheminement des messages.
• Assurez-vous que l’IoT Hub est correctement associé à l’instance de mise à jour de l’appareil.
• Exécutez les diagnostics Device Update et la vérification de l’agent.
• Effectuez la synchronisation des appareils si nécessaire.

Pour plus d’informations, consultez Plug-and-Play dans Azure Device Update et Device Update for Azure IoT Hub agent check.

Contenu connexe

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