Samouczek: tworzenie grafu usługi Azure Digital Twins przy użyciu przykładowej aplikacji klienckiej

• Przykładowa aplikacja kliencka
• Interfejs wiersza polecenia

W tym samouczku utworzysz graf w usłudze Azure Digital Twins przy użyciu modeli, reprezentacji bliźniaczych i relacji. Narzędzie do tego samouczka to przykładowa aplikacja kliencka wiersza polecenia do interakcji z wystąpieniem usługi Azure Digital Twins. Aplikacja kliencka jest podobna do aplikacji klienckiej napisanej w kodzie.

Ten przykład umożliwia wykonywanie podstawowych akcji usługi Azure Digital Twins, takich jak przekazywanie modeli, tworzenie i modyfikowanie reprezentacji bliźniaczych oraz tworzenie relacji. Możesz również zapoznać się z kodem przykładu , aby dowiedzieć się więcej na temat interfejsów API usługi Azure Digital Twins i ćwiczyć implementowanie własnych poleceń, modyfikując przykładowy projekt, jednak chcesz.

W tym samouczku wykonasz...

• Modelowanie środowiska
• Tworzenie cyfrowych reprezentacji bliźniaczych
• Dodawanie relacji w celu utworzenia grafu
• Wykonywanie zapytań względem grafu w celu udzielenia odpowiedzi na pytania

Wymagania wstępne

Przed rozpoczęciem tego samouczka zacznij od następujących wymagań wstępnych:

• Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
• W tym samouczku jest używana platforma .NET. Najnowszą wersję zestawu .NET SDK dla wielu platform można pobrać z witryny Pobierz platformę .NET.

Następnie przejdź do pozostałej części tej sekcji, aby skonfigurować pozostałe wymagania wstępne.

Pobieranie przykładowych zasobów

Samouczek jest oparty na kompleksowej wersji przykładowego projektu usługi Azure Digital Twins napisanego w języku C#. Pobierz przykładowy projekt na maszynie, przechodząc do przykładowego linku i wybierając przycisk Przeglądaj kod pod tytułem.

Spowoduje to przejście do repozytorium GitHub dla przykładów, które można pobrać jako plik zip, wybierając przycisk Kod , a następnie pobierz plik ZIP.

Spowoduje to pobranie folderu zip na maszynę jako digital-twins-samples-main.zip. Rozpakuj folder i wyodrębnij pliki.

Przygotowywanie wystąpienia usługi Azure Digital Twins

Aby pracować z usługą Azure Digital Twins w tym artykule, musisz mieć wystąpienie usługi Azure Digital Twins i wymagane uprawnienia do korzystania z niego. Jeśli masz już skonfigurowane wystąpienie usługi Azure Digital Twins, możesz użyć tego wystąpienia i przejść do następnej sekcji. W przeciwnym razie postępuj zgodnie z instrukcjami w temacie Konfigurowanie wystąpienia i uwierzytelniania. Instrukcje zawierają informacje ułatwiające sprawdzenie, czy każdy krok został ukończony pomyślnie.

Po skonfigurowaniu wystąpienia zanotuj nazwę hosta wystąpienia. Nazwę hosta można znaleźć w witrynie Azure Portal.

Konfigurowanie przykładowego projektu

Następnie skonfiguruj przykładową aplikację kliencką, która będzie współdziałać z wystąpieniem usługi Azure Digital Twins.

Przejdź na maszynę do folderu pobranego wcześniej z przykładów usługi Azure Digital Twins (i rozpakuj go, jeśli jeszcze tego nie zrobiono).

W folderze przejdź do folderu digital-twins-samples-main\AdtSampleApp\SampleClientApp i otwórz plik appsettings.json . Ten plik JSON zawiera zmienną konfiguracji, która jest niezbędna do uruchomienia projektu.

W treści pliku zmień instanceUrl wartość na adres URL nazwy hosta wystąpienia usługi Azure Digital Twins (dodając https:// przed nazwą hosta, jak pokazano poniżej).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Zapisz i zamknij plik.

Konfigurowanie lokalnych poświadczeń platformy Azure

W tym przykładzie użyto wartości DefaultAzureCredential (część Azure.Identity biblioteki) do uwierzytelniania użytkowników przy użyciu wystąpienia usługi Azure Digital Twins podczas uruchamiania go na komputerze lokalnym. Aby uzyskać więcej informacji na temat różnych sposobów uwierzytelniania aplikacji klienckiej za pomocą usługi Azure Digital Twins, zobacz Pisanie kodu uwierzytelniania aplikacji.

W programie DefaultAzureCredentialprzykład wyszuka poświadczenia w środowisku lokalnym, takie jak logowanie się platformy Azure w lokalnym interfejsie wiersza polecenia platformy Azure lub w programie Visual Studio lub Visual Studio Code. Z tego powodu należy zalogować się do platformy Azure lokalnie za pomocą jednego z tych mechanizmów, aby skonfigurować poświadczenia dla przykładu.

Jeśli używasz programu Visual Studio lub Visual Studio Code do uruchamiania przykładów kodu, upewnij się, że zalogowaliśmy się do tego edytora przy użyciu tych samych poświadczeń platformy Azure, których chcesz użyć do uzyskania dostępu do wystąpienia usługi Azure Digital Twins. Jeśli używasz lokalnego okna interfejsu wiersza polecenia, uruchom az login polecenie , aby zalogować się do konta platformy Azure. Następnie po uruchomieniu przykładowego kodu powinno nastąpić automatyczne uwierzytelnienie.

Uruchamianie przykładowego projektu

Po skonfigurowaniu aplikacji i uwierzytelniania otwórz okno konsoli lokalnej, którego użyjesz do uruchomienia projektu. Przejdź w konsoli do folderu digital-twins-samples-main\AdtSampleApp\SampleClientApp i uruchom projekt za pomocą następującego polecenia dotnet:

dotnet run

Projekt rozpocznie działanie, przeprowadzi uwierzytelnianie i zaczeka na polecenie.

Oto zrzut ekranu przedstawiający wygląd konsoli projektu:

Napiwek

Aby uzyskać listę wszystkich możliwych poleceń, których można użyć w tym projekcie, wprowadź help w konsoli projektu i naciśnij klawisz Return.

Po pomyślnym potwierdzeniu, że aplikacja jest uruchomiona, możesz zatrzymać uruchamianie projektu. Uruchomisz go ponownie później w samouczku.

Modelowanie środowiska fizycznego przy użyciu języka DTDL

Teraz, po skonfigurowaniu wystąpienia usługi Azure Digital Twins i przykładowej aplikacji, możesz rozpocząć tworzenie grafu scenariusza.

Pierwszym krokiem tworzenia rozwiązania usługi Azure Digital Twins jest definiowanie modeli bliźniaczych reprezentacji dla danego środowiska.

Modele są podobne do klas w językach programowania obiektowego; są szablonami zdefiniowanymi przez użytkownika, które można utworzyć w celu utworzenia cyfrowych reprezentacji bliźniaczych. Modele dla usługi Azure Digital Twins są pisane w języku przypominającym kod JSON o nazwie Digital Twins Definition Language (DTDL) i definiują typ bliźniaczej reprezentacji pod względem jego właściwości, relacji i składników.

Uwaga

Język DTDL umożliwia również definiowanie poleceń w cyfrowych reprezentacjach bliźniaczych. Jednak polecenia nie są obecnie obsługiwane w usłudze Azure Digital Twins.

W pobranym wcześniej folderze przykładowego projektu przejdź do folderu digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models . Ten folder zawiera przykładowe modele.

Otwórz plik Room.json do edycji i wprowadź następujące zmiany w kodzie:

1. Zaktualizuj numer wersji, aby wskazać, że udostępniasz bardziej zaktualizowaną wersję tego modelu. Zrób to, zmieniając wartość 1 na końcu @id wartości na 2. Każda liczba większa niż bieżący numer wersji również będzie działać.

2. Edytuj właściwość. Zmień nazwę Humidity właściwości na HumidityLevel (lub coś innego, jeśli chcesz. Jeśli używasz czegoś innego niż HumidityLevel, pamiętaj, co zostało użyte i nadal używasz tego elementu zamiast humidityLevel w całym samouczku.

3. Dodaj właściwość. Poniżej właściwości kończącej HumidityLevel się w wierszu 15 wklej następujący kod, aby dodać RoomName właściwość do pokoju:

   ,{
     "@type": "Property",
     "name": "RoomName",
     "schema": "string"
   }
   

4. Dodaj relację. Poniżej właśnie dodanej RoomName właściwości wklej następujący kod, aby dodać możliwość tworzenia contains relacji bliźniaczych z innymi reprezentacjami bliźniaczymi:

   ,{
     "@type": "Relationship",
     "name": "contains"
   }
   

Po zakończeniu zaktualizowany model powinien być zgodny z następującymi elementami:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Przed przejściem upewnij się, że plik został zapisany.

Przekazywanie modeli do usługi Azure Digital Twins

Po zaprojektowaniu modeli należy przekazać je do wystąpienia usługi Azure Digital Twins. W ten sposób skonfiguruje wystąpienie usługi Azure Digital Twins przy użyciu własnego niestandardowego słownictwa domeny. Po przekazaniu modeli możesz utworzyć wystąpienia bliźniaczych reprezentacji, które ich używają.

1. Wróć do okna konsoli, które jest otwarte w folderze digital-twins-samples-main\AdtSampleApp\SampleClientApp , a następnie ponownie uruchom aplikację konsolową za pomocą polecenia dotnet run.

2. W oknie konsoli projektu uruchom następujące polecenie, aby przekazać zaktualizowany model pokoju wraz z modelem Floor, który będzie również używany w następnej sekcji, aby utworzyć różne typy reprezentacji bliźniaczych.

   CreateModels Room Floor
   

   Dane wyjściowe powinny wskazywać, że modele zostały utworzone pomyślnie.

3. Sprawdź, czy modele zostały utworzone, uruchamiając polecenie GetModels true. To polecenie wyświetli pełne informacje dotyczące wszystkich modeli przekazanych do wystąpienia usługi Azure Digital Twins. Wyszukaj edytowany model pokoju w wynikach:

   

Zachowaj uruchomioną aplikację konsolową, aby wykonać następne kroki.

Błędy

Przykładowa aplikacja obsługuje również błędy z usługi.

Aby to przetestować, uruchom CreateModels ponownie polecenie , aby spróbować ponownie przekazać model Pokoju, który został już przekazany:

CreateModels Room

Ponieważ nie można zastąpić modeli, to polecenie zwróci teraz błąd usługi wskazujący, że niektóre identyfikatory modeli, które próbujesz utworzyć, już istnieją.

Aby uzyskać szczegółowe informacje na temat usuwania istniejących modeli, zobacz Zarządzanie modelami DTDL.

Tworzenie cyfrowych reprezentacji bliźniaczych

Teraz, gdy niektóre modele zostały przekazane do wystąpienia usługi Azure Digital Twins, możesz utworzyć cyfrowe reprezentacje bliźniacze na podstawie definicji modelu. Cyfrowe reprezentacje bliźniacze reprezentują jednostki w środowisku biznesowym — takie jak czujniki na farmie, pokoje w budynku lub światła w samochodzie.

Aby utworzyć cyfrową reprezentację bliźniaczą, użyj CreateDigitalTwin polecenia . Musisz odwołać się do modelu opartego na bliźniaczej reprezentacji i opcjonalnie zdefiniować początkowe wartości dla dowolnych właściwości w modelu. Na tym etapie nie trzeba przekazywać żadnych informacji o relacji.

1. Uruchom ten kod w uruchomionej konsoli projektu, aby utworzyć kilka reprezentacji bliźniaczych na podstawie zaktualizowanego wcześniej modelu Pokój i innego modelu Floor. Pamiętaj, że pokój ma trzy właściwości, więc można podać argumenty z początkowymi wartościami dla tych właściwości. (Inicjowanie wartości właściwości jest opcjonalne ogólnie, ale są one wymagane w tym samouczku).

   CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
   CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
   CreateDigitalTwin dtmi:example:Floor;1 floor0
   CreateDigitalTwin dtmi:example:Floor;1 floor1
   

   Dane wyjściowe z tych poleceń powinny wskazywać, że bliźniacze reprezentacje zostały utworzone pomyślnie.

   

2. Możesz sprawdzić, czy bliźniacze reprezentacje zostały utworzone, uruchamiając Query polecenie . To polecenie wysyła zapytanie do wystąpienia usługi Azure Digital Twins dla wszystkich zawartych w nim cyfrowych reprezentacji bliźniaczych. Poszukaj w wynikach bliźniaczych reprezentacji bliźniaczych room0, room1, floor0 i floor1.

Uwaga

Po wprowadzeniu zmiany danych na grafie może wystąpić opóźnienie do 10 sekund, zanim zmiany zostaną odzwierciedlone w zapytaniach.

Interfejs API DigitalTwins odzwierciedla zmiany natychmiast, więc jeśli potrzebujesz natychmiastowej odpowiedzi, użyj żądania interfejsu API (DigitalTwins GetById) lub wywołania zestawu SDK (GetDigitalTwin), aby pobrać dane bliźniaczej reprezentacji zamiast zapytania.

Modyfikowanie cyfrowej reprezentacji bliźniaczej

Możesz również zmodyfikować właściwości utworzonej reprezentacji bliźniaczej.

Uwaga

Podstawowy interfejs API REST używa formatu poprawki JSON do definiowania aktualizacji bliźniaczej reprezentacji. Aplikacja wiersza polecenia używa również tego formatu, aby zapewnić środowisko truer z oczekiwanymi podstawowymi interfejsami API.

1. Uruchom to polecenie, aby zmienić room0's RoomName z "Room0" na "PresidentialSuite":

   UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
   

   Dane wyjściowe powinny wskazywać, że bliźniacy reprezentacja została pomyślnie zaktualizowana.

2. Możesz sprawdzić, czy aktualizacja zakończyła się pomyślnie, uruchamiając to polecenie, aby wyświetlić informacje o pokoju0:

   GetDigitalTwin room0
   

   Dane wyjściowe powinny odzwierciedlać zaktualizowaną nazwę.

Tworzenie grafu przez dodawanie relacji

Następnie możesz utworzyć relacje między tymi bliźniaczymi reprezentacjami, aby połączyć je z grafem bliźniaczych reprezentacji. Wykresy bliźniaczych reprezentacji są używane do reprezentowania całego środowiska.

Typy relacji, które można utworzyć z jednej reprezentacji bliźniaczej do drugiej, są definiowane we wcześniej przekazanych modelach . Definicja modelu dla floor określa, że podłogi mogą mieć typ relacji o nazwie contains, co umożliwia utworzenie containsrelacji typu -type z każdego bliźniaczej reprezentacji piętro do odpowiedniego pokoju, który zawiera.

Aby dodać relację, użyj CreateRelationship polecenia . Określ bliźniacze reprezentację, z którą pochodzi relacja, typ relacji i bliźniacze, z którą łączy się relacja. Na koniec nadaj relacji unikatowy identyfikator.

1. Uruchom następujące polecenia, aby dodać relację contains z każdej utworzonej wcześniej reprezentacji bliźniaczej Floor do odpowiedniej reprezentacji bliźniaczej pokoju. Relacje mają nazwę relationship0 i relationship1.

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   Napiwek

   Relacja contains w modelu Floor została również zdefiniowana z dwiema właściwościami ciągu i ownershipDepartmentownershipUser , dzięki czemu można również podać argumenty z początkowymi wartościami dla nich podczas tworzenia relacji. Oto alternatywna wersja powyższego polecenia, aby utworzyć relację0, która określa również wartości początkowe dla tych właściwości:

   CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
   

   Dane wyjściowe z tych poleceń potwierdzają, że relacje zostały utworzone pomyślnie:

   

2. Relacje można zweryfikować przy użyciu dowolnego z poniższych poleceń, które będą wyświetlać relacje w wystąpieniu usługi Azure Digital Twins.

   • Aby wyświetlić wszystkie relacje wychodzące z każdego piętra (wyświetlanie relacji z jednej strony):

     GetRelationships floor0
     GetRelationships floor1
     

   • Aby wyświetlić wszystkie relacje przychodzące do każdego pokoju (wyświetlanie relacji z "drugiej" strony):

     GetIncomingRelationships room0
     GetIncomingRelationships room1
     

   • Aby wyszukać te relacje indywidualnie, według identyfikatora:

     GetRelationship floor0 relationship0
     GetRelationship floor1 relationship1
     

Bliźniacze i relacje skonfigurowane w tym samouczku tworzą następujący graf koncepcyjny:

Wykonywanie zapytań względem grafu bliźniaczej reprezentacji w celu udzielenia odpowiedzi na pytania dotyczące środowiska

Główną funkcją usługi Azure Digital Twins jest możliwość łatwego i wydajnego wykonywania zapytań względem grafu bliźniaczej reprezentacji w celu odpowiadania na pytania dotyczące środowiska.

Uwaga

Po wprowadzeniu zmiany danych na grafie może wystąpić opóźnienie do 10 sekund, zanim zmiany zostaną odzwierciedlone w zapytaniach.

Interfejs API DigitalTwins odzwierciedla zmiany natychmiast, więc jeśli potrzebujesz natychmiastowej odpowiedzi, użyj żądania interfejsu API (DigitalTwins GetById) lub wywołania zestawu SDK (GetDigitalTwin), aby pobrać dane bliźniaczej reprezentacji zamiast zapytania.

Uruchom następujące polecenia w uruchomionej konsoli projektu, aby odpowiedzieć na kilka pytań dotyczących przykładowego środowiska.

1. Jakie są wszystkie jednostki z mojego środowiska reprezentowane w usłudze Azure Digital Twins? (zapytanie wszystkie)

   Query
   

   To polecenie umożliwia błyskawiczne przedstawienie środowiska i upewnienie się, że wszystko jest reprezentowane w taki sposób, jak chcesz, aby był on w usłudze Azure Digital Twins. Wynikiem tego polecenia jest dane wyjściowe zawierające każdą cyfrową reprezentację bliźniaczą ze szczegółami. Oto fragment:

   

   Napiwek

   W przykładowym projekcie polecenie Query bez żadnych dodatkowych argumentów jest odpowiednikiem elementu Query SELECT * FROM DIGITALTWINS. Aby wykonać zapytanie dotyczące wszystkich reprezentacji bliźniaczych w wystąpieniu przy użyciu interfejsów API zapytań lub poleceń interfejsu wiersza polecenia, użyj dłuższego (kompletnego) zapytania.

2. Jakie są wszystkie pokoje w moim środowisku? (zapytanie według modelu)

   Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
   

   Zapytanie można ograniczyć do bliźniaczych reprezentacji określonego typu, aby uzyskać bardziej szczegółowe informacje o reprezentowanych elementach. Wynik tego pokazuje pokój0 i pokój1, ale nie pokazuje floor0 ani floor1 (ponieważ są to podłogi, a nie pokoje).

   

3. Jakie są wszystkie pokoje na piętrze0? (zapytanie według relacji)

   Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
   

   Możesz wykonywać zapytania na podstawie relacji na wykresie, aby uzyskać informacje na temat sposobu łączenia bliźniaczych reprezentacji bliźniaczych lub ograniczenia zapytania do określonego obszaru. Tylko pokój0 znajduje się na piętrze0, więc jest to jedyny pokój w wyniku.

   

4. Jakie są wszystkie bliźniacze reprezentacje w moim środowisku z temperaturą powyżej 75? (zapytanie według właściwości)

   Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
   

   Możesz wykonać zapytanie względem grafu na podstawie właściwości, aby odpowiedzieć na różne pytania, w tym znaleźć wartości odstające w środowisku, które mogą wymagać uwagi. Obsługiwane są również inne operatory porównania (<, =>, lub !=). room1 pojawia się w wynikach tutaj, ponieważ ma temperaturę 80.

   

5. Jakie są wszystkie pokoje na piętrze0 z temperaturą powyżej 75? (zapytanie złożone)

   Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
   

   Możesz również połączyć wcześniejsze zapytania, takie jak w języku SQL, przy użyciu operatorów kombinacji, takich jak AND, , ORNOT. To zapytanie używa AND polecenia , aby poprzednie zapytanie dotyczące temperatury reprezentacji bliźniaczej było bardziej szczegółowe. Wynik obejmuje teraz tylko pomieszczenia o temperaturze powyżej 75, które znajdują się na podłodze 0 — w tym przypadku nie jest to żaden z nich. Zestaw wyników jest pusty.

   

Po uruchomieniu kilku zapytań dotyczących skonfigurowanego scenariusza samouczek zostanie ukończony. Zatrzymaj uruchamianie projektu i zamknij okno konsoli.

Czyszczenie zasobów

Po ukończeniu tego samouczka możesz wybrać zasoby, które chcesz usunąć, w zależności od tego, co chcesz zrobić dalej.

• Jeśli planujesz przejść do następnego samouczka, możesz zachować zasoby skonfigurowane tutaj, aby nadal korzystać z tego wystąpienia usługi Azure Digital Twins i skonfigurować przykładową aplikację na potrzeby następnego samouczka

• Jeśli chcesz nadal korzystać z wystąpienia usługi Azure Digital Twins, ale wyczyść wszystkie jego modele, bliźniacze i relacje, możesz użyć przykładowych poleceń i DeleteAllModels aplikacjiDeleteAllTwins, aby wyczyścić bliźniacze i modele w twoim wystąpieniu.

• Jeśli nie potrzebujesz żadnych zasobów utworzonych w tym samouczku, możesz usunąć wystąpienie usługi Azure Digital Twins i wszystkie inne zasoby z tego artykułu za pomocą polecenia az group delete interfejsu wiersza polecenia. Spowoduje to usunięcie wszystkich zasobów platformy Azure w grupie zasobów, a także samej grupy zasobów.

  Ważne

  Usunięcie grupy zasobów jest nieodwracalne. Grupa zasobów oraz wszystkie zawarte w niej zasoby zostaną trwale usunięte. Uważaj, aby nie usunąć przypadkowo niewłaściwych zasobów lub niewłaściwej grupy zasobów.

  Otwórz usługę Azure Cloud Shell lub lokalne okno interfejsu wiersza polecenia, a następnie uruchom następujące polecenie, aby usunąć grupę zasobów i wszystko, co zawiera.

  az group delete --name <your-resource-group>
  

Możesz również usunąć pobrany folder projektu z komputera lokalnego.

Następne kroki

W tym samouczku rozpoczęto pracę z usługą Azure Digital Twins, tworząc graf w wystąpieniu przy użyciu przykładowej aplikacji klienckiej. Utworzono modele, cyfrowe reprezentacje bliźniacze i relacje w celu utworzenia grafu. Uruchomiono również kilka zapytań na grafie, aby dowiedzieć się, jakiego rodzaju pytania usługa Azure Digital Twins może odpowiedzieć na temat środowiska.

Przejdź do następnego samouczka, aby połączyć usługę Azure Digital Twins z innymi usługami platformy Azure w celu ukończenia scenariusza opartego na danych, kompleksowego:

Połączenie kompleksowe rozwiązanie