Tutoriel : Provisionner vos conditions de travail de création et surveiller les conditions de travail avec Azure Digital Twins Preview

Article
01/10/2020

Important

Une nouvelle version du service Azure Digital Twins a été publiée. En fonction des fonctionnalités étendues du nouveau service, le service Azure Digital Twins d’origine (décrit dans ce jeu de documentation) a été supprimé.

Pour afficher la documentation du nouveau service, consultez la documentation Azure Digital Twins active.

Ce didacticiel montre comment utiliser la préversion d’Azure Digital Twins pour surveiller les conditions de température et le niveau de confort souhaités pour vos espaces. Après avoir configuré votre exemple de bâtiment, vous pouvez le provisionner et exécuter des fonctions personnalisées dans vos données de capteur en suivant les étapes de ce tutoriel.

Dans ce tutoriel, vous allez apprendre à :

Définir les conditions à superviser.
Créer une fonction définie par l’utilisateur.
Simuler des données de capteur.
Obtenir les résultats d’une fonction définie par l’utilisateur.

Prérequis

Ce tutoriel suppose que vous avez terminé votre configuration Azure Digital Twins. Avant de poursuivre, assurez-vous que vous avez les éléments suivants :

Un compte Azure.
Une instance de Digital Twins en cours d’exécution.
Les exemples C# Digital Twins téléchargés et extraits sur votre machine de travail.
Le kit SDK .NET Core version 2.1.403 ou ultérieure sur votre machine de développement pour générer et exécuter l’exemple. Exécutez dotnet --version pour vérifier que la version appropriée est installée.
Visual Studio Code pour explorer l’exemple de code.

Conseil

Utilisez un nom d’instance Digital Twins unique si vous provisionnez une nouvelle instance.

Définition des conditions à surveiller

Vous pouvez définir un ensemble de conditions spécifiques à superviser dans les données de capteur ou d’appareil ; il est appelé détecteur de problèmes de correspondance. Vous pouvez ensuite définir des fonctions appelées fonctions définies par l’utilisateur. Ces fonctions exécutent une logique personnalisée sur les données provenant de vos espaces et de vos appareils, quand les conditions spécifiées par les détecteurs de problèmes de correspondance se produisent. Pour plus d’informations, consultez Traitement des données et fonctions définies par l’utilisateur.

À partir de l’exemple de projet occupancy-quickstart, ouvrez le fichier src\actions\provisionSample.yaml dans Visual Studio Code. Notez la section qui commence par le type matchers. Chaque entrée sous ce type crée un détecteur de problèmes de correspondance avec la valeur Name (Nom) spécifiée. Cet outil de détection supervise un capteur de type dataTypeValue. Notez sa relation avec l’espace nommé Focus Room A1 (Salle de travail A1), qui est doté d’un nœud d’appareils contenant quelques capteurs. Pour provisionner un détecteur de problèmes de correspondance effectuant le suivi d’un de ces capteurs, assurez-vous que sa valeur de dataTypeValue correspond à celle de dataType du capteur.

Ajoutez le détecteur de problèmes de correspondance suivant sous ceux qui existent déjà. Assurez-vous que les clés sont alignées et que les espaces ne sont pas remplacés par des tabulations. Ces lignes sont également présentes dans le fichier provisionSample.yaml en tant que lignes commentées. Vous pouvez supprimer les marques de commentaire en retirant le caractère # au début de chaque ligne.

      - name: Matcher Temperature
        dataTypeValue: Temperature

Ce détecteur de problèmes de correspondance va assurer le suivi du capteur SAMPLE_SENSOR_TEMPERATURE que vous avez ajouté dans le premier tutoriel.

Créer une fonction définie par l’utilisateur

Vous pouvez utiliser les fonctions définies par l’utilisateur pour personnaliser le traitement de vos données de capteur. Celles-ci sont constituées d’un code JavaScript personnalisé pouvant être exécuté au sein de votre instance Azure Digital Twins lorsque des conditions spécifiques se produisent, telles que décrites par les détecteurs de problèmes de correspondance. Vous pouvez créer des détecteurs de problèmes de correspondance et des fonctions définies par l’utilisateur pour chaque capteur que vous souhaitez superviser. Pour plus d’informations, consultez Traitement des données et fonctions définies par l’utilisateur.

Dans l’exemple de fichier provisionSample.yaml, recherchez une section qui commence par le type userdefinedfunctions. Cette section configure une fonction définie par l’utilisateur avec un Nom donné. Cette fonction définie par l’utilisateur agit sur la liste des détecteurs de problèmes de correspondance, sous matcherNames (Noms des détecteurs de problèmes de correspondance). Notez la façon dont vous pouvez fournir votre propre fichier JavaScript à l’UDF en tant que script.

Notez également la section nommée roleassignments. Il affecte le rôle d’administrateur de l’espace à la fonction définie par l’utilisateur. Ce rôle lui permet d’accéder aux événements qui proviennent d’un des espaces provisionnés.

Configurez la fonction UDF pour inclure le matcheur de température en ajoutant ou en supprimant les commentaires de la ligne suivante dans le matcherNames nœud du fichier provisionSample.yaml :
```
        - Matcher Temperature
```
Ouvrez le fichier src\actions\userDefinedFunctions\availability.js dans votre éditeur. Il s’agit du fichier référencé dans l’élément script du fichier provisionSample.yaml. La fonction définie par l’utilisateur dans ce fichier recherche des conditions d’absence de mouvement dans la salle, et des niveaux de dioxyde de carbone inférieurs à 1 000 ppm.

Modifiez le fichier JavaScript pour surveiller la température ainsi que d’autres conditions. Ajoutez les lignes de code suivantes pour rechercher les conditions où aucun mouvement n’est détecté dans la salle, où le niveau de dioxyde de carbone est inférieur à 1 000 ppm et celui de la température inférieur à 25,5 degrés Celsius (78 degrés Fahrenheit).

Notes

Cette section modifie le fichier src\actions\userDefinedFunctions\availability.js afin que vous puissiez apprendre en détail une façon d’écrire une fonction définie par l’utilisateur. Toutefois, vous pouvez choisir d’utiliser directement le fichier src\actions\userDefinedFunctions\availabilityForTutorial.js dans votre configuration. Ce fichier contient toutes les modifications requises pour ce didacticiel. Si vous utilisez ce fichier à la place, veillez à utiliser le nom de fichier approprié pour la clé script dans le fichier src\actions\provisionSample.yaml.

a. En haut du fichier, ajoutez les lignes suivantes pour la température en-dessous du commentaire // Add your sensor type here:
```
    var temperatureType = "Temperature";
    var temperatureThreshold = 78;
```
b. Ajoutez les lignes suivantes après l’instruction qui définit var motionSensor, en-dessous du commentaire // Add your sensor variable here:
```
   var temperatureSensor = otherSensors.find(function(element) {
       return element.DataType === temperatureType;
   });
```
c. Ajoutez la ligne suivante après l’instruction qui définit var carbonDioxideValue, en-dessous du commentaire // Add your sensor latest value here :
```
    var temperatureValue = getFloatValue(temperatureSensor.Value().Value);
```
d. Supprimez les lignes de code suivantes en dessous du commentaire // Modify this line to monitor your sensor value :
```
   if(carbonDioxideValue === null || motionValue === null) {
       sendNotification(telemetry.SensorId, "Sensor", "Error: Carbon dioxide or motion are null, returning");
       return;
   }
```
Remplacez-les par les lignes suivantes :
```
    if(carbonDioxideValue === null || motionValue === null || temperatureValue === null){
        sendNotification(telemetry.SensorId, "Sensor", "Error: Carbon dioxide, motion, or temperature are null, returning");
        return;
    }
```
e. Supprimez les lignes de code suivantes en dessous du commentaire // Modify these lines as per your sensor :
```
    var availableFresh = "Room is available and air is fresh";
    var noAvailableOrFresh = "Room is not available or air quality is poor";
```
Remplacez-les par les lignes suivantes :
```
    var alert = "Room with fresh air and comfortable temperature is available.";
    var noAlert = "Either room is occupied, or working conditions are not right.";
```
f. Supprimez le bloc de code if-else suivant après le commentaire // Modify this code block for your sensor :
```
    // If carbonDioxide less than threshold and no presence in the room => log, notify and set parent space computed value
    if(carbonDioxideValue < carbonDioxideThreshold && !presence) {
        log(`${availableFresh}. Carbon Dioxide: ${carbonDioxideValue}. Presence: ${presence}.`);
        setSpaceValue(parentSpace.Id, spaceAvailFresh, availableFresh);
    }
    else {
        log(`${noAvailableOrFresh}. Carbon Dioxide: ${carbonDioxideValue}. Presence: ${presence}.`);
        setSpaceValue(parentSpace.Id, spaceAvailFresh, noAvailableOrFresh);

        // Set up custom notification for poor air quality
        parentSpace.Notify(JSON.stringify(noAvailableOrFresh));
    }
```
Remplacez-le par le bloc if-else suivant :
```
    // If sensor values are within range and room is available
    if(carbonDioxideValue < carbonDioxideThreshold && temperatureValue < temperatureThreshold && !presence) {
        log(`${alert}. Carbon Dioxide: ${carbonDioxideValue}. Temperature: ${temperatureValue}. Presence: ${presence}.`);

        // log, notify and set parent space computed value
        setSpaceValue(parentSpace.Id, spaceAvailFresh, alert);

        // Set up notification for this alert
        parentSpace.Notify(JSON.stringify(alert));
    }
    else {
        log(`${noAlert}. Carbon Dioxide: ${carbonDioxideValue}. Temperature: ${temperatureValue}. Presence: ${presence}.`);

        // log, notify and set parent space computed value
        setSpaceValue(parentSpace.Id, spaceAvailFresh, noAlert);
    }
```
L’UDF modifiée recherchera une condition où la salle est disponible et où son niveau de dioxyde de carbone et sa température se situent dans la plage acceptable. Il génère une notification avec l’instruction parentSpace.Notify(JSON.stringify(alert)); lorsque cette condition est remplie. Il définit la valeur de l’espace surveillé, sans tenir compte du fait que la condition est remplie ou non, avec le message correspondant.

g. Enregistrez le fichier.
Ouvrez une fenêtre de commande et accédez au dossier occupancy-quickstart\src. Exécutez la commande suivante pour configurer le graphe d’intelligence spatiale et la fonction définie par l’utilisateur :
```
dotnet run ProvisionSample
```
Important

Pour empêcher tout accès non autorisé à votre API de gestion Digital Twins, l’application occupancy-quickstart vous oblige à vous connecter avec vos informations d’identification de compte Azure. Elle enregistre vos informations d’identification pour une courte période, afin que vous n’ayez pas besoin de vous connecter à chaque exécution. Lorsque ce programme s’exécute pour la première fois et que vos informations d’identification enregistrées expirent, l’application vous dirige vers une page de connexion et vous donne un code propre à la session qui doit être entré sur cette page. Suivez les instructions de l’invite pour vous connecter avec votre compte Azure.
Une fois votre compte authentifié, l’application commence à créer un exemple de graphe spatial, tel que configuré dans provisionSample.yaml. Attendez la fin du provisionnement. Cette opération peut prendre quelques minutes. Examinez ensuite les messages dans la fenêtre de commande et voyez comment votre graphe spatial est créé. Remarquez la façon dont l’application crée un hub IoT au niveau du nœud racine ou de Venue.
À partir de la sortie dans la fenêtre de commande, copiez la valeur de ConnectionString, sous la section Devices, dans le presse-papiers. Vous en aurez besoin pour simuler la connexion de l’appareil à la section suivante.

Conseil

Si au cours de l’opération de provisionnement, vous obtenez un message d’erreur semblable à celui-ci : « L’opération d’E/S a été abandonnée en raison d’une sortie du thread ou d’une requête d’application », essayez de réexécuter la commande. Il est possible que le client HTTP ait expiré suite à un problème de réseau.

Simulation de données de capteur

Dans cette section, vous utilisez le projet nommé device-connectivity dans l’exemple. Vous simulez des données de capteur pour la détection de mouvement, de température et de dioxyde de carbone. Ce projet génère des valeurs aléatoires pour les capteurs, puis les envoie au hub IoT en utilisant la chaîne de connexion d’appareil.

Dans une fenêtre de commande distincte, accédez à l’exemple Azure Digital Twins, puis au dossier device-connectivity.
Exécutez cette commande pour vous assurer que les dépendances du projet sont correctes :
```
dotnet restore
```
Ouvrez le fichier appsettings.json dans votre éditeur et modifiez les valeurs suivantes :

a. DeviceConnectionString : affectez la valeur de ConnectionString dans la fenêtre de sortie à partir de la section précédente. Copiez cette chaîne entièrement, entre guillemets, pour que le simulateur puisse se connecter correctement au hub IoT.

b. HardwareId dans le tableau capteurs : étant donné que vous simulez des événements à partir de capteurs approvisionnés dans votre instance Azure Digital Twins, l’ID matériel et les noms des capteurs de ce fichier doivent correspondre au sensors nœud du fichier provisionSample.yaml .

Ajoutez une nouvelle entrée pour le capteur de température. Le nœud Sensors (Capteurs) dans le fichier appsettings.json doit se présenter de la façon suivante :
```
"Sensors": [{
  "DataType": "Motion",
  "HardwareId": "SAMPLE_SENSOR_MOTION"
},{
  "DataType": "CarbonDioxide",
  "HardwareId": "SAMPLE_SENSOR_CARBONDIOXIDE"
},{
  "DataType": "Temperature",
  "HardwareId": "SAMPLE_SENSOR_TEMPERATURE"
}]
```
Exécutez cette commande pour démarrer la simulation des événements d’appareil concernant la température, le mouvement et le dioxyde de carbone :
```
dotnet run
```
Notes

Comme l’exemple de simulation ne communique pas directement avec votre instance Digital Twin, aucune authentification n’est nécessaire.

Obtention des résultats de la fonction définie par l’utilisateur

La fonction définie par l’utilisateur s’exécute chaque fois que votre instance reçoit des données du capteur et de l’appareil. Cette section interroge votre instance Azure Digital Twins afin d’obtenir les résultats de la fonction définie par l’utilisateur. Vous serez alors informé de la disponibilité d’une pièce, de la qualité de l’air à l’intérieur et de sa température pratiquement en temps réel.

Ouvrez la fenêtre de commande que vous avez utilisée pour provisionner l’exemple, ou une nouvelle fenêtre de commande, et accédez de nouveau au dossier occupancy-quickstart\src de l’exemple.
Exécutez la commande suivante et connectez-vous lorsque vous y êtes invité :
```
dotnet run GetAvailableAndFreshSpaces
```

La fenêtre de sortie illustre la façon dont la fonction définie par l’utilisateur s’exécute et intercepte les événements à partir de la simulation d’appareil.

Si la condition supervisée est remplie, la fonction définie par l’utilisateur détermine la valeur de l’espace avec le message approprié, comme nous l’avons vu plus tôt. La fonction GetAvailableAndFreshSpaces affiche le message sur la console.

Nettoyer les ressources

Si vous souhaitez arrêter votre exploration d’Azure Digital Twins ici, vous pouvez supprimer les ressources créées dans ce tutoriel :

Dans le menu de gauche du portail Azure, sélectionnez Toutes les ressources, puis votre groupe de ressources Digital Twins et Supprimer.

Conseil

Si vous avez rencontré des difficultés pour supprimer votre instance de Digital Twins, une mise à jour du service a été déployée avec le correctif. Réessayez de supprimer votre instance.
Si nécessaire, supprimez les exemples d’applications de votre machine de travail.

Étapes suivantes

Maintenant que vous avez provisionné vos espaces et créé une infrastructure pour déclencher des notifications personnalisées, vous pouvez passer à l’un des tutoriels suivants :

Didacticiel : Recevoir des notifications à partir de vos espaces Azure Digital Twins à l’aide de Logic Apps

Didacticiel : Visualiser et analyser des événements à partir de vos espaces Azure Digital Twins à l’aide de Time Series Insights