Samouczek: udostępnianie warunków roboczych tworzenia i monitorowania za pomocą usługi Azure Digital bliźniaczych reprezentacji PreviewTutorial: Provision your building and monitor working conditions with Azure Digital Twins Preview

W tym samouczku pokazano, jak używać usługi Azure Digital bliźniaczych reprezentacji Preview do monitorowania obszarów pod kątem wymagań dotyczących temperatury i poziomu komfortu.This tutorial demonstrates how to use Azure Digital Twins Preview to monitor your spaces for desired temperature conditions and comfort level. Po skonfigurowaniu przykładowego budynku możesz zaaprowizować swój budynek i uruchamiać funkcje niestandardowe na danych z czujników, wykonując czynności opisane w tym samouczki.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.

Niniejszy samouczek zawiera informacje na temat wykonywania następujących czynności:In this tutorial, you learn how to:

  • Definiowanie warunków, które mają być monitorowane.Define conditions to monitor.
  • Tworzenie funkcji zdefiniowanej przez użytkownika (UDF, User Defined Function).Create a user-defined function (UDF).
  • Symulowanie danych z czujników.Simulate sensor data.
  • Pobieranie wyników funkcji zdefiniowanej przez użytkownika.Get results of a user-defined function.

Wymagania wstępnePrerequisites

W tym samouczku przyjęto założenie, że ukończono konfigurację usługi Azure Digital Twins.This tutorial assumes that you have finished your Azure Digital Twins setup. Przed kontynuowaniem upewnij się, że masz:Before proceeding, make sure that you have:

Porada

Jeśli zainicjowano nowe wystąpienie, użyj unikatowej nazwy wystąpienia bliźniaczych reprezentacji Digital.Use a unique Digital Twins instance name if you're provisioning a new instance.

Definiowanie warunków, które mają być monitorowaneDefine conditions to monitor

Możesz zdefiniować zestaw określonych warunków nazywanych elementami matcher, które mają być monitorowane w urządzeniu lub w danych z czujników.You can define a set of specific conditions to monitor in the device or sensor data, called matchers. Następnie można zdefiniować funkcje zdefiniowane przez użytkownika.You can then define functions called user-defined functions. Funkcje zdefiniowane przez użytkownika umożliwiają wykonywanie niestandardowej logiki na danych pochodzących z przestrzeni i urządzeń, gdy wystąpią warunki określone w elementach matcher.User-defined functions execute custom logic on data that comes from your spaces and devices, when the conditions specified by the matchers occur. Aby uzyskać więcej informacji, przeczytaj Przetwarzanie danych i funkcje zdefiniowane przez użytkownika.For more information, read Data processing and user-defined functions.

W przykładowym projekcie occupancy-quickstart otwórz plik src\actions\provisionSample.yaml w programie Visual Studio Code.From the occupancy-quickstart sample project, open the file src\actions\provisionSample.yaml in Visual Studio Code. Zwróć uwagę na sekcję, która zaczyna się od typu matchers.Note the section that begins with the type matchers. Każdy wpis w ramach tego typu tworzy element matcher z określonym parametrem Name (nazwa).Each entry under this type creates a matcher with the specified Name. Element matcher będzie monitorował czujnik typu dataTypeValue.The matcher will monitor a sensor of type dataTypeValue. Zwróć uwagę, że jest on związany z przestrzenią o nazwie Focus Room A1, w której znajduje się węzeł devices zawierający kilka czujników.Notice how it relates to the space named Focus Room A1, which has a devices node that contains a few sensors. Aby aprowizować element matcher, który będzie śledzić jeden z tych czujników, należy upewnić się, że jego typ dataTypeValue jest zgodny z typem dataType czujnika.To provision a matcher that will track one of these sensors, make sure that its dataTypeValue matches the sensor's dataType.

Dodaj następujący element matcher poniżej istniejących elementów matcher.Add the following matcher below the existing matchers. Upewnij się, że klucze są dopasowane, a spacje nie zostały zastąpione znakami tabulacji.Make sure the keys are aligned and spaces are not replaced by tabs. Te wiersze znajdują się również w pliku provisionSample.yaml jako komentarze.These lines are also present in the provisionSample.yaml file as commented-out lines. Możesz przenieść je poza komentarze, usuwając znak # na początku wiersza.You can uncomment them by removing the # character in front of each line.

      - name: Matcher Temperature
        dataTypeValue: Temperature

Ten dopasowany element będzie śledził czujnik SAMPLE_SENSOR_TEMPERATURE, który został dodany w pierwszym samouczku.This matcher will track the SAMPLE_SENSOR_TEMPERATURE sensor that you added in the first tutorial.

Tworzenie funkcji zdefiniowanej przez użytkownikaCreate a user-defined function

Funkcje zdefiniowane przez użytkownika umożliwiają dostosowanie sposobu przetwarzania danych z czujników.You can use user-defined functions to customize the processing of your sensor data. Są one niestandardowym kodem JavaScript, który można uruchamiać w ramach wystąpienia usługi Azure Digital Twins, gdy wystąpią warunki określone w elementach matcher.They're custom JavaScript code that can run within your Azure Digital Twins instance, when specific conditions as described by the matchers occur. Możesz utworzyć elementy matcher i funkcje zdefiniowane przez użytkownika dla każdego czujnika, którego chcesz monitorować.You can create matchers and user-defined functions for each sensor that you want to monitor. Aby uzyskać więcej informacji, przeczytaj Przetwarzanie danych i funkcje zdefiniowane przez użytkownika.For more information, read Data processing and user-defined functions.

W przykładowym pliku provisionSample. YAML odszukaj sekcję rozpoczynającą się od typu UserDefinedFunctions.In the sample provisionSample.yaml file, look for a section that begins with the type userdefinedfunctions. Ta sekcja służy do aprowizowania funkcji zdefiniowanej przez użytkownika o określonej wartości parametru Name.This section provisions a user-defined function with a given Name. Funkcja ta działa na listę elementów matcher wymienionych w sekcji matcherNames.This UDF acts on the list of matchers under matcherNames. Zauważ, że możesz podać własny plik JavaScript dla funkcji UDF jako skrypt.Notice how you can provide your own JavaScript file for the UDF as the script.

Zwróć również uwagę na sekcję o nazwie roleassignments.Also note the section named roleassignments. Służy ona do przypisania roli administratora przestrzeni do funkcji zdefiniowanej przez użytkownika.It assigns the Space Administrator role to the user-defined function. Ta rola umożliwia funkcji dostęp do zdarzeń przychodzących z dowolnej z aprowizowanych przestrzeni.This role allows it to access the events that come from any of the provisioned spaces.

  1. Skonfiguruj funkcję UDF, aby zawierała element matcher temperatury, dodając następujący wiersz matcherNames (lub usuwając komentarz) w węźle pliku 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. Otwórz plik src\actions\userDefinedFunctions\availability.js w edytorze.Open the file src\actions\userDefinedFunctions\availability.js in your editor. Jest to plik, do którego odwołuje się element skryptu provisionSample. YAML.This is the file referenced in the script element of provisionSample.yaml. Funkcja zdefiniowana przez użytkownika w tym pliku wyszukuje warunki, gdy w pomieszczeniu nie jest wykrywany ruch, a poziom dwutlenku węgla jest niższy niż 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.

    Zmodyfikuj plik JavaScript, aby monitorować temperaturę oraz inne warunki.Modify the JavaScript file to monitor temperature and other conditions. Dodaj następujące wiersze kodu, aby wyszukiwać warunki, gdy w pomieszczeniu nie jest wykrywany ruch, poziom dwutlenku węgla jest niższy niż 1,000 ppm, a temperatura jest niższa niż 78 stopni Fehrenheita (25,5 stopnia Celsjusza).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.

    Uwaga

    W tej sekcji zostanie zmodyfikowany plik src\actions\userDefinedFunctions\availability.js, aby umożliwić Ci szczegółowe poznanie jednego ze sposobów pisania funkcji zdefiniowanej przez użytkownika.This section modifies the file src\actions\userDefinedFunctions\availability.js so you can learn in detail one way to write a user-defined function. Możesz jednak bezpośrednio użyć pliku src\actions\userDefinedFunctions\availabilityForTutorial.js w swojej konfiguracji.However, you can choose to directly use the file src\actions\userDefinedFunctions\availabilityForTutorial.js in your setup. Ten plik zawiera wszystkie zmiany, które są wymagane do celów tego samouczka.This file has all the changes required for this tutorial. Jeśli w zamian użyjesz tego pliku, pamiętaj, aby użyć prawidłowej nazwy pliku dla klucza script w pliku 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. W górnej części pliku dodaj następujące wiersze dla temperatury pod komentarzem // 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. Dodaj następujące wiersze po instrukcji definiującej zmienną var motionSensor pod komentarzem // 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;
       });
    

    d.c. Dodaj następujący wiersz po instrukcji definiującej zmienną var carbonDioxideValue pod komentarzem // 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. Usuń następujące wiersze kodu spod komentarza // 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;
       }
    

    Zastąp je z następującymi wierszami: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. Usuń następujące wiersze kodu spod komentarza // 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";
    

    Zastąp je z następującymi wierszami: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. Usuń następujące blok kodu if-else po komentarzu // 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));
        }
    

    Zastąp go następującym blokiem if-else: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);
        }
    

    Zmodyfikowana funkcja UDF będzie wyszukiwała warunek, w którym pomieszczenie jest dostępne, a poziom dwutlenku węgla i temperatura mieszczą się w dopuszczalnych limitach.The modified UDF will look for a condition where a room becomes available and has the carbon dioxide and temperature within tolerable limits. Wygeneruje ona powiadomienie przy użyciu instrukcji parentSpace.Notify(JSON.stringify(alert));, gdy ten warunek zostanie spełniony.It will generate a notification with the statement parentSpace.Notify(JSON.stringify(alert)); when this condition is met. Ustawi wartość monitorowanej przestrzeni niezależnie od tego, czy warunek zostanie spełniony, i wyświetli odpowiedni komunikat.It will set the value of the monitored space regardless of whether the condition is met, with the corresponding message.

    g.g. Zapisz plik.Save the file.

  3. Otwórz okno polecenia i przejdź do folderu occupancy-quickstart\src.Open a command window, and go to the folder occupancy-quickstart\src. Uruchom następujące polecenie, aby zaaprowizować wykres analizy przestrzennej i funkcję zdefiniowaną przez użytkownika:Run the following command to provision your spatial intelligence graph and user-defined function:

    dotnet run ProvisionSample
    

    Ważne

    Aby uniemożliwić nieautoryzowany dostęp do interfejsu API zarządzania usługą Digital Twins, aplikacja occupancy-quickstart wymaga zalogowania się przy użyciu poświadczeń konta platformy 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. Zapisuje ona Twoje poświadczenia na pewien okres czasu, aby logowanie nie było konieczne przy każdym uruchomieniu.It saves your credentials for a brief period, so you might not need to sign in every time you run it. Przy pierwszym uruchomieniu tego programu, a także po wygaśnięciu zapisanych poświadczeń, aplikacja przekieruje Cię do strony logowania i poda kod specyficzny dla sesji, który należy wprowadzić na tej stronie.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. Postępuj zgodnie z monitami, aby zalogować się na koncie platformy Azure.Follow the prompts to sign in with your Azure account.

  4. Po uwierzytelnieniu konta aplikacja rozpocznie Tworzenie przykładowego wykresu przestrzennego zgodnie z konfiguracją w provisionSample. YAML.After your account is authenticated, the application starts creating a sample spatial graph as configured in provisionSample.yaml. Poczekaj na ukończenie aprowizowania.Wait until the provisioning finishes. Może to potrwać kilka minut.It will take a few minutes. Następnie przyjrzyj się komunikatom w oknie polecenia i spójrz na utworzony wykres przestrzenny.After that, observe the messages in the command window and notice how your spatial graph is created. Zauważ, że aplikacja tworzy centrum IoT w węźle głównym lub w lokalizacji Venue.Notice how the application creates an IoT hub at the root node or the Venue.

  5. Z danych wyjściowych w oknie polecenia skopiuj wartość elementu ConnectionString w sekcji Devices do schowka.From the output in the command window, copy the value of ConnectionString, under the Devices section, to your clipboard. Ta wartość będzie potrzebna do symulowania połączenia urządzenia w następnej sekcji.You'll need this value to simulate the device connection in the next section.

    przykład udostępniania Provision sample

Porada

Jeśli podczas aprowizowania zostanie wyświetlony komunikat podobny do następującego „Operacja We/Wy została przerwana z powodu zakończenia wątku lub żądania aplikacji”, spróbuj ponownie uruchomić polecenie.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. Może się to zdarzyć, jeśli klient HTTP przekroczy limit czasu ze względu na problem z siecią.This might happen if the HTTP client timed out from a network issue.

Symulowanie danych z czujnikówSimulate sensor data

W tej sekcji będziesz korzystać z projektu o nazwie device-connectivity w ramach przykładu.In this section, you'll use the project named device-connectivity in the sample. Użyjesz go do symulowania danych dotyczących wykrywania ruchu, temperatury i dwutlenku węgla.You'll simulate sensor data for detecting motion, temperature, and carbon dioxide. Ten projekt generuje losowe wartości dla czujników i wysyła je do centrum IoT przy użyciu parametrów połączenia urządzenia.This project generates random values for the sensors, and sends them to the IoT hub by using the device connection string.

  1. W osobnym oknie polecenia przejdź do przykładu usługi Azure Digital Twins, a następnie do folderu device-connectivity.In a separate command window, go to the Azure Digital Twins sample and then to the device-connectivity folder.

  2. Uruchom następujące polecenie, aby upewnić się, że zależności dla projektu są prawidłowe:Run this command to make sure the dependencies for the project are correct:

    dotnet restore
    
  3. Otwórz plik appsettings.json w edytorze i zmodyfikuj następujące wartości:Open the appsettings.json file in your editor, and edit the following values:

    a.a. DeviceConnectionString: przypisz wartość ConnectionString w oknie danych wyjściowych z poprzedniej sekcji.DeviceConnectionString: Assign the value of ConnectionString in the output window from the previous section. Skopiuj cały ciąg między cudzysłowami, aby symulator mógł poprawnie nawiązać połączenie z centrum IoT Hub.Copy this string completely, within the quotes, so the simulator can connect properly with the IoT hub.

    b.b. HardwareId w tablicy czujników : ponieważ symulujesz zdarzenia z czujników, które są obsługiwane w wystąpieniu usługi Azure Digital bliźniaczych reprezentacji, identyfikator sprzętu i nazwy czujników w tym pliku powinny być zgodne z węzłem sensors pliku 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.

    Dodaj nowy wpis dla czujnika temperatury.Add a new entry for the temperature sensor. Węzeł czujników w pliku appSettings. JSON powinien wyglądać następująco: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. Uruchom następujące polecenie, aby rozpocząć symulację zdarzeń urządzeń dotyczących temperatury, ruchu i dwutlenku węgla:Run this command to start simulating device events for temperature, motion, and carbon dioxide:

    dotnet run
    

    Uwaga

    Ponieważ przykładowa symulacja nie komunikuje się bezpośrednio z wystąpieniem usługi Digital Twins, uwierzytelnianie nie jest konieczne.Because the simulation sample does not directly communicate with your Digital Twins instance, it does not require you to authenticate.

Pobieranie wyników funkcji zdefiniowanej przez użytkownikaGet results of the user-defined function

Funkcja zdefiniowana przez użytkownika jest uruchamiana za każdym razem, gdy wystąpienie odbiera dane z urządzeń i czujników.The user-defined function runs every time your instance receives device and sensor data. W tej sekcji jest wykonywane zapytanie względem wystąpienia usługi Azure Digital Twins w celu uzyskania wyników funkcji zdefiniowanej przez użytkownika.This section queries your Azure Digital Twins instance to get the results of the user-defined function. Użytkownik zostanie powiadomiony o niemal czasie rzeczywistym, gdy będzie dostępny pokój, że powietrze jest świeże i temperatura jest odpowiednia.You'll be notified in near real time, when a room is available, that the air is fresh and temperature is right.

  1. Otwórz okno polecenia, którego użyto do aprowizacji przykładu, lub nowe okno polecenia i ponownie przejdź do folderu occupancy-quickstart\src w przykładzie.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. Uruchom następujące polecenie i po pojawieniu się monitu zaloguj się:Run the following command and sign in when prompted:

    dotnet run GetAvailableAndFreshSpaces
    

W oknie danych wyjściowych będzie widoczne wykonywanie funkcji zdefiniowanej przez użytkownika oraz przechwytywanie zdarzeń z symulacji urządzenia.The output window shows how the user-defined function runs and intercepts events from the device simulation.

Dane wyjściowe dla UDFOutput for the UDF

W przypadku spełnienia monitorowanego warunku funkcja zdefiniowana przez użytkownika ustawi wartość dla przestrzeni, zwracając odpowiedni komunikat, jak pokazano wyżej.If the monitored condition is met, the user-defined function sets the value of the space with the relevant message, as we saw earlier. Funkcja GetAvailableAndFreshSpaces wyświetla komunikat w konsoli.The GetAvailableAndFreshSpaces function prints out the message on the console.

Oczyszczanie zasobówClean up resources

Jeśli nie chcesz kontynuować pracy z usługą Azure Digital Twins, możesz usunąć zasoby utworzone w tym samouczku:If you want to stop exploring Azure Digital Twins at this point, feel free to delete resources created in this tutorial:

  1. W menu po lewej stronie w witrynie Azure Portal wybierz przycisk Wszystkie zasoby, wybierz grupę zasobów usługi Digital Twins i wybierz polecenie Usuń.From the left menu in the Azure portal, select All resources, select your Digital Twins resource group, and select Delete.

    Porada

    Jeśli podczas usuwania wystąpienia usługi Digital Twins wystąpił problem, została wdrożona aktualizacja usługi zawierająca poprawkę.If you experienced trouble deleting your Digital Twins instance, a service update has been rolled out with the fix. Ponów próbę usunięcia wystąpienia.Please retry deleting your instance.

  2. Jeśli będzie to konieczne, możesz usunąć przykładowe aplikacje na komputerze służbowym.If necessary, delete the sample applications on your work machine.

Następne krokiNext steps

Teraz po zaaprowizowaniu przestrzeni i utworzeniu platformy do wyzwalania niestandardowych powiadomień możesz przejść do dowolnego z następujących samouczków:Now that you have provisioned your spaces and created a framework to trigger custom notifications, you can go to either of the following tutorials: