Samouczek: wdrażanie usługi Azure Digital Twins w wersji zapoznawczej i konfigurowanie grafu przestrzennego

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.

Usługa Azure Digital Twins w wersji zapoznawczej umożliwia łączenie osób, miejsc i urządzeń w spójnym systemie przestrzennym. W tej serii samouczków przedstawiono sposób wykrywania zajętości pomieszczeń z optymalnymi warunkami temperatury i jakości powietrza za pomocą usługi Azure Digital Twins.

Samouczki przeprowadzą Cię przez proces tworzenia w aplikacji konsoli .NET scenariusza budynku biurowego. Budynek składa się z wielu pięter i pomieszczeń na każdym piętrze. W pomieszczeniach znajdują się urządzenia z podłączonymi czujnikami, które wykrywają ruch, temperaturę otoczenia i jakość powietrza.

Nauczysz się, jak za pomocą usługi Azure Digital Twins replikować obszary i jednostki fizyczne w budynku jako obiekty cyfrowe. Przeprowadzisz symulację zdarzeń urządzeń przy użyciu innej aplikacji konsoli. Następnie dowiesz się, jak monitorować zdarzenia pochodzące z tych obszarów i jednostek fizycznych w czasie zbliżonym do rzeczywistego.

Korzystając z tych informacji, administrator biura może ułatwić pracownikom tego budynku rezerwowanie sal konferencyjnych z optymalnymi warunkami. Menedżer pomieszczeń biurowych może za pomocą Twojej konfiguracji poznać trendy dotyczące wykorzystania pomieszczeń oraz monitorować warunki dla celów konserwacji.

W pierwszym samouczku tej serii poznasz następujące zagadnienia:

• Wdrażanie usługi Digital Twins.
• Udzielanie uprawnień dla Twojej aplikacji.
• Modyfikowanie przykładowej aplikacji usługi Digital Twins.
• Aprowizowanie budynku.

W tym samouczkach są używane i modyfikowane te same przykłady co w przewodniku Szybki start dotyczącym znajdowania dostępnych pomieszczeń, co pozwala uzyskać bardziej szczegółową wiedzę na temat poszczególnych pojęć.

Wymagania wstępne

• Subskrypcja platformy Azure. Jeśli nie masz konta platformy Azure, utwórz bezpłatne konto.

• Zestaw SDK dla platformy .NET Core. Przykładowe aplikacje usługi Azure Digital Twins używane w tych samouczkach są napisane w języku C#. Zainstaluj zestaw SDK .NET Core w wersji 2.1.403 lub nowszej na maszynie deweloperskiej w celu skompilowania i uruchomienia przykładu. Sprawdź, czy na Twojej maszynie jest zainstalowana właściwa wersja, uruchamiając polecenie dotnet --version w oknie poleceń.

• Program Visual Studio Code umożliwiający eksplorowanie przykładowego kodu.

Wdrażanie usługi Digital Twins

Wykonaj kroki opisane w tej sekcji, aby utworzyć nowe wystąpienie usługi Azure Digital Twins. Można utworzyć tylko jedno wystąpienie na subskrypcję. Jeśli jedno wystąpienie jest już uruchomione, przejdź do następnej sekcji.

1. Zaloguj się w witrynie Azure Portal.

2. Wybierz pasek boczny strony głównej, a następnie pozycję + Utwórz zasób.

   

3. Wyszukaj usługę Digital Twins i wybierz pozycję Digital Twins.

   

   Alternatywnie wybierz pozycję Internet rzeczy i wybierz pozycję Digital Twins (wersja zapoznawcza).

4. Wybierz przycisk Utwórz, aby rozpocząć proces wdrażania.

   

5. W okienku Digital Twins wprowadź następujące informacje:

   • Nazwa zasobu: utwórz unikatową nazwę dla wystąpienia usługi Digital Twins.

   • Subskrypcja: wybierz subskrypcję, która ma zostać użyta do utworzenia tego wystąpienia usługi Digital Twins.

   • Grupa zasobów: wybierz lub utwórz grupę zasobów dla wystąpienia usługi Digital Twins.

   • Lokalizacja: wybierz lokalizację znajdującą się najbliżej Twoich urządzeń.

     

6. Przejrzyj informacje dotyczące usługi Digital Twins, a następnie wybierz pozycję Utwórz. Tworzenie wystąpienia usługi Digital Twins może potrwać kilka minut. Postępy możesz monitorować w okienku Powiadomienia.

7. Otwórz okienko Przegląd wystąpienia usługi Digital Twins. Zwróć uwagę na link w obszarze Interfejs API zarządzania. Adres URL interfejsu API zarządzania jest sformatowany jako:

   https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
   

   Ten adres URL prowadzi do dokumentacji interfejsu API REST usługi Azure Digital Twins dotyczącej Twojego wystąpienia. Przeczytaj artykuł Jak używać struktury Swagger w usłudze Digital Twins, aby dowiedzieć się, jak odczytać tę dokumentację interfejsu API i korzystać z niej. Skopiuj i zmodyfikuj adres URL interfejsu API zarządzania do tego formatu:

   https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
   

   Aplikacja uzyska dostęp do Twojego wystąpienia, używając zmodyfikowanego adresu URL jako podstawowego adresu URL. Skopiuj ten zmodyfikowany adres URL do pliku tymczasowego. Będzie potrzebny w następnej sekcji.

   

Udzielanie uprawnień dla Twojej aplikacji

Usługa Digital Twins steruje dostępem do odczytu/zapisu w usłudze, korzystając z usługi Azure Active Directory (Azure AD). Każda aplikacja, która wymaga połączenia z wystąpieniem usługi Digital Twins, musi być zarejestrowana w usłudze Azure AD. W tej sekcji opisano procedurę rejestrowania przykładowej aplikacji.

Jeśli już masz zarejestrowaną aplikację, możesz wykorzystać ją jako przykład. Jednak przejrzyj tę sekcję, aby upewnić się, że Twoja rejestracja aplikacji jest poprawnie skonfigurowana.

Uwaga

Ta sekcja zawiera instrukcje dotyczące rejestracji aplikacji Azure AD.

1. W Azure Portal otwórz usługę Azure Active Directory z rozwijanego menu po lewej stronie, a następnie otwórz okienko Rejestracje aplikacji.

   

2. Wybierz przycisk + Nowa rejestracja .

   

3. Wprowadź przyjazną nazwę tej rejestracji aplikacji w polu Nazwa.

   1. W sekcji Identyfikator URI przekierowania (opcjonalnie) wprowadź wartość https://microsoft.com w polu tekstowym.

   2. Sprawdź, które konta i dzierżawy są obsługiwane przez aplikację usługi Azure Active Directory.

   3. Wybierz pozycję Zarejestruj.

   

4. Blok Uwierzytelnianie określa ważne ustawienia konfiguracji uwierzytelniania.

   1. Dodaj identyfikatory URI przekierowania i skonfiguruj tokeny dostępu , wybierając pozycję + Dodaj platformę.

   2. Wybierz pozycję Tak , aby określić, że aplikacja jest klientem publicznym.

   3. Sprawdź, które konta i dzierżawy są obsługiwane przez aplikację usługi Azure Active Directory.

   

5. Po wybraniu odpowiedniej platformy skonfiguruj identyfikatory URI przekierowania i tokeny dostępu na panelu bocznym po prawej stronie interfejsu użytkownika.

   1. Identyfikatory URI przekierowania muszą być zgodne z adresem dostarczonym przez żądanie uwierzytelniania:

      • W przypadku aplikacji hostowanych w lokalnym środowisku programistycznym wybierz pozycję Klient publiczny (mobilny & desktop). Upewnij się, że dla klienta publicznego ustawiono wartość Tak.
      • W przypadku aplikacji Single-Page hostowanych na Azure App Service wybierz pozycję Internet.

   2. Określ, czy adres URL wylogowywania jest odpowiedni.

   3. Włącz niejawny przepływ udzielania, sprawdzając tokeny dostępu lub tokeny identyfikatorów.

   

   Kliknij pozycję Konfiguruj, a następnie pozycję Zapisz.

6. Otwórz okienko Przegląd zarejestrowanej aplikacji i skopiuj wartości następujących jednostek do pliku tymczasowego. Te wartości będą używane do konfigurowania przykładowej aplikacji w poniższych sekcjach.

   • Identyfikator aplikacji (klienta)
   • Identyfikator katalogu (dzierżawcy)

   

7. Otwórz okienko Uprawnienia interfejsu API na potrzeby rejestracji aplikacji. Wybierz przycisk + Dodaj uprawnienie . W okienku Żądania uprawnień interfejsu API wybierz kartę Interfejsy API używane przez moją organizację , a następnie wyszukaj jedną z następujących opcji:

   1. Azure Digital Twins. Wybierz interfejs API usługi Azure Digital Twins .

      

   2. Alternatywnie wyszukaj Azure Smart Spaces Serviceciąg . Wybierz interfejs API usługi Azure Smart Spaces.

      

   Ważne

   Nazwa i identyfikator interfejsu API Azure AD, który będzie wyświetlany, zależy od dzierżawy:

   • Testowe konta dzierżawy i klientów powinny wyszukiwać ciąg Azure Digital Twins.
   • Inne konta Microsoft powinny wyszukiwać .Azure Smart Spaces Service

8. Jeden z interfejsów API będzie wyświetlany jako usługa Azure Digital Twins w tym samym okienku uprawnień interfejsu API żądania po wybraniu. Wybierz opcję listy rozwijanej Odczyt , a następnie zaznacz pole wyboru Read.Write . Wybierz przycisk Dodaj uprawnienia .

   

9. W zależności od ustawień organizacji może być konieczne wykonanie dodatkowych kroków w celu udzielenia dostępu administratora do tego interfejsu API. Aby uzyskać więcej informacji, skontaktuj się z administratorem. Po zatwierdzeniu dostępu administratora w okienku uprawnień interfejsu API zostanie wyświetlona kolumna Administracja Wymagana zgoda.

   

   Sprawdź, czy jest wyświetlana usługa Azure Digital Twins .

Konfigurowanie przykładowej aplikacji usługi Digital Twins

W tej sekcji przejdziesz przez aplikację usługi Azure Digital Twins, która komunikuje się z interfejsami API REST usługi Digital Twins.

Pobieranie przykładu

Jeśli już masz przykłady pobrane na potrzeby przewodnika Szybki start dotyczącego znajdowania dostępnych pomieszczeń, możesz pominąć te kroki.

1. Pobierz przykładowe aplikacje usługi Digital Twins dla platformy .NET.
2. Wyodrębnij zawartość folderu zip na swojej maszynie.

Eksplorowanie przykładu

W folderze z wyodrębnionym przykładem otwórz plik digital-twins-samples-csharp\digital-twins-samples.code-workspace w programie Visual Studio Code. Zawiera on dwa projekty:

• Używając przykładu aprowizacji occupancy-quickstart, możesz skonfigurować i aprowizować wykres analizy przestrzennej. Ten wykres jest cyfrowym obrazem lokalizacji fizycznych i znajdujących się w nich zasobów. Używa modelu obiektów, który definiuje obiekty dla inteligentnego budynku. Aby uzyskać pełną listę obiektów usługi Digital Twins i interfejsów API REST, odwiedź stronę dokumentacji interfejsu API REST lub skorzystaj z adresu URL interfejsu API zarządzania, który został utworzony na potrzeby Twojego wystąpienia.

  Aby zapoznać się z przykładem, aby zrozumieć, jak komunikuje się z wystąpieniem usługi Digital Twins, możesz rozpocząć od folderu src\actions . W plikach w tym folderze zaimplementowano polecenia, które będą używane w tych samouczkach:

  • Plik provisionSample.cs przedstawia sposób aprowizowania grafu przestrzennego.
  • Plik getSpaces.cs pobiera informacje o aprowizowanych miejscach.
  • Plik getAvailableAndFreshSpaces.cs pobiera wyniki funkcji niestandardowej nazywanej funkcją zdefiniowaną przez użytkownika.
  • Plik createEndpoints.cs tworzy punkty końcowe do interakcji z innymi usługami.

• Przykład symulacji device-connectivity symuluje dane z czujników i wysyła je do centrum IoT aprowizowanego na potrzeby Twojego wystąpienia usługi Digital Twins. Ten przykład zostanie wykorzystany w kolejnym samouczku po przeprowadzeniu aprowizacji wykresu przestrzennego. Identyfikatory czujników i urządzeń, których używasz do skonfigurowania tego przykładu, powinny być takie same jak te, które będą używane do aprowizacji wykresu.

Konfigurowanie przykładu aprowizacji

1. Otwórz okno polecenia i przejdź do pobranego przykładu. Uruchom następujące polecenie:

   cd occupancy-quickstart/src
   

2. Przywróć zależności w przykładowym projekcie, uruchamiając następujące polecenie:

   dotnet restore
   

3. W programie Visual Studio Code otwórz plik appSettings.json w projekcie occupancy-quickstart. Zaktualizuj następujące wartości:

   • ClientId: wprowadź identyfikator aplikacji Twojej rejestracji aplikacji w usłudze Azure AD. Ten identyfikator został zanotowany w sekcji, w której były określane uprawnienia aplikacji.
   • Dzierżawa: wprowadź identyfikator katalogu swojej dzierżawy usługi Azure AD. Ten identyfikator także został zanotowany w sekcji, w której były określane uprawnienia aplikacji.
   • BaseUrl: wprowadź adres URL Twojego wystąpienia usługi Digital Twins. Aby uzyskać ten adres URL, zamień symbole zastępcze w tym adresie URL na wartości odpowiadające Twojemu wystąpieniu: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Możesz również uzyskać ten adres URL, modyfikując adres URL interfejsu API zarządzania z sekcji poświęconej wdrażaniu. Zamień ciąg swagger/ na api/v1.0/.

4. Przejrzyj listę funkcji usługi Digital Twins, które można eksplorować przy użyciu przykładu. Uruchom następujące polecenie:

   dotnet run
   

Omówienie procesu aprowizacji

W tej sekcji pokazano, jak przykładowa aplikacja aprowizuje wykres przestrzenny budynku.

W programie Visual Studio Code przejdź do folderu occupancy-quickstart\src\actions i otwórz plik provisionSample.cs. Zwróć uwagę na następującą funkcję:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Ta funkcja używa pliku provisionSample.yaml z tego samego folderu. Otwórz ten plik i zanotuj hierarchię budynku biura: Venue (Miejsce), Floor (Piętro), Area (Obszar) i Rooms (Pomieszczenia). W każdym z tych miejsc fizycznych mogą znajdować się urządzenia i czujniki. Każdy wpis ma wstępnie zdefiniowane type— na przykład Floor, Room.

Przykładowy plik yaml przedstawia wykres przestrzenny korzystający z domyślnego (Default) modelu obiektów usługi Digital Twins. Ten model zawiera nazwy rodzajowe dla większości typów. Nazwy rodzajowe są wystarczające dla budynku. Przykłady takich nazw to: Temperature dla typu SensorDataType i Map dla typu SpaceBlobType. Przykładowym typem miejsca jest Room (Pomieszczenie) z podtypami FocusRoom (Pomieszczenie robocze), ConferenceRoom (Sala konferencyjna) itd.

Jeśli musisz utworzyć wykres przestrzenny dla innego typu miejsca, na przykład dla fabryki, możesz potrzebować innego modelu obiektów. Uruchamiając polecenie dotnet run GetOntologies w wierszu polecenia dla przykładu aprowizacji, możesz dowiedzieć się, jakie modele są dostępne do użycia.

Aby uzyskać więcej informacji na temat wykresów przestrzennych i modeli obiektów, przeczytaj Omówienie modeli obiektów i wykresu analizy przestrzennej usługi Digital Twins.

Modyfikowanie przykładowego wykresu przestrzennego

Plik provisionSample.yaml zawiera następujące węzły:

• resources: węzeł resources tworzy w konfiguracji zasób usługi Azure IoT Hub do komunikacji z urządzeniami. Centrum IoT w węźle głównym wykresu może komunikować się ze wszystkimi urządzeniami i czujnikami na wykresie.

• spaces: w modelu obiektów usługi Digital Twins węzeł spaces reprezentuje lokalizacje fizyczne. Każda przestrzeń ma Typewartość —na przykład Region, Miejsce lub Klient — i przyjazną Name. Miejsca mogą należeć do innych miejsc tworzących strukturę hierarchiczną. Plik provisionSample.yaml zawiera wykres przestrzenny wymyślonego budynku. Zwróć uwagę na logiczne zagnieżdżanie miejsc typu Floor w węźle Venue, typu Area na piętrze i węzłów Room w obszarze.

• devices: miejsca mogą zawierać urządzenia (devices) będące jednostkami fizycznymi lub wirtualnymi, które zarządzają pewną liczbą czujników. Na przykład urządzenie może być telefonem użytkownika, zasobnikem czujnika Urządzenia Raspberry Pi lub bramą. W wymyślonym budynku z Twojego przykładu zwróć uwagę na sposób umieszczenia urządzenia Raspberry Pi 3 A1 w pomieszczeniu Focus Room. Każdy węzeł urządzenia jest identyfikowany przez unikatowy identyfikator hardwareId trwale zakodowany w przykładzie. Aby skonfigurować ten przykład na potrzeby rzeczywistego środowiska produkcyjnego, zamień te wartości na wartości z Twojej konfiguracji.

• sensors: urządzenie może zawierać wiele czujników (sensors). Umożliwiają one wykrywanie i rejestrowanie zmian fizycznych, takich jak temperatura, ruch i poziom naładowania baterii. Każdy węzeł czujnika jest unikatowo identyfikowany za pomocą identyfikatora hardwareId trwale zapisanego w tym miejscu. Na potrzeby rzeczywistej aplikacji zamień te identyfikatory, używając unikatowych identyfikatorów czujników z Twojej konfiguracji. Plik provisionSample.yaml ma dwa czujniki umożliwiające rejestrowanie ruchu (Motion) i dwutlenku węgla (CarbonDioxide). Dodaj kolejny czujnik, aby rejestrować temperaturę (Temperature), dodając poniższe wiersze pod wierszami dotyczącymi czujnika CarbonDioxide. Są one udostępniane w pliku provisionSample.yaml jako wiersze komentarzy. Możesz przenieść je poza komentarze, usuwając znak # na początku wiersza.

          - dataType: Temperature
            hardwareId: SAMPLE_SENSOR_TEMPERATURE
  

  Uwaga

  Upewnij się, że klucze dataType i hardwareId pasują do instrukcji powyżej tego fragmentu kodu. Upewnij się również, że edytor nie zastępuje spacji tabulatorami.

Zapisz i zamknij plik provisionSample.yaml. W następnym samouczku dodasz więcej informacji do tego pliku, a następnie przeprowadzisz aprowizację przykładowego budynku w usłudze Azure Digital Twins.

Porada

Wykres przestrzenny można wyświetlać i modyfikować przy użyciu narzędzia Azure Digital Twins Graph Viewer.

Czyszczenie zasobów

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

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

   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.

2. Jeśli będzie to konieczne, możesz usunąć przykładową aplikację na komputerze służbowym.

Następne kroki

Aby dowiedzieć się, jak zaimplementować logikę niestandardową w celu monitorowania warunków w przykładowym budynku, przejdź do kolejnego samouczka w serii:

Samouczek: aprowizowanie budynku i monitorowanie warunków pracy