Samouczek: aprowizuj warunki pracy budynku i monitoruj je za pomocą usługi Azure Digital Twins (wersja zapoznawcza)

Artykuł
01/10/2020

Ważne

Wydano nową wersję usługi Azure Digital Twins. W świetle rozszerzonych możliwości nowej usługi oryginalna usługa Azure Digital Twins (opisana w tym zestawie dokumentacji) została wycofana.

Aby wyświetlić dokumentację nowej usługi, odwiedź aktywną dokumentację usługi Azure Digital Twins.

W tym samouczku pokazano, jak używać usługi Azure Digital Twins w wersji zapoznawczej do monitorowania przestrzeni pod kątem żądanych warunków temperatury i poziomu komfortu. 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.

Ten samouczek zawiera informacje na temat wykonywania następujących czynności:

Definiowanie warunków, które mają być monitorowane.
Tworzenie funkcji zdefiniowanej przez użytkownika (UDF, User Defined Function).
Symulowanie danych z czujników.
Pobieranie wyników funkcji zdefiniowanej przez użytkownika.

Wymagania wstępne

W tym samouczku przyjęto założenie, że ukończono konfigurację usługi Azure Digital Twins. Przed kontynuowaniem upewnij się, że masz:

Konto platformy Azure.
Uruchomione wystąpienie usługi Digital Twins.
Pobrane i wyodrębnione przykłady usługi Digital Twins w języku C# na maszynie roboczej.
Zestaw SDK .NET Core w wersji 2.1.403 lub nowszej na komputerze deweloperskim w celu skompilowania i uruchomienia przykładu. Uruchom polecenie dotnet --version, aby sprawdzić, czy zainstalowano prawidłową wersję.
Program Visual Studio Code umożliwiający eksplorowanie przykładowego kodu.

Porada

Użyj unikatowej nazwy wystąpienia usługi Digital Twins, jeśli aprowizujesz nowe wystąpienie.

Definiowanie warunków, które mają być monitorowane

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. Następnie można zdefiniować funkcje zdefiniowane przez użytkownika. 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. Aby uzyskać więcej informacji, przeczytaj Przetwarzanie danych i funkcje zdefiniowane przez użytkownika.

W przykładowym projekcie occupancy-quickstart otwórz plik src\actions\provisionSample.yaml w programie Visual Studio Code. Zwróć uwagę na sekcję, która zaczyna się od typu matchers. Każdy wpis w ramach tego typu tworzy element matcher z określonym parametrem Name (nazwa). Element matcher będzie monitorował czujnik typu 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. 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.

Dodaj następujący element matcher poniżej istniejących elementów matcher. Upewnij się, że klucze są dopasowane, a spacje nie zostały zastąpione znakami tabulacji. Te wiersze znajdują się również w pliku provisionSample.yaml jako komentarze. Możesz przenieść je poza komentarze, usuwając znak # na początku wiersza.

      - name: Matcher Temperature
        dataTypeValue: Temperature

Ten matcher będzie śledzić SAMPLE_SENSOR_TEMPERATURE czujnik dodany w pierwszym samouczku.

Tworzenie funkcji zdefiniowanej przez użytkownika

Funkcje zdefiniowane przez użytkownika umożliwiają dostosowanie sposobu przetwarzania danych z czujników. 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. Możesz utworzyć elementy matcher i funkcje zdefiniowane przez użytkownika dla każdego czujnika, którego chcesz monitorować. Aby uzyskać więcej informacji, przeczytaj Przetwarzanie danych i funkcje zdefiniowane przez użytkownika.

W przykładowym pliku provisionSample.yaml poszukaj sekcji rozpoczynającej się od typu userdefinedfunctions. Ta sekcja służy do aprowizowania funkcji zdefiniowanej przez użytkownika o określonej wartości parametru Name. Funkcja ta działa na listę elementów matcher wymienionych w sekcji matcherNames. Zauważ, że możesz podać własny plik JavaScript dla funkcji UDF jako skrypt.

Zwróć również uwagę na sekcję o nazwie roleassignments. Służy ona do przypisania roli administratora przestrzeni do funkcji zdefiniowanej przez użytkownika. Ta rola umożliwia funkcji dostęp do zdarzeń przychodzących z dowolnej z aprowizowanych przestrzeni.

Skonfiguruj funkcję UDF, aby uwzględnić dopasowanie temperatury przez dodanie lub usunięcie komentarza następującego wiersza w węźle matcherNames pliku provisionSample.yaml :
```
        - Matcher Temperature
```

Otwórz plik src\actions\userDefinedFunctions\availability.js w edytorze. Jest to plik, do których odwołuje się element skryptuprovisionSample.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.

Zmodyfikuj plik JavaScript, aby monitorować temperaturę oraz inne warunki. 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).

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. Możesz jednak bezpośrednio użyć pliku src\actions\userDefinedFunctions\availabilityForTutorial.js w swojej konfiguracji. Ten plik zawiera wszystkie zmiany, które są wymagane do celów tego samouczka. 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.

a. W górnej części pliku dodaj następujące wiersze dla temperatury pod komentarzem // Add your sensor type here:

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

b. Dodaj następujące wiersze po instrukcji definiującej zmienną var motionSensor pod komentarzem // Add your sensor variable here:

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

c. Dodaj następujący wiersz po instrukcji definiującej zmienną var carbonDioxideValue pod komentarzem // Add your sensor latest value here:

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

d. Usuń następujące wiersze kodu spod komentarza // 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:

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

e. Usuń następujące wiersze kodu spod komentarza // 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:

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

f. Usuń następujące blok kodu if-else po komentarzu // 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:

    // 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. Wygeneruje ona powiadomienie przy użyciu instrukcji parentSpace.Notify(JSON.stringify(alert));, gdy ten warunek zostanie spełniony. Ustawi wartość monitorowanej przestrzeni niezależnie od tego, czy warunek zostanie spełniony, i wyświetli odpowiedni komunikat.

g. Zapisz plik.

Otwórz okno polecenia i przejdź do folderu occupancy-quickstart\src. Uruchom następujące polecenie, aby zaaprowizować wykres analizy przestrzennej i funkcję zdefiniowaną przez użytkownika:
```
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. Zapisuje ona Twoje poświadczenia na pewien okres czasu, aby logowanie nie było konieczne przy każdym uruchomieniu. 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. Postępuj zgodnie z monitami, aby zalogować się na koncie platformy Azure.
Po uwierzytelnieniu konta aplikacja rozpoczyna tworzenie przykładowego grafu przestrzennego zgodnie z konfiguracją w pliku provisionSample.yaml. Poczekaj na ukończenie aprowizowania. Może to potrwać kilka minut. Następnie przyjrzyj się komunikatom w oknie polecenia i spójrz na utworzony wykres przestrzenny. Zauważ, że aplikacja tworzy centrum IoT w węźle głównym lub w lokalizacji Venue.
Z danych wyjściowych w oknie polecenia skopiuj wartość elementu ConnectionString w sekcji Devices do schowka. Ta wartość będzie potrzebna do symulowania połączenia urządzenia w następnej sekcji.

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. Może się to zdarzyć, jeśli klient HTTP przekroczy limit czasu ze względu na problem z siecią.

Symulowanie danych z czujników

W tej sekcji będziesz korzystać z projektu o nazwie device-connectivity w ramach przykładu. Użyjesz go do symulowania danych dotyczących wykrywania ruchu, temperatury i dwutlenku węgla. 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.

W osobnym oknie polecenia przejdź do przykładu usługi Azure Digital Twins, a następnie do folderu device-connectivity.
Uruchom następujące polecenie, aby upewnić się, że zależności dla projektu są prawidłowe:
```
dotnet restore
```
Otwórz plik appsettings.json w edytorze i edytuj następujące wartości:

a. DeviceConnectionString: przypisz wartość ConnectionString w oknie danych wyjściowych z poprzedniej sekcji. Skopiuj cały ciąg między cudzysłowami, aby symulator mógł poprawnie nawiązać połączenie z centrum IoT Hub.

b. HardwareId w tablicy Sensors : Ponieważ symulujesz zdarzenia z czujników aprowizowanych do wystąpienia usługi Azure Digital Twins, identyfikator sprzętu i nazwy czujników w tym pliku powinny być zgodne sensors z węzłem pliku provisionSample.yaml .

Dodaj nowy wpis dla czujnika temperatury. Węzeł Sensors w pliku appsettings.json powinien wyglądać następująco:
```
"Sensors": [{
  "DataType": "Motion",
  "HardwareId": "SAMPLE_SENSOR_MOTION"
},{
  "DataType": "CarbonDioxide",
  "HardwareId": "SAMPLE_SENSOR_CARBONDIOXIDE"
},{
  "DataType": "Temperature",
  "HardwareId": "SAMPLE_SENSOR_TEMPERATURE"
}]
```
Uruchom następujące polecenie, aby rozpocząć symulację zdarzeń urządzeń dotyczących temperatury, ruchu i dwutlenku węgla:
```
dotnet run
```
Uwaga

Ponieważ przykładowa symulacja nie komunikuje się bezpośrednio z wystąpieniem usługi Digital Twins, uwierzytelnianie nie jest konieczne.

Pobieranie wyników funkcji zdefiniowanej przez użytkownika

Funkcja zdefiniowana przez użytkownika jest uruchamiana za każdym razem, gdy wystąpienie odbiera dane z urządzeń i czujników. 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. Otrzymasz powiadomienie w czasie niemal rzeczywistym, gdy pokój jest dostępny, że powietrze jest świeże, a temperatura jest prawidłowa.

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.
Uruchom następujące polecenie i po pojawieniu się monitu zaloguj się:
```
dotnet run GetAvailableAndFreshSpaces
```

W oknie danych wyjściowych będzie widoczne wykonywanie funkcji zdefiniowanej przez użytkownika oraz przechwytywanie zdarzeń z symulacji urządzenia.

W przypadku spełnienia monitorowanego warunku funkcja zdefiniowana przez użytkownika ustawi wartość dla przestrzeni, zwracając odpowiedni komunikat, jak pokazano wyżej. Funkcja GetAvailableAndFreshSpaces wyświetla komunikat w konsoli.

Czyszczenie zasobów

Jeśli nie chcesz kontynuować pracy z usługą Azure Digital Twins, możesz usunąć zasoby utworzone w tym samouczku:

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

Porada

Jeśli podczas usuwania wystąpienia usługi Digital Twins wystąpił problem, została wdrożona aktualizacja usługi zawierająca poprawkę. Ponów próbę usunięcia wystąpienia.
Jeśli będzie to konieczne, możesz usunąć przykładowe aplikacje na komputerze służbowym.

Następne kroki

Teraz po zaaprowizowaniu przestrzeni i utworzeniu platformy do wyzwalania niestandardowych powiadomień możesz przejść do dowolnego z następujących samouczków:

Samouczek: otrzymywanie powiadomień z przestrzeni usługi Azure Digital Twins przy użyciu usługi Logic Apps

Samouczek: wizualizowanie i analizowanie zdarzeń z przestrzeni usługi Azure Digital Twins przy użyciu usługi Time Series Insights