Samouczek: wdrażanie usługi Azure Digital bliźniaczych reprezentacji Preview i Konfigurowanie wykresu przestrzennego

Ważne

Wydano nową wersję usługi Azure Digital bliźniaczych reprezentacji. W świetle rozszerzonych możliwości usługi oryginalna usługa Azure Digital bliźniaczych reprezentacji (opisana w tym zestawie dokumentacji) zostanie wycofana do końca roku 2020.

Aby wyświetlić dokumentację nowej usługi, odwiedź dokumentację usługi Azure Digital bliźniaczych reprezentacji w wersji zapoznawczej.

Możesz użyć usługi Azure Digital bliźniaczych reprezentacji w wersji zapoznawczej, aby połączyć osoby, miejsca i urządzenia w spójny system przestrzenny. 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 po stronie głównej, a następnie pozycję + Utwórz zasób.

    Rozwiń pasek boczny po stronie głównej, a następnie wybierz pozycję + Utwórz zasób.

  3. Wyszukaj ciąg Digital bliźniaczych reprezentacjii wybierz pozycję Digital bliźniaczych reprezentacji.

    Opcje podczas tworzenia nowego wystąpienia usługi Digital Twins

    Alternatywnie wybierz pozycję Internet rzeczyi wybierz pozycję Digital bliźniaczych reprezentacji (wersja zapoznawcza).

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

    Utwórz i Potwierdź wdrożenie zasobu

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

      Okienko usługi Digital Twins z wprowadzonymi informacjami

  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.

    Omówienie interfejsu API zarządzania

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 usługi Azure AD.

  1. W Azure PortalOtwórz Azure Active Directory z menu rozwijanego po lewej stronie, a następnie otwórz okienko rejestracje aplikacji .

    Wybierz okienko Azure Active Directory

  2. Wybierz przycisk + Nowa rejestracja .

    Wybierz przycisk Nowa rejestracja

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

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

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

    3. Wybierz pozycję Zarejestruj.

    Okienko tworzenia

  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żawcy są obsługiwane przez aplikację Azure Active Directory.

    Ustawienie konfiguracji klienta publicznego

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

    1. Identyfikatory URI przekierowania muszą być zgodne z adresem podanym w żądaniu uwierzytelniania:

      • W przypadku aplikacji hostowanych w lokalnym środowisku programistycznym wybierz pozycję Klient publiczny (mobile & Desktop). Upewnij się, że ustawiono opcję Klient publiczny na wartość tak.
      • W przypadku aplikacji jednostronicowych hostowanych w Azure App Service wybierz pozycję Sieć Web.
    2. Ustal, czy adres URL wylogowania jest odpowiedni.

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

    Konfigurowanie identyfikatorów URI przekierowania

    Kliknij przycisk Konfiguruj, a następnie 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)

    Identyfikator aplikacji usługi Azure Active Directory

  7. Otwórz okienko uprawnień interfejsu API dla rejestracji aplikacji. Wybierz pozycję + Dodaj przycisk uprawnienia . W okienku uprawnienia żądania interfejsu API wybierz opcję interfejsy API Moja organizacja używa karty, a następnie wyszukaj jedną z następujących opcji:

    1. Azure Digital Twins. Wybierz interfejs API Digital bliźniaczych reprezentacji platformy Azure .

      Interfejs API wyszukiwania lub usługa Azure Digital bliźniaczych reprezentacji

    2. Możesz też wyszukać Azure Smart Spaces Service . Wybierz interfejs API usługi Azure Smart Spaces .

      Interfejs API wyszukiwania w usłudze Azure Smart Spaces

    Ważne

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

    • Należy wyszukać w usłudze testowej dzierżawy i konta klienta Azure Digital Twins .
    • Należy wyszukać inne konta Microsoft Azure Smart Spaces Service .
  8. Jeden z interfejsów API będzie wyświetlany jako usługa Azure Digital bliźniaczych reprezentacji w tym samym okienku uprawnień interfejsu API żądania . Wybierz opcję Odczyt Odczytaj , a następnie zaznacz pole wyboru Odczyt. zapis . Wybierz przycisk Dodaj uprawnienia .

    Dodawanie uprawnień interfejsu API

  9. W zależności od ustawień organizacji może być konieczne wykonanie dodatkowych czynności w celu udzielenia administratorowi dostępu do tego interfejsu API. Aby uzyskać więcej informacji, skontaktuj się z administratorem. Po zatwierdzeniu dostępu administratora do kolumny wymagana jest zgoda administratora w okienku uprawnienia interfejsu API zostaną wyświetlone Twoje uprawnienia.

    Zatwierdzenie zgody administratora

    Sprawdź, czy zostanie wyświetlona Usługa Digital bliźniaczych reprezentacji .

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 do inteligentnego kompilowania. 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 Digital bliźniaczych reprezentacji, możesz rozpocząć pracę z folderem src\actions . W plikach w tym folderze zaimplementowano polecenia, które będą używane w tych samouczkach:

    • Plik provisionSample.cs pokazuje, jak zainicjować obsługę wykresu przestrzennego.
    • Plik getSpaces.cs pobiera informacje o zainicjowanych 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. Zapoznaj się z listą funkcji Digital bliźniaczych reprezentacji, które możesz 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 zdefiniowany typ (type) — na przykład Floor (Piętro) lub Room (Pomieszczenie).

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żde miejsce ma typ (Type) — na przykład Region, Venue (Miejsce) lub Customer (Klient) — oraz przyjazną nazwę (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, Raspberry z czujnikiem 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 dostępne w provisionSample. YAML jako wiersze z komentarzem. 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.

Oczyszczanie 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: