Tutoriel : Provisionner votre bâtiment et superviser les conditions de travail avec la préversion d’Azure Digital TwinsTutorial: Provision your building and monitor working conditions with Azure Digital Twins Preview

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.This tutorial demonstrates how to use Azure Digital Twins Preview to monitor your spaces for desired temperature conditions and comfort level. 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.After you configure your sample building, you can provision your building and run custom functions on your sensor data by using the steps in this tutorial.

Dans ce tutoriel, vous allez apprendre à :In this tutorial, you learn how to:

  • Définir les conditions à superviser.Define conditions to monitor.
  • Créer une fonction définie par l’utilisateur.Create a user-defined function (UDF).
  • Simuler des données de capteur.Simulate sensor data.
  • Obtenir les résultats d’une fonction définie par l’utilisateur.Get results of a user-defined function.

Conditions préalables requisesPrerequisites

Ce tutoriel suppose que vous avez terminé votre configuration Azure Digital Twins.This tutorial assumes that you have finished your Azure Digital Twins setup. Avant de poursuivre, assurez-vous que vous avez les éléments suivants :Before proceeding, make sure that you have:

Conseil

Utilisez un nom d’instance Digital Twins unique si vous provisionnez une nouvelle instance.Use a unique Digital Twins instance name if you're provisioning a new instance.

Définition des conditions à surveillerDefine conditions to monitor

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.You can define a set of specific conditions to monitor in the device or sensor data, called matchers. Vous pouvez ensuite définir des fonctions appelées fonctions définies par l’utilisateur.You can then define functions called user-defined functions. 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.User-defined functions execute custom logic on data that comes from your spaces and devices, when the conditions specified by the matchers occur. Pour plus d’informations, consultez Traitement des données et fonctions définies par l’utilisateur.For more information, read Data processing and user-defined functions.

À partir de l’exemple de projet occupancy-quickstart, ouvrez le fichier src\actions\provisionSample.yaml dans Visual Studio Code.From the occupancy-quickstart sample project, open the file src\actions\provisionSample.yaml in Visual Studio Code. Notez la section qui commence par le type matchers.Note the section that begins with the 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.Each entry under this type creates a matcher with the specified Name. Cet outil de détection supervise un capteur de type dataTypeValue.The matcher will monitor a sensor of 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.Notice how it relates to the space named Focus Room A1, which has a devices node that contains a few sensors. 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.To provision a matcher that will track one of these sensors, make sure that its dataTypeValue matches the sensor's dataType.

Ajoutez le détecteur de problèmes de correspondance suivant sous ceux qui existent déjà.Add the following matcher below the existing matchers. Assurez-vous que les clés sont alignées et que les espaces ne sont pas remplacés par des tabulations.Make sure the keys are aligned and spaces are not replaced by tabs. Ces lignes sont également présentes dans le fichier provisionSample.yaml en tant que lignes commentées.These lines are also present in the provisionSample.yaml file as commented-out lines. Vous pouvez supprimer les marques de commentaire en retirant le caractère # au début de chaque ligne.You can uncomment them by removing the # character in front of each line.

      - 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.This matcher will track the SAMPLE_SENSOR_TEMPERATURE sensor that you added in the first tutorial.

Création d’une fonction définie par l’utilisateurCreate a user-defined function

Vous pouvez utiliser les fonctions définies par l’utilisateur pour personnaliser le traitement de vos données de capteur.You can use user-defined functions to customize the processing of your sensor data. 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.They're custom JavaScript code that can run within your Azure Digital Twins instance, when specific conditions as described by the matchers occur. 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.You can create matchers and user-defined functions for each sensor that you want to monitor. Pour plus d’informations, consultez Traitement des données et fonctions définies par l’utilisateur.For more information, read Data processing and user-defined functions.

Dans l’exemple de fichier provisionSample.yaml, recherchez une section qui commence par le type userdefinedfunctions.In the sample provisionSample.yaml file, look for a section that begins with the type userdefinedfunctions. Cette section configure une fonction définie par l’utilisateur avec un Nom donné.This section provisions a user-defined function with a given Name. 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).This UDF acts on the list of matchers under matcherNames. Notez la façon dont vous pouvez fournir votre propre fichier JavaScript à l’UDF en tant que script.Notice how you can provide your own JavaScript file for the UDF as the script.

Notez également la section nommée roleassignments.Also note the section named roleassignments. Il affecte le rôle d’administrateur de l’espace à la fonction définie par l’utilisateur.It assigns the Space Administrator role to the user-defined function. Ce rôle lui permet d’accéder aux événements qui proviennent d’un des espaces provisionnés.This role allows it to access the events that come from any of the provisioned spaces.

  1. Configurez l’UDF pour inclure le détecteur de problèmes de température en ajoutant ou en supprimant les marques de commentaire de la ligne suivante dans le nœud matcherNames du fichier provisionSample.yaml :Configure the UDF to include the temperature matcher by adding or uncommenting the following line in the matcherNames node of the provisionSample.yaml file:

            - Matcher Temperature
    
  2. Ouvrez le fichier src\actions\userDefinedFunctions\availability.js dans votre éditeur.Open the file src\actions\userDefinedFunctions\availability.js in your editor. Il s’agit du fichier référencé dans l’élément script du fichier provisionSample.yaml.This is the file referenced in the script element of 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.The user-defined function in this file looks for conditions when no motion is detected in the room and carbon dioxide levels are below 1,000 ppm.

    Modifiez le fichier JavaScript pour surveiller la température ainsi que d’autres conditions.Modify the JavaScript file to monitor temperature and other 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).Add the following lines of code to look for conditions when no motion is detected in the room, carbon dioxide levels are below 1,000 ppm, and temperature is below 78 degrees 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.This section modifies the file src\actions\userDefinedFunctions\availability.js so you can learn in detail one way to write a user-defined function. Toutefois, vous pouvez choisir d’utiliser directement le fichier src\actions\userDefinedFunctions\availabilityForTutorial.js dans votre configuration.However, you can choose to directly use the file src\actions\userDefinedFunctions\availabilityForTutorial.js in your setup. Ce fichier contient toutes les modifications requises pour ce didacticiel.This file has all the changes required for this tutorial. 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.If you use this file instead, make sure to use the correct file name for the script key in src\actions\provisionSample.yaml.

    a.a. En haut du fichier, ajoutez les lignes suivantes pour la température en-dessous du commentaire // Add your sensor type here:At the top of the file, add the following lines for temperature below the comment // Add your sensor type here:

        var temperatureType = "Temperature";
        var temperatureThreshold = 78;
    

    b.b. Ajoutez les lignes suivantes après l’instruction qui définit var motionSensor, en-dessous du commentaire // Add your sensor variable here:Add the following lines after the statement that defines var motionSensor, below the comment // Add your sensor variable here:

       var temperatureSensor = otherSensors.find(function(element) {
           return element.DataType === temperatureType;
       });
    

    c.c. Ajoutez la ligne suivante après l’instruction qui définit var carbonDioxideValue, en-dessous du commentaire // Add your sensor latest value here :Add the following line after the statement that defines var carbonDioxideValue, below the comment // Add your sensor latest value here:

        var temperatureValue = getFloatValue(temperatureSensor.Value().Value);
    

    d.d. Supprimez les lignes de code suivantes en dessous du commentaire // Modify this line to monitor your sensor value :Remove the following lines of code from below the comment // 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 :Replace them with the following lines:

        if(carbonDioxideValue === null || motionValue === null || temperatureValue === null){
            sendNotification(telemetry.SensorId, "Sensor", "Error: Carbon dioxide, motion, or temperature are null, returning");
            return;
        }
    

    e.e. Supprimez les lignes de code suivantes en dessous du commentaire // Modify these lines as per your sensor :Remove the following lines of code from below the comment // 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 :Replace them with the following lines:

        var alert = "Room with fresh air and comfortable temperature is available.";
        var noAlert = "Either room is occupied, or working conditions are not right.";
    

    f.f. Supprimez le bloc de code if-else suivant après le commentaire // Modify this code block for your sensor :Remove the following if-else code block after the comment // 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 :And replace it with the following if-else block:

        // 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.The modified UDF will look for a condition where a room becomes available and has the carbon dioxide and temperature within tolerable limits. Il génère une notification avec l’instruction parentSpace.Notify(JSON.stringify(alert)); lorsque cette condition est remplie.It will generate a notification with the statement parentSpace.Notify(JSON.stringify(alert)); when this condition is met. 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.It will set the value of the monitored space regardless of whether the condition is met, with the corresponding message.

    g.g. Enregistrez le fichier .Save the file.

  3. Ouvrez une fenêtre de commande et accédez au dossier occupancy-quickstart\src.Open a command window, and go to the folder occupancy-quickstart\src. Exécutez la commande suivante pour configurer le graphe d’intelligence spatiale et la fonction définie par l’utilisateur :Run the following command to provision your spatial intelligence graph and user-defined function:

    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.To prevent unauthorized access to your Digital Twins Management API, the occupancy-quickstart application requires you to sign in with your Azure account credentials. Elle enregistre vos informations d’identification pour une courte période, afin que vous n’ayez pas besoin de vous connecter à chaque exécution.It saves your credentials for a brief period, so you might not need to sign in every time you run it. 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.The first time this program runs, and when your saved credentials expire after that, the application directs you to a sign-in page and gives a session-specific code to enter on that page. Suivez les instructions de l’invite pour vous connecter avec votre compte Azure.Follow the prompts to sign in with your Azure account.

  4. Une fois votre compte authentifié, l’application commence à créer un exemple de graphe spatial, tel que configuré dans provisionSample.yaml.After your account is authenticated, the application starts creating a sample spatial graph as configured in provisionSample.yaml. Attendez la fin du provisionnement.Wait until the provisioning finishes. Cette opération peut prendre quelques minutes.It will take a few minutes. Examinez ensuite les messages dans la fenêtre de commande et voyez comment votre graphe spatial est créé.After that, observe the messages in the command window and notice how your spatial graph is created. Remarquez la façon dont l’application crée un hub IoT au niveau du nœud racine ou de Venue.Notice how the application creates an IoT hub at the root node or the Venue.

  5. À partir de la sortie dans la fenêtre de commande, copiez la valeur de ConnectionString, sous la section Devices, dans le presse-papiers.From the output in the command window, copy the value of ConnectionString, under the Devices section, to your clipboard. Vous en aurez besoin pour simuler la connexion de l’appareil à la section suivante.You'll need this value to simulate the device connection in the next section.

    Provisionner l’exempleProvision sample

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.If you get an error message similar to "The I/O operation has been aborted because of either a thread exit or an application request" in the middle of the provisioning, try running the command again. Il est possible que le client HTTP ait expiré suite à un problème de réseau.This might happen if the HTTP client timed out from a network issue.

Simulation de données de capteurSimulate sensor data

Dans cette section, vous utilisez le projet nommé device-connectivity dans l’exemple.In this section, you'll use the project named device-connectivity in the sample. Vous simulez des données de capteur pour la détection de mouvement, de température et de dioxyde de carbone.You'll simulate sensor data for detecting motion, temperature, and carbon dioxide. 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.This project generates random values for the sensors, and sends them to the IoT hub by using the device connection string.

  1. Dans une fenêtre de commande distincte, accédez à l’exemple Azure Digital Twins, puis au dossier device-connectivity.In a separate command window, go to the Azure Digital Twins sample and then to the device-connectivity folder.

  2. Exécutez cette commande pour vous assurer que les dépendances du projet sont correctes :Run this command to make sure the dependencies for the project are correct:

    dotnet restore
    
  3. Ouvrez le fichier appsettings.json dans votre éditeur et modifiez les valeurs suivantes :Open the appsettings.json file in your editor, and edit the following values:

    a.a. DeviceConnectionString : affectez la valeur de ConnectionString dans la fenêtre de sortie de la section précédente.DeviceConnectionString: Assign the value of ConnectionString in the output window from the previous section. Copiez cette chaîne entièrement, entre guillemets, pour que le simulateur puisse se connecter correctement au hub IoT.Copy this string completely, within the quotes, so the simulator can connect properly with the IoT hub.

    b.b. HardwareId dans le tableau Sensors : comme vous simulez des événements à partir des capteurs provisionnés dans votre instance Azure Digital Twins, l’ID du matériel et les noms des capteurs contenus dans ce fichier doivent correspondre au nœud sensors du fichier provisionSample.yaml.HardwareId within the Sensors array: Because you're simulating events from sensors provisioned to your Azure Digital Twins instance, the hardware ID and the names of the sensors in this file should match the sensors node of the provisionSample.yaml file.

    Ajoutez une nouvelle entrée pour le capteur de température.Add a new entry for the temperature sensor. Le nœud Sensors (Capteurs) dans le fichier appsettings.json doit se présenter de la façon suivante :The Sensors node in appsettings.json should look like the following:

    "Sensors": [{
      "DataType": "Motion",
      "HardwareId": "SAMPLE_SENSOR_MOTION"
    },{
      "DataType": "CarbonDioxide",
      "HardwareId": "SAMPLE_SENSOR_CARBONDIOXIDE"
    },{
      "DataType": "Temperature",
      "HardwareId": "SAMPLE_SENSOR_TEMPERATURE"
    }]
    
  4. 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 :Run this command to start simulating device events for temperature, motion, and carbon dioxide:

    dotnet run
    

    Notes

    Comme l’exemple de simulation ne communique pas directement avec votre instance Digital Twin, aucune authentification n’est nécessaire.Because the simulation sample does not directly communicate with your Digital Twins instance, it does not require you to authenticate.

Obtention des résultats de la fonction définie par l’utilisateurGet results of the user-defined function

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.The user-defined function runs every time your instance receives device and sensor data. Cette section interroge votre instance Azure Digital Twins afin d’obtenir les résultats de la fonction définie par l’utilisateur.This section queries your Azure Digital Twins instance to get the results of the user-defined function. 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.You'll be notified in near real time, when a room is available, that the air is fresh and temperature is right.

  1. 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.Open the command window that you used to provision the sample, or a new command window, and go to the occupancy-quickstart\src folder of the sample again.

  2. Exécutez la commande suivante et connectez-vous lorsque vous y êtes invité :Run the following command and sign in when prompted:

    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.The output window shows how the user-defined function runs and intercepts events from the device simulation.

Sortie de la fonction définie par l’utilisateurOutput for the UDF

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.If the monitored condition is met, the user-defined function sets the value of the space with the relevant message, as we saw earlier. La fonction GetAvailableAndFreshSpaces affiche le message sur la console.The GetAvailableAndFreshSpaces function prints out the message on the console.

Nettoyer les ressourcesClean up resources

Si vous souhaitez arrêter votre exploration d’Azure Digital Twins ici, vous pouvez supprimer les ressources créées dans ce tutoriel :If you want to stop exploring Azure Digital Twins at this point, feel free to delete resources created in this tutorial:

  1. Dans le menu de gauche du portail Azure, sélectionnez Toutes les ressources, puis votre groupe de ressources Digital Twins et Supprimer.From the left menu in the Azure portal, select All resources, select your Digital Twins resource group, and select Delete.

    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.If you experienced trouble deleting your Digital Twins instance, a service update has been rolled out with the fix. Réessayez de supprimer votre instance.Please retry deleting your instance.

  2. Si nécessaire, supprimez les exemples d’applications de votre machine de travail.If necessary, delete the sample applications on your work machine.

Étapes suivantesNext steps

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 :Now that you have provisioned your spaces and created a framework to trigger custom notifications, you can go to either of the following tutorials: