Comprendre et utiliser les jumeaux d’appareil IoT Hub
Les jumeaux d’appareil sont des documents JSON qui stockent des informations sur l’état des appareils (métadonnées, configurations et conditions). Azure IoT Hub conserve un jumeau d’appareil pour chaque appareil que vous y connectez.
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.
Cet article aborde les points suivants :
- La structure du jumeau d’appareil : balises, propriétés souhaitées et propriétés signalées.
- Les opérations que les applications d’appareils et les applications principales peuvent effectuer sur des jumeaux d’appareil.
Vous pouvez utiliser des jumeaux d’appareil pour répondre aux besoins suivants :
Stocker les métadonnées spécifiques à l’appareil dans le cloud, Par exemple, l’emplacement d’un distributeur automatique.
Signaler les informations d’état actuel, telles que les capacités disponibles et les conditions, à partir de votre application pour appareil, Par exemple, si un appareil connecté à votre hub IoT via un réseau mobile ou Wi-Fi.
Synchroniser l’état des flux de travail de longue durée entre une application pour appareil et un back-end, par exemple, lorsque le back-end de solution spécifie une nouvelle version de microprogramme à installer et que l’application pour appareil rapporte les différentes étapes du processus de mise à jour.
Interroger les métadonnées, la configuration ou l’état de vos appareils
Pour plus d’informations sur l’utilisation des propriétés signalées, des messages appareil-à-cloud ou du chargement de fichiers, consultez le guide de communication appareil-à-cloud.
Pour plus d’informations sur l’utilisation des propriétés souhaitées, des méthodes directes ou des messages cloud-à-appareil, consultez les conseils de communication cloud-à-appareil.
Pour découvrir dans quelle mesure les jumeaux d’appareil sont liés au modèle d’appareil utilisé par un appareil Azure IoT Plug-and-Play, consultez Comprendre les jumeaux numériques IoT Plug-and-Play.
Jumeaux d’appareil
Les jumeaux d’appareil stockent des informations relatives aux appareils, dont l’utilité est la suivante :
Ils permettent à un appareil et à un back-end de synchroniser les conditions et la configuration de l’appareil.
Ils permettent à un back-end de solution d’interroger et de cibler des opérations de longue durée.
Le cycle de vie d’un jumeau d’appareil est lié à son identité d’appareil correspondante. Des jumeaux d’appareil sont implicitement créés et supprimés lors de la création ou de la suppression d’une identité d’appareil dans IoT Hub.
Un jumeau d’appareil est un document JSON incluant les éléments suivants :
Tags (balises). Une section du document JSON accessible en lecture et en écriture par le serveur principal de solution. Les balises ne sont pas visibles pour des applications d’appareil.
Propriétés souhaitées (Desired) . Utilisées en même temps que les propriétés signalées pour synchroniser une configuration ou une condition d’appareil. Le serveur principal de solution peut définir les propriétés souhaitées, et l’application d’appareil peut les lire. L’application d’appareil peut également recevoir des notifications sur les changements des propriétés souhaitées.
Propriétés signalées (Reported) . Utilisées en même temps que les propriétés souhaitées pour synchroniser une configuration ou une condition d’appareil. L’application d’appareil peut définir les propriétés signalées, et le serveur principal de solution peut les lire et les interroger.
Propriétés d’identité des appareils. La racine du document JSON du jumeau d’appareil contient les propriétés en lecture seule de l’identité d’appareil correspondante stockées dans le registre des identités. Les propriétés
connectionStateUpdatedTimeetgenerationIdne seront pas incluses.
L’exemple suivant montre un document JSON de jumeau d’appareil :
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
L’objet racine contient les propriétés d’identité des appareils et des objets conteneur pour tags et pour les propriétés reported et desired. Le conteneur properties contient des éléments en lecture seule ($metadata et $version) décrits dans les sections Métadonnées de jumeau d’appareil et Accès concurrentiel optimiste.
Exemple de propriété signalée (Reported)
Dans l’exemple précédent, le jumeau d’appareil contient une propriété batteryLevel qui est signalée par l’application d’appareil. Cette propriété permet d’interroger des appareils et d’agir sur ceux-ci en fonction du dernier niveau signalé de charge de la batterie. D’autres exemples incluent une application d’appareil signalant des capacités d’appareil ou des options de connectivité.
Notes
Les propriétés signalées simplifient les scénarios où le serveur principal de solution s’intéresse à la dernière valeur connue d’une propriété. Si le back-end de la solution doit traiter une télémétrie d’appareil se présentant sous la forme de séquences d’événements horodatés, telles que des séries chronologiques, utilisez des messages appareil-à-cloud.
Exemple de propriété souhaitée
Dans l’exemple précédent, les propriétés souhaitées et signalées du jumeau d’appareil telemetryConfig sont utilisées par le serveur principal d’application et l’application d’appareil pour synchroniser la configuration de la télémétrie pour cet appareil. Par exemple :
Le serveur principal de solution définit la propriété souhaitée avec la valeur de configuration souhaitée. Voici la partie du document contenant la propriété souhaitée définie :
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },L’application de l’appareil est informée de la modification immédiatement si l’appareil est connecté. S’il n’est pas connecté, l’application d’appareil suit le flux de reconnexion de l’appareil lorsqu’il se connecte. L’application d’appareil signale ensuite la configuration mise à jour (ou une condition d’erreur à l’aide de la propriété
status). Voici la partie contenant les propriétés signalées :"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }Le back-end de la solution peut suivre les résultats de l’opération de configuration sur de nombreux appareils en interrogeant les jumeaux d’appareil.
Notes
Les extraits de code précédents sont des exemples, optimisés pour la lisibilité, de manière possible d’encoder la configuration d’un appareil et son état. IoT Hub n’impose pas de schéma spécifique pour les propriétés souhaitées et signalées de jumeau d’appareil dans les jumeaux d’appareil.
Important
IoT Plug-and-Play définit un schéma qui utilise plusieurs propriétés supplémentaires pour synchroniser les modifications apportées aux propriétés souhaitées et signalées. Si votre solution utilise IoT Plug-and-Play, vous devez respecter les conventions de Plug-and-Play lors de la mise à jour des propriétés des jumeaux. Pour plus d’informations et un exemple, consultez Propriétés accessibles en écriture dans IoT Plug-and-Play.
Vous pouvez utiliser des jumeaux pour synchroniser des opérations de longue durée, telles que des mises à jour de microprogramme. Pour plus d’informations sur l’utilisation de propriétés pour synchroniser et suivre une opération de longue durée sur des appareils, consultez Utiliser des propriétés souhaitées pour configurer des appareils.
Opérations principales
Le back-end de solution opère sur le jumeau d’appareil en utilisant les opérations atomiques suivantes, exposées par le biais du protocole HTTPS :
Récupérer le jumeau d’appareil par son ID. Cette opération renvoie le contenu du document du jumeau d’appareil, à savoir les Tags (balises) et les propriétés système souhaitées (Desired) et signalées (Reported).
Mettre à jour partiellement le jumeau d’appareil. Cette opération permet au serveur principal de solution de mettre à jour partiellement les Tags (balises) ou les propriétés souhaitées (Desired) dans un jumeau d’appareil. La mise à jour partielle est exprimée sous la forme d’un document JSON qui ajoute ou met à jour toute propriété. Les propriétés définies sur
nullsont supprimées. L’exemple suivant crée une propriété souhaitée avec la valeur{"newProperty": "newValue"}, remplace la valeur existante deexistingPropertypar"otherNewValue"et supprimeotherOldProperty. Aucune autre modification n’est apportée aux autres propriétés souhaitées ou Tags existants :{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Remplacer des propriétés souhaitées. Cette opération permet au serveur principal de la solution de remplacer complètement toutes les propriétés souhaitées existantes, et de remplacer
properties/desiredpar un nouveau document JSON.Remplacer des Tags. Cette opération permet au serveur principal de la solution de remplacer complètement tous les Tags existants, et de remplacer
tagspar un nouveau document JSON.Recevoir des notifications jumelles. Cette opération permet au back-end de la solution d’être notifié lorsque le jumeau est modifié. Pour ce faire, votre solution IoT doit créer un itinéraire et définir la source de données équivalente à twinChangeEvents. Par défaut, aucune route n’existe, donc aucune notification jumelle n’est envoyée. Si le taux de variation est trop élevé, ou pour d’autres raisons, telles que des défaillances internes, IoT Hub peut envoyer une seule notification qui contient toutes les modifications. Par conséquent, si l’audit et la journalisation fiables de tous les états intermédiaires sont nécessaires pour votre application, vous devez utiliser des messages appareil-à-cloud. Pour en savoir plus sur les propriétés et le corps retournés dans le message de notification jumelle, consultez Schémas d’événements autres que les événements de télémétrie.
Toutes les opérations précédentes prennent en charge l’accès concurrentiel optimiste et nécessitent l’autorisation ServiceConnect définie dans Contrôler l’accès à IoT Hub.
En plus de ces opérations, le back-end de la solution peut :
Interroger les jumeaux d’appareil à l’aide du langage de requête IoT Hub similaire à SQL.
Effectuer des opérations sur les grands ensembles de jumeaux d’appareil à l’aide de travaux.
Opérations d’appareil
L’application d’appareil opère sur le jumeau d’appareil en utilisant les opérations atomiques suivantes :
Récupérer le jumeau d’appareil. Cette opération renvoie le contenu du document du jumeau d’appareil, à savoir les propriétés système souhaitées (Desired) et signalées (Reported) pour l’appareil actuellement connecté. (Les balises ne sont pas visibles pour des applications d’appareil.)
Mettre à jour partiellement les propriétés signalées (Reported) . Cette opération permet la mise à jour partielle des propriétés signalées de l’appareil actuellement connecté. Cette opération utilise le même format de mise à jour JSON que le serveur principal de solution utilise pour une mise à jour partielle des propriétés souhaitées.
Observer les propriétés souhaitées (Desired) . L’appareil actuellement connecté peut choisir d’être informé des mises à jour des propriétés souhaitées au moment où elles se produisent. L’appareil reçoit la forme de mise à jour (remplacement partiel ou complet) exécutée par le serveur principal de la solution.
Toutes les opérations précédentes nécessitent l’autorisation DeviceConnect, comme défini dans Contrôler l’accès à IoT Hub.
Les kits Azure IoT device SDK simplifient l’utilisation des opérations précédentes dans un grand nombre de langages et de plateformes. Pour plus d’informations sur les détails des primitives d’IoT Hub concernant la synchronisation des propriétés souhaitées, consultez Flux de reconnexion d’appareil.
Format des Tags et propriétés
Les Tags (balises) ainsi que les propriétés souhaitées (Desired) et signalées (Reported) sont des objets JSON soumis aux restrictions suivantes :
Clés : Toutes les clés des objets JSON sont encodées en UTF-8, respectent la casse et mesurent jusqu’à 1 Ko. Les caractères autorisés excluent les caractères de contrôle UNICODE (segments C0 et C1), ainsi que
.,$et SP.Notes
Les requêtes IoT Hub utilisées dans le Routage des messages ne prennent pas en charge les espaces ou l’un des caractères suivants dans un nom de clé :
()<>@,;:\"/?={}.Valeurs : Toutes les valeurs figurant dans les objets JSON peuvent être des types JSON suivants : booléen, nombre, chaîne, objet. Les tableaux sont également pris en charge.
Les entiers peuvent avoir une valeur minimale de 4503599627370496 et une valeur maximale de 4503599627370495.
Les valeurs de chaîne sont encodées au format UTF-8 et peuvent avoir une longueur maximale de 4 Ko.
Profondeur : La profondeur maximale des objets JSON dans les balises, les propriétés souhaitées et les propriétés signalées est de 10. Par exemple, l’objet suivant est valide :
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Taille de jumeau d’appareil
IoT Hub applique une limite de taille de 8 Ko à la valeur tags, et une limite de taille de 32 Ko aux valeurs properties/desired et properties/reported. Ces totaux n’incluent pas les éléments en lecture seule, tels que $version et $metadata/$lastUpdated.
La taille du jumeau est calculée comme suit :
Pour chaque propriété du document JSON, IoT Hub calcule et ajoute de façon cumulative la longueur de la clé et la valeur de la propriété.
Les clés de propriété sont considérées comme des chaînes encodées au format UTF8.
Les valeurs de propriété simples sont considérées comme des chaînes encodées au format UTF8, des valeurs numériques (huit octets) ou des valeurs booléennes (quatre octets).
La taille des chaînes encodées au format UTF8 est calculée en comptant tous les caractères, à l’exception des caractères de contrôle UNICODE (segments C0 et C1).
Les valeurs de propriété complexes (objets imbriqués) sont calculées en fonction de la taille agrégée des clés de propriété et des valeurs de propriété qu’elles contiennent.
IoT Hub rejette en générant une erreur toute opération susceptible d’augmenter la taille des documents tags, properties/desired ou properties/reported au-delà de la limite.
Métadonnées de jumeau d’appareil
IoT Hub tient à jour l’horodateur de la dernière mise à jour de chaque objet JSON dans les propriétés souhaitées et signalées du jumeau d’appareil. Les horodateurs sont exprimés en UTC et codés au format ISO8601YYYY-MM-DDTHH:MM:SS.mmmZ.
Par exemple :
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
Ces informations sont conservées à chaque niveau (pas uniquement celui des feuilles de la structure JSON) afin de préserver les mises à jour qui suppriment des clés d’objet.
Accès concurrentiel optimiste
Les Tags ainsi que les propriétés souhaitées (Desired) et signalées (Reported) prennent en charge l’accès concurrentiel optimiste. Si vous devez garantir l’ordre des mises à jour des propriétés de jumeau, envisagez d’implémenter la synchronisation au niveau de l’application en attendant le rappel des propriétés signalées avant d’envoyer la prochaine mise à jour.
Les jumeaux d’appareil ont une propriété ETag (etag), conformément à RFC7232, qui représente la représentation JSON du jumeau. Vous pouvez utiliser la propriété etag dans des opérations de mise à jour conditionnelle à partir du serveur principal de solution pour assurer la cohérence. Il s’agit de la seule option permettant de garantir la cohérence dans les opérations qui impliquent le conteneur tags.
Les propriétés souhaitées et signalées du jumeau d’appareil ont aussi une valeur $version dont la nature incrémentielle est garantie. De même qu’un ETag, la version peut être utilisée par la partie effectuant la mise à jour afin d’assurer la cohérence des mises à jour. Par exemple, une application d’appareil pour une propriété signalée ou le serveur principal de solution pour une propriété souhaitée.
Les versions sont également utiles quand un agent observateur (par exemple, l’application d’appareil observant les propriétés souhaitées) doit concilier des concurrences entre les résultats d’une opération de récupération et d’une notification de mise à jour. Pour plus d’informations, consultez la section Flux de reconnexion d’appareil.
Flux de reconnexion d’appareil
IoT Hub ne conserve pas les notifications de mise à jour de propriétés souhaitées pour les appareils déconnectés. Il en résulte qu’un appareil qui se connecte doit récupérer le document complet des propriétés souhaitées, en plus de s’abonner aux notifications de mise à jour. Étant donné la possibilité de concurrences entre les notifications de mise à jour et la récupération complète, le flux suivant doit être assuré :
- L’application d’appareil se connecte à un hub IoT.
- L’application d’appareil s’abonne aux notifications de mise à jour des propriétés souhaitées.
- L’application d’appareil récupère le document complet pour les propriétés souhaitées.
L’application d’appareil peut ignorer toutes les notifications dont la $version a une valeur inférieure ou égale à la version du document complet récupéré. Cette approche est possible, car IoT Hub garantit que les numéros de version sont toujours incrémentiels.
Étapes suivantes
À présent que vous savez ce que sont des jumeaux d’appareil, vous serez peut-être intéressé par les rubriques suivantes du Guide du développeur IoT Hub :
- Comprendre et utiliser les jumeaux de module dans IoT Hub
- Appeler une méthode directe sur un appareil
- Planifier des travaux sur plusieurs appareils
Pour tenter de mettre en pratique certains des concepts décrits dans cet article, consultez les didacticiels IoT Hub suivants :