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.

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 le back-end de solution 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 d’appareil et des applications back-end. Par exemple, lorsqu’une application back-end spécifie la nouvelle version de microprogramme à installer et que l’application d’appareil indique 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 :

• Les applications d’appareil et les applications back-end peuvent utiliser pour 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 les applications back-end. 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. Les applications back-end peuvent 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 les applications back-end peuvent 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 connectionStateUpdatedTime et generationId ne sont 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 la propriété signalée batteryLevel. 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é.

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 :

1. Une application back-end 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"
       },
       ...
   },
   

2. 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"
       }
       ...
   }
   

3. Une application back-end suit les résultats de l’opération de configuration sur de nombreux appareils en interrogeant les jumeaux d’appareil.

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 met partiellement à jour les étiquettes ou les propriétés souhaitées 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 null sont supprimées. L’exemple suivant crée une propriété souhaitée avec la valeur {"newProperty": "newValue"}, remplace la valeur existante de existingProperty par "otherNewValue" et supprime otherOldProperty. 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 remplace complètement toutes les propriétés souhaitées existantes et substitue properties/desired par un nouveau document JSON.

• Remplacer des Tags. Cette opération remplace complètement toutes les étiquettes existantes et substitue tags par un nouveau document JSON.

• Recevoir des notifications jumelles. Cette opération notifie lorsque le jumeau est modifié. Pour recevoir des notifications de changement de jumeau d’appareil, 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é.

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

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 :

• IoT Hub calcule et ajoute de façon cumulative la longueur de la clé et la valeur de chaque 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 à la RFC7232, qui correspond à 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. Cette propriété est 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, vous pouvez utiliser la propriété de version afin d’assurer la cohérence des mises à jour. Par exemple, une application d’appareil pour une propriété signalée ou une application back-end 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é :

1. L’application d’appareil se connecte à un hub IoT.
2. L’application d’appareil s’abonne aux notifications de mise à jour des propriétés souhaitées.
3. 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

Pour mettre en pratique certains des concepts décrits dans cet article, consultez l’article IoT Hub suivant :

• Tutoriel : configurer vos appareils avec des propriétés de jumeau d’appareil
• Comment utiliser des jumeaux d’appareil