Prise en main des représentations d’appareils (Node.js)

Article
03/21/2023

Les jumeaux d’appareil sont des documents JSON qui stockent des informations sur l’état des appareils (métadonnées, configurations et conditions). IoT Hub conserve une représentation 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.

Vous pouvez utiliser des jumeaux d’appareil pour répondre aux besoins suivants :

Stockez les métadonnées d’appareil à partir de votre serveur principal de solution.
Signaler les informations d’état actuel, telles que les capacités disponibles et les conditions, par exemple la méthode de connectivité utilisée, à partir de votre application d’appareil
Synchronisez l’état des workflows de longue durée, par exemple les mises à jour de microprogramme et de configuration, entre une application d’appareil et une application back-end.
Interroger les métadonnées, la configuration ou l’état de vos appareils

Les représentations d’appareil sont conçues pour les synchronisations et pour l’interrogation des configurations et des conditions d’appareil. Pour plus d’informations sur les jumeaux d’appareil, notamment quand utiliser des jumeaux d’appareil, consultez Comprendre les jumeaux d’appareil.

Les hubs IoT stockent des jumeaux d’appareil, qui contiennent les éléments suivants :

Tags (balises). Métadonnées d’appareil uniquement accessibles par le back-end de solution.
Propriétés souhaitées (Desired) . Objets JSON modifiables par le back-end de solution et observables par l’application d’appareil.
Propriétés signalées (Reported) . Objets JSON modifiables par l’application d’appareil et consultables par le back-end de solution.

Les balises et les propriétés ne peuvent pas contenir de tableaux, mais peuvent contenir des objets imbriqués.

L’illustration suivante montre l’organisation des jumeaux d’appareil :

Capture d’écran d’un schéma de concept de jumeau d’appareil.

En outre, le serveur principal de solution peut interroger les représentations d’appareil concernant toutes les données ci-dessus. Pour plus d’informations sur les jumeaux d’appareil, consultez Présentation des jumeaux d’appareil. Pour plus d’informations sur l’interrogation, consultez Langage de requête IoT Hub.

Cet article vous montre comment :

Utilisez une application d’appareil simulé pour signaler son canal de connectivité en tant que propriété signalée sur le jumeau d’appareil.
Interrogez les appareils à partir de votre application principale à l’aide de filtres sur les étiquettes et les propriétés précédemment créées.

Dans cet article, vous allez créer deux applications de console Node.js :

AddTagsAndQuery.js : une application back-end qui ajoute des balises et interroge les jumeaux d’appareils.
TwinSimulatedDevice.js : une application d’appareil simulé qui se connecte à votre hub IoT et signale son état de connectivité.

Notes

Pour plus d’informations sur les outils SDK disponibles pour créer des applications d’appareil et de back-end, consultez les SDK Azure IoT.

Prérequis

Pour effectuer ce qui est décrit dans cet article, vous avez besoin des éléments suivants :

Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.
Un appareil inscrit dans votre hub IoT. Si vous n’avez pas d’appareil dans votre hub IoT, suivez les étapes décrites dans Inscrire un appareil.
Node.j version 10.0.x ou ultérieure.
Vérifiez que le port 8883 est ouvert dans votre pare-feu. L’exemple d’appareil décrit dans cet article utilise le protocole MQTT, qui communique via le port 8883. Ce port peut être bloqué dans certains environnements réseau professionnels et scolaires. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous créez un service back-end qui ajoute des propriétés souhaitées à un jumeau d’appareil, puis interroge le registre des identités pour trouver tous les appareils dont les propriétés signalées ont été mises à jour en conséquence. Votre service a besoin de l’autorisation de connexion du service pour modifier les propriétés souhaitées d'un jumeau d’appareil, et de l’autorisation de lecture du registre pour interroger le registre des identités. Aucune stratégie d'accès partagé par défaut ne contient que ces deux autorisations. Vous devez donc en créer une.

Pour créer une stratégie d'accès partagé qui accorde des autorisations de connexion de service et de lecture du registre, et obtenir une chaîne de connexion pour cette stratégie, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre hub, sélectionnez Stratégies d’accès partagé.
Dans le menu supérieur au-dessus de la liste des stratégies, sélectionnez Ajouter une stratégie de politiques d’accès partagé.
Sous Ajouter une stratégie de politiques d’accès partagé, entrez un nom descriptif pour votre stratégie, par exemple serviceAndRegistryRead. Sous Autorisations, sélectionnez Lecture du registre et Connexion du service, puis sélectionnez Ajouter.
Sélectionnez votre nouvelle stratégie dans la liste des stratégies.
Sélectionnez l’icône de copie pour la Chaîne de connexion principale et enregistrez la valeur.

Pour plus d’informations sur les autorisations et les stratégies d’accès partagé IoT Hub, consultez Contrôle d’accès et autorisations.

Créer une application d’appareil qui met à jour les propriétés signalées

Dans cette section, vous allez créer une application console Node.js qui se connecte à votre hub en tant que myDeviceId, puis met à jour les propriétés signalées de sa représentation d’appareil afin qu’elles contiennent les informations confirmant qu’elle est connectée par le biais d’un réseau cellulaire.

Créez un dossier vide nommé reportconnectivity. Dans le dossier reportconnectivity, créez un fichier package.json en utilisant la commande suivante à l’invite de commandes. Le paramètre --yes accepte toutes les valeurs par défaut.
```
npm init --yes
```
Dans votre invite de commandes dans le dossier reportconnectivity, exécutez la commande suivante pour installer les packages azure-iot-device et azure-iot-device-mqtt :
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
À l’aide d’un éditeur de texte, créez un fichier ReportConnectivity.js dans le dossier reportconnectivity.

Ajoutez le code suivant au fichier ReportConnectivity.js. Remplacez {device connection string} par la chaîne de connexion de l’appareil que vous avez vu au moment de l’inscription d’un appareil dans IoT Hub :

    'use strict';
    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-mqtt').Mqtt;

    var connectionString = '{device connection string}';
    var client = Client.fromConnectionString(connectionString, Protocol);

    client.open(function(err) {
    if (err) {
        console.error('could not open IotHub client');
    }  else {
        console.log('client opened');

        client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            var patch = {
                connectivity: {
                    type: 'cellular'
                }
            };

            twin.properties.reported.update(patch, function(err) {
                if (err) {
                    console.error('could not update twin');
                } else {
                    console.log('twin state reported');
                    process.exit();
                }
            });
        }
        });
    }
    });

L’objet Client expose toutes les méthodes requises pour interagir avec des jumeaux d’appareil à partir de l’appareil. Le code précédent, après avoir initialisé l’objet Client, récupère la représentation d’appareil de myDeviceId, puis met à jour sa propriété signalée avec les informations de connectivité.

Exécuter l’application d’appareil
```
    node ReportConnectivity.js
```
Vous devriez voir le message twin state reported.
À présent que l’appareil a signalé ses informations de connectivité, il doit apparaître dans les deux requêtes. Accédez au dossier addtagsandqueryapp, puis réexécutez les requêtes :
```
    node AddTagsAndQuery.js
```
Cette fois, myDeviceId doit apparaître dans les résultats des deux requêtes.

Créer une application de service qui met à jour les propriétés souhaitées et interroge les jumeaux

Dans cette section, vous créez une application console Node.js qui ajoute des métadonnées d’emplacement à la représentation d’appareil associée à myDeviceId. L’application interroge IoT Hub pour lister les appareils situés aux États-Unis, puis interroge les appareils qui signalent une connexion réseau cellulaire.

Créez un dossier vide nommé addtagsandqueryapp. Dans le dossier addtagsandqueryapp, créez un fichier package.json en utilisant la commande suivante à l’invite de commandes. Le paramètre --yes accepte toutes les valeurs par défaut.
```
npm init --yes
```
À l’invite de commandes, dans le dossier addtagsandqueryapp, exécutez la commande suivante pour installer le package azure-iothub :
```
npm install azure-iothub --save
```
À l’aide d’un éditeur de texte, créez un fichier AddTagsAndQuery.js dans le dossier addtagsandqueryapp.

Ajoutez le code suivant au fichier AddTagsAndQuery.js. Remplacez {iot hub connection string} par la chaîne de connexion IoT Hub que vous avez copiée dans Obtenir la chaîne de connexion du hub IoT.

     'use strict';
     var iothub = require('azure-iothub');
     var connectionString = '{iot hub connection string}';
     var registry = iothub.Registry.fromConnectionString(connectionString);

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

L’objet Registry expose toutes les méthodes requises pour interagir avec des représentations d’appareil à partir du service. Le code précédent initialise l’objet Registry, récupère la représentation d’appareil de myDeviceId, puis met à jour ses balises avec les informations d’emplacement souhaitées.

Une fois les balises mises à jour, il appelle la fonction queryTwins.

Ajoutez le code suivant à la fin de AddTagsAndQuery.js pour implémenter la fonction queryTwins :

     var queryTwins = function() {
         var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });

         query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });
     };

Le code précédent exécute deux requêtes : la première sélectionne uniquement les représentations des appareils situés dans l’usine Redmond43et la seconde affine la requête pour sélectionner uniquement les appareils qui sont également connectés via un réseau cellulaire.

Quand le code crée l’objet query, il spécifie le nombre maximal de documents retournés dans le deuxième paramètre. L’objet query contient une propriété booléenne hasMoreResults permettant d’appeler les méthodes nextAsTwin plusieurs fois afin de récupérer tous les résultats. Une méthode appelée next est disponible pour les résultats qui ne sont pas des jumeaux d’appareil, par exemple les résultats de requêtes d’agrégation.

Exécutez l’application avec :
```
    node AddTagsAndQuery.js
```
Vous devriez voir un appareil dans les résultats de la requête demandant tous les appareils situés à Redmond43, et aucun pour la requête limitant les résultats aux appareils utilisant un réseau cellulaire.

Dans cet article, vous découvrirez comment :

Ajouté des métadonnées d’appareil en tant que balises à partir d’une application back-end
Signalé des informations de connectivité des appareils dans le jumeau d’appareil
Interrogé des informations du jumeau d’appareil, en utilisant le langage de requête IoT Hub de type SQL

Étapes suivantes

Pour découvrir comment :

Pour envoyer de la télémétrie à partir d’appareils, consultez Démarrage rapide : Envoyer des données de télémétrie à partir d’un appareil IoT Plug-and-Play vers Azure IoT Hub
Pour configurer des appareils à l’aide des propriétés souhaitées du jumeau d’appareil, consultez Tutoriel : Configurer vos appareils à partir d’un service back-end
Pour contrôler les appareils de manière interactive, comme l’activation d’un ventilateur à partir d’une application contrôlée par l’utilisateur, consultez Démarrage rapide : contrôler un appareil connecté à un IoT Hub

Partager via