Comprendre le registre des identités dans votre IoT Hub
Chaque hub IoT a un registre des identités contenant des informations sur les appareils et modules autorisés à se connecter au hub IoT. Pour qu’un appareil ou module puisse se connecter à un hub IoT, une entrée correspondant à cet appareil ou module doit figurer dans le registre des identités du hub IoT. Un appareil ou module doit également s’authentifier auprès du hub IoT à l’aide des informations d’identification stockées dans le registre des identités.
L’ID d’appareil ou de module stocké dans le registre des identités respecte la casse.
À un niveau supérieur, le registre des identités est une collection compatible REST de ressources d’identité d’appareil ou de module. Lorsque vous ajoutez une entrée au registre des identités, IoT Hub crée un jeu de ressources par appareil, comme une file d’attente contenant des messages cloud vers appareil en transit.
Utilisez le registre des identités lorsque vous avez besoin d’effectuer les actions suivantes :
- Provisionner des appareils ou modules qui se connectent à votre hub IoT.
- Contrôler l’accès par appareil/module aux points de terminaison côté appareil ou module de votre hub.
Opérations du registre d’identité
Le registre des identités IoT Hub expose les opérations suivantes :
- Création d’une identité d’appareil ou de module
- Mise à jour de l’identité d’appareil ou de module
- Récupération d’une identité d’appareil ou de module par ID
- Suppression de l’identité d’appareil ou de module
- Création de listes contenant jusqu’à 1 000 identités
- Exportation des identités d’appareil vers le stockage Blob Azure
- Importation des identités d’appareil depuis le stockage Blob Azure
Toutes ces opérations peuvent utiliser un accès concurrentiel optimiste, comme spécifié dans la RFC7232.
Important
La seule façon de récupérer toutes les identités dans un registre d’identités IoT Hub consiste à utiliser la fonctionnalité Exporter.
Un registre des identités IoT Hub :
- Ne contient pas de métadonnées de l’application.
Important
Utilisez le registre des identités uniquement pour les opérations de gestion et d’approvisionnement. Les opérations à haut débit ne doivent pas dépendre de l’exécution d’opérations dans le registre des identités au moment de leur exécution. Par exemple, la vérification de l’état de la connexion d’un appareil avant l’envoi d’une commande n’est pas un modèle pris en charge. Veillez à vérifier les taux de limitation du registre d’identités.
Notes
L’obtention d’une identité d’appareil ou de module peut prendre quelques secondes après la création. Réessayez l’opération get des identités d’appareil ou de module en cas de défaillance.
Désactivation d’appareils
Vous pouvez désactiver les appareils en mettant à jour la propriété status d’une identité dans le registre des identités. Généralement, cette propriété est utilisée dans deux scénarios :
Au cours d’un processus d’orchestration d’approvisionnement. Pour plus d’informations, consultez Provisionnement des appareils.
Si vous pensez qu’un appareil est compromis ou non autorisé pour une raison quelconque.
Important
IoT Hub ne vérifie pas les listes de révocation de certificats lors de l’authentification des appareils avec une authentification basée sur un certificat. Si vous avez un appareil dont vous avez besoin d’empêcher la connexion à IoT Hub en raison d’un certificat potentiellement compromis, vous devez désactiver l’appareil dans le registre des identités.
Cette fonctionnalité n’est pas disponible pour les modules.
Pour plus d’informations, consultez Désactiver ou supprimer un appareil dans un hub IoT.
Importer et exporter les identités des appareils
Utilisez des opérations asynchrones sur le point de terminaison du fournisseur de ressources IoT Hub pour exporter des identités d’appareils en bloc à partir du registre des identités du hub IoT. Les exportations sont des tâches à long terme qui utilisent un conteneur d’objets blob fourni par le client pour enregistrer les données relatives à l’identité des appareils lues dans le registre des identités.
Utilisez des opérations asynchrones sur le point de terminaison du fournisseur de ressources IoT Hub pour importer des identités d’appareils en bloc dans le registre des identités du hub IoT. Les importations sont des tâches à long terme qui utilisent des données dans un conteneur d’objets blob, fourni par le client, pour écrire les données relatives à l’identité des appareils dans le registre des identités.
Pour plus d’informations sur l’importation et l’exportation d’API, consultez API REST du fournisseur de ressources IoT Hub. Pour en savoir plus sur l’exécution des travaux d’importation et d’exportation, consultez Gestion en bloc des identités d’appareils IoT Hub.
Les identités des appareils peuvent également être exportées et importées d'un hub IoT en utilisant l'API de service via l'API REST ou l'un des SDK de service du hub IoT.
Approvisionnement des appareils
Les données d’appareil qu’une solution IoT donnée stocke dépendent des exigences spécifiques de cette solution. Mais une solution doit au minimum stocker les clés d’authentification et les identités des appareils. Azure IoT Hub inclut un registre d’identité qui peut stocker des valeurs pour chaque appareil, comme les ID, les clés d’authentification et les codes d’état. Une solution peut utiliser d’autres services Azure, comme le stockage Table, le stockage Blob ou Azure Cosmos DB pour stocker d’autres données d’appareil.
Approvisionnement des appareils est le processus d'ajout des données d'appareil initial aux magasins dans votre solution. Pour permettre à un nouvel appareil de se connecter à votre hub, vous devez ajouter un ID et des clés d’appareil au registre des identités d’IoT Hub. Dans le cadre du processus d’approvisionnement, vous devrez peut-être initialiser les données spécifiques à l’appareil dans d’autres magasins de la solution. Vous pouvez également utiliser le service de d’approvisionnement des appareils IoT Hub pour activer l’approvisionnement sans contact et juste-à-temps vers un ou plusieurs hubs IoT sans qu’une intervention humaine soit nécessaire. Pour plus d’informations, consultez la documentation relative au service d’approvisionnement.
Notifications de cycle de vie des appareils et des modules
IoT Hub peut avertir votre solution IoT quand une identité d’appareil est créée ou supprimée, en envoyant des notifications de cycle de vie. Pour ce faire, votre solution IoT doit créer un itinéraire et définir la source de données DeviceLifecycleEvents. Par défaut, aucune notification du cycle de vie n’est envoyée. Autrement dit, aucun itinéraire n’existe préalablement. En créant un itinéraire avec une source de données égale à DeviceLifecycleEvents, les événements du cycle de vie sont envoyés pour les identités d’appareil et les identités de module. Le contenu du message varie selon que les événements sont générés pour les identités de module ou les identités d’appareil. Pour en savoir plus sur les propriétés et le corps retournés dans le message de notification, consultez Schémas d’événements autres que les événements de télémétrie.
Les notifications pour la création d’une identité de module diffèrent selon qu’il s’agit d’un module IoT Edge ou d’un autre module. Pour les modules IoT Edge, la notification de création est envoyée uniquement si l’appareil IoT Edge correspondant est en cours d’exécution. Pour tous les autres modules, les notifications de cycle de vie sont envoyées chaque fois que l’identité de module est mise à jour côté IoT Hub.
Propriétés d’identité des appareils
Les identités des appareils sont représentées sous forme de documents JSON avec les propriétés suivantes :
| Propriété | Options | Description |
|---|---|---|
| deviceId | obligatoire, en lecture seule sur les mises à jour | Une chaîne qui respecte la casse (jusqu’à 128 caractères) de caractères alphanumériques 7 bits ASCII plus certains caractères spéciaux :- . % _ * ? ! ( ) , : = @ $ '. Les caractères spéciaux + # ne sont pas pris en charge. |
| generationId | obligatoire, en lecture seule | Une chaîne qui respecte la casse, générée par IoT Hub, d’une longueur maximale de 128 caractères. Cette valeur permet de distinguer les appareils dotés du même deviceIdlorsqu’ils ont été supprimés et recréés. |
| etag | obligatoire, en lecture seule | Une chaîne représentant un ETag faible pour l’identité de l’appareil, conformément à la RFC7232. |
| Authentification | facultatif | Un objet composite contenant des informations d’authentification et des éléments de sécurité. Pour plus d’informations, consultez Mécanisme d’authentification dans la documentation sur l’API REST. |
| capabilities | facultatif | Ensemble de fonctionnalités de l’appareil. Par exemple, si l’appareil est un appareil de périphérie ou pas. Pour plus d’informations, consultez Fonctionnalités de l’appareil dans la documentation sur l’API REST. |
| deviceScope | facultatif | Portée de l’appareil. Pour les appareils de périphérie, la portée est générée automatiquement et immuable. Déconseillé dans les appareils de non-périphérie. Toutefois, sur les appareils enfants (leaf), attribuez à cette propriété la même valeur que la propriété parentScopes (deviceScope du périphérique parent) pour la compatibilité descendante avec les versions précédentes de l’API. Pour plus d’informations, consultez IoT Edge en tant que passerelle : relations parent/enfant. |
| parentScopes | facultatif | Portée du parent direct d’un appareil enfant (valeur de la propriété deviceScope de l’appareil parent). Pour les périphériques de périphérie, la valeur est vide si l’appareil n’a pas de parent. Pour les périphériques de non-périphérie, la propriété est absente si l’appareil n’a pas de parent. Pour plus d’informations, consultez IoT Edge en tant que passerelle : relations parent/enfant. |
| status | obligatoire | Un indicateur d’accès. Peut être Activé ou Désactivé. Si la propriété est définie sur Activé, l’appareil est autorisé à se connecter. Si la propriété est définie sur Désactivé, cet appareil ne peut pas accéder à un point de terminaison de l’appareil. |
| statusReason | facultatif | Une chaîne de 128 caractères qui stocke le motif de l’état de l’identité de l’appareil. Tous les caractères UTF-8 sont autorisés. |
| statusUpdateTime | en lecture seule | Un indicateur temporel, indiquant la date et l’heure de la dernière mise à jour de l’état. |
| connectionState | en lecture seule | Un champ indiquant l’état de la connexion : Connecté ou Déconnecté. Ce champ représente la vue IoT Hub de l’état de connexion de l’appareil. Important : Ce champ doit être utilisé uniquement à des fins de développement/débogage. L’état de la connexion est mis à jour uniquement pour les appareils utilisant les protocoles AMQP ou MQTT. Cet état est basé sur les pings au niveau du protocole (tests ping MQTT ou AMQP) et peut avoir un délai maximum de 5 minutes seulement. C’est pourquoi de faux positifs peuvent survenir. Par exemple, un appareil peut être signalé comme étant connecté, alors qu’il est déconnecté. |
| connectionStateUpdatedTime | en lecture seule | Un indicateur temporel, indiquant la date et la dernière heure de mise à jour de l’état de la connexion. |
| lastActivityTime | en lecture seule | Un indicateur temporel, indiquant la date et la dernière heure de connexion de l’appareil, de réception d’un message ou d’envoi d’un message. Cette propriété est finalement cohérente, mais peut être retardée pendant 5 à 10 minutes. Pour cette raison, elle ne doit pas être utilisée dans les scénarios de production. |
Notes
L’état de la connexion peut uniquement représenter la vue IoT Hub de l’état de la connexion. Les mises à jour à cet état peuvent être différées en fonction des conditions et des configurations du réseau.
Notes
Les SDK d’appareil ne prennent pas en charge l’utilisation des caractères + et # dans le deviceId.
Propriétés d’identité des modules
Les identités des modules sont représentées sous forme de documents JSON avec les propriétés suivantes :
| Propriété | Options | Description |
|---|---|---|
| deviceId | obligatoire, en lecture seule sur les mises à jour | Une chaîne qui respecte la casse (jusqu’à 128 caractères) de caractères alphanumériques 7 bits ASCII plus certains caractères spéciaux :- . + % _ # * ? ! ( ) , : = @ $ '. |
| moduleId | obligatoire, en lecture seule sur les mises à jour | Une chaîne qui respecte la casse (jusqu’à 128 caractères) de caractères alphanumériques 7 bits ASCII plus certains caractères spéciaux :- . + % _ # * ? ! ( ) , : = @ $ '. |
| generationId | obligatoire, en lecture seule | Une chaîne qui respecte la casse, générée par IoT Hub, d’une longueur maximale de 128 caractères. Cette valeur permet de distinguer les appareils dotés du même deviceIdlorsqu’ils ont été supprimés et recréés. |
| etag | obligatoire, en lecture seule | Une chaîne représentant un ETag faible pour l’identité de l’appareil, conformément à la RFC7232. |
| Authentification | facultatif | Un objet composite contenant des informations d’authentification et des éléments de sécurité. Pour plus d’informations, consultez Mécanisme d’authentification dans la documentation sur l’API REST. |
| managedBy | facultatif | Identifie qui gère ce module. Par exemple, cette valeur est « IoT Edge » si le runtime Edge possède ce module. |
| cloudToDeviceMessageCount | en lecture seule | Nombre de messages cloud-à-module actuellement mis en file d’attente à envoyer au module. |
| connectionState | en lecture seule | Un champ indiquant l’état de la connexion : Connecté ou Déconnecté. Ce champ représente la vue IoT Hub de l’état de connexion de l’appareil. Important : Ce champ doit être utilisé uniquement à des fins de développement/débogage. L’état de la connexion est mis à jour uniquement pour les appareils utilisant les protocoles AMQP ou MQTT. Cet état est basé sur les pings au niveau du protocole (tests ping MQTT ou AMQP) et peut avoir un délai maximum de 5 minutes seulement. C’est pourquoi de faux positifs peuvent survenir. Par exemple, un appareil peut être signalé comme étant connecté, alors qu’il est déconnecté. |
| connectionStateUpdatedTime | en lecture seule | Un indicateur temporel, indiquant la date et la dernière heure de mise à jour de l’état de la connexion. |
| lastActivityTime | en lecture seule | Un indicateur temporel, indiquant la date et la dernière heure de connexion de l’appareil, de réception d’un message ou d’envoi d’un message. |
Notes
Les SDK d’appareil ne prennent pas en charge l’utilisation des caractères + et # dans les deviceId et moduleId.
Matériel de référence supplémentaire
Les autres articles de référence dans le Guide du développeur IoT Hub comprennent :
La rubrique Points de terminaison IoT Hub, qui décrit les différents points de terminaison que chaque hub IoT expose pour les opérations d’exécution et de gestion.
La rubrique Quotas et limitation IoT Hub décrit les quotas et le comportement de limitation qui s’appliquent au service IoT Hub.
La rubrique SDK des services et appareils Azure IoT, qui répertorie les SDK en différents langages que vous pouvez utiliser pour le développement d’applications d’appareil et de service qui interagissent avec IoT Hub.
La rubrique Langage de requête IoT Hub décrit le langage de requête permettant de récupérer à partir d’IoT Hub des informations sur les jumeaux d’appareil et les travaux.
La rubrique Prise en charge de MQTT au niveau d’IoT Hub, qui fournit des informations supplémentaires sur la prise en charge du protocole MQTT par IoT Hub.
Étapes suivantes
À présent que vous savez comment utiliser le registre des identités IoT Hub, vous serez peut-être intéressé par les rubriques suivantes du Guide du développeur Iot Hub :
Pour savoir comment utiliser le service d’approvisionnement des appareils IoT Hub afin d’activer l’approvisionnement sans contact et juste-à-temps, consultez :