Udostępnij przez


Tworzenie punktów końcowych w usłudze Azure Digital Twins

W tym artykule wyjaśniono, jak utworzyć punkt końcowy dla zdarzeń usługi Azure Digital Twin przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure. Możesz również zarządzać punktami końcowymi za pomocą interfejsów API płaszczyzny sterowania DigitalTwinsEndpoint.

Routing powiadomień o zdarzeniach z usługi Azure Digital Twins do usług podrzędnych lub połączonych zasobów obliczeniowych jest procesem dwuetapowym: tworzenie punktów końcowych, a następnie tworzenie tras zdarzeń, które wysyłają dane do tych punktów końcowych. W tym artykule opisano pierwszy krok konfigurowania punktów końcowych, które mogą odbierać zdarzenia. Później możesz utworzyć trasy zdarzeń określające, które zdarzenia generowane przez usługę Azure Digital Twins są dostarczane do których punktów końcowych.

Wymagania wstępne

  • Konto platformy Azure, które można skonfigurować bezpłatnie.

  • Instancja Azure Digital Twins w ramach Twojej subskrypcji Azure. Jeśli nie masz wystąpienia, utwórz je, wykonując kroki opisane w temacie Konfigurowanie wystąpienia i uwierzytelniania. W dalszej części tego artykułu miej dostępne następujące wartości z konfiguracji:

    • Nazwa wystąpienia
    • Grupa zasobów

    Te informacje można znaleźć w portalu Azure po skonfigurowaniu wystąpienia.

    Zrzut ekranu przedstawiający stronę przeglądu wystąpienia usługi Azure Digital Twins w witrynie Azure Portal. Nazwa i grupa zasobów są wyróżnione.

Jeśli zamierzasz używać interfejsu wiersza polecenia platformy Azure podczas wykonywania czynności opisanych w tym przewodniku, postępuj zgodnie z instrukcjami w następnej sekcji.

Przygotuj środowisko dla interfejsu CLI platformy Azure

Tworzenie wymaganych zasobów

Te usługi to obsługiwane typy punktów końcowych, które można utworzyć dla swojego wystąpienia.

Przed połączeniem punktu końcowego z usługą Azure Digital Twins należy utworzyć temat usługi Event Grid, centrum zdarzeń lub temat usługi Service Bus używany dla punktu końcowego.

Użyj poniższego wykresu, aby zobaczyć, jakie zasoby należy skonfigurować przed utworzeniem punktu końcowego.

Typ punktu końcowego Wymagane zasoby (połączone z instrukcjami tworzenia)
Punkt końcowy usługi Event Grid Temat Event Grid
(Schemat zdarzeń musi być schematem usługi Event Grid lub schematem zdarzeń w chmurze w wersji 1.0)
Punkt końcowy usługi Event Hubs Przestrzeń nazw usługi Event Hubs

centrum zdarzeń

(Opcjonalnie) Reguła autoryzacji na potrzeby uwierzytelniania opartego na kluczach
Punkt końcowy usługi Service Bus Przestrzeń nazw usługi Service Bus

Temat Service Bus

(Opcjonalnie) Reguła autoryzacji na potrzeby uwierzytelniania opartego na kluczach

Tworzenie punktu końcowego

Po utworzeniu zasobów punktu końcowego możesz utworzyć punkt końcowy usługi Azure Digital Twins. Użyj poniższych zakładek, aby wybrać preferowane doświadczenie.

Aby utworzyć nowy punkt końcowy, przejdź do strony wystąpienia w portalu Azure. Wystąpienie można znaleźć, wprowadzając jego nazwę na pasku wyszukiwania portalu.

  1. Z menu wystąpienia wybierz pozycję Połącz dane wyjściowe z punktami końcowymi>. Następnie na stronie Punkty końcowe wybierz pozycję + Utwórz punkt końcowy. Ta akcja powoduje otwarcie strony Tworzenie punktu końcowego .

    Zrzut ekranu przedstawiający tworzenie punktu końcowego typu Event Grid w witrynie Azure Portal.

  2. Wprowadź nazwę punktu końcowego i wybierz typ punktu końcowego.

  3. Wypełnij pozostałe szczegóły wymagane dla typu punktu końcowego, w tym subskrypcję i zasoby punktu końcowego opisane wcześniej.

    1. W przypadku punktów końcowych usługi Event Hubs i Service Bus wybierz typ uwierzytelniania. Można użyć uwierzytelniania opartego na kluczach ze wstępnie utworzoną regułą autoryzacji lub zarządzanej tożsamości przypisanej przez system lub użytkownika. Tożsamość przypisana przez system jest dostępna tylko wtedy, gdy dla wystąpienia została włączona tożsamość przypisana przez system. Aby uzyskać więcej informacji na temat korzystania z opcji uwierzytelniania tożsamości, zobacz Opcje punktu końcowego: uwierzytelnianie oparte na tożsamości w dalszej części tego artykułu.

    Zrzut ekranu przedstawiający tworzenie punktu końcowego typu Event Hubs w witrynie Azure Portal.

  4. Zakończ tworzenie punktu końcowego, wybierając pozycję Zapisz.

Po utworzeniu punktu końcowego możesz sprawdzić, czy został on pomyślnie utworzony, sprawdzając ikonę powiadomienia na górnym pasku witryny Azure Portal:

Zrzut ekranu przedstawiający powiadomienie w celu zweryfikowania utworzenia punktu końcowego w witrynie Azure Portal.

Jeśli tworzenie punktu końcowego zakończy się niepowodzeniem, zaobserwuj komunikat o błędzie i spróbuj ponownie po kilku minutach.

Możesz również wyświetlić punkt końcowy, który utworzyłeś, na stronie Punkty końcowe dla wystąpienia usługi Azure Digital Twins.

Teraz temat usługi Event Grid, centrum zdarzeń lub temat usługi Service Bus jest dostępny jako punkt końcowy w usłudze Azure Digital Twins pod nazwą wybraną dla punktu końcowego. Zazwyczaj ta nazwa jest używana jako element docelowy trasy zdarzeń, którą można utworzyć w obszarze Tworzenie tras i filtrów.

Opcje punktu końcowego: uwierzytelnianie oparte na tożsamościach

W tej sekcji opisano sposób używania tożsamości zarządzanej dla wystąpienia usługi Azure Digital Twins podczas przekazywania zdarzeń do obsługiwanych miejsc docelowych routingu. Skonfigurowanie tożsamości zarządzanej nie jest wymagane do routingu, ale może pomóc instancji w łatwym dostępie do innych chronionych zasobów firmy Microsoft, takich jak Event Hubs, miejsca docelowe Service Bus i kontener Azure Storage. Tożsamości zarządzane mogą być przypisane przez system lub przypisane przez użytkownika.

W pozostałej części tej sekcji przedstawiono trzy kroki konfigurowania punktu końcowego przy użyciu tożsamości zarządzanej.

1. Włącz tożsamość zarządzaną dla wystąpienia

Skorzystaj z poniższych zakładek, aby uzyskać instrukcje zgodnie z Twoimi preferencjami.

Najpierw upewnij się, że włączasz tożsamość zarządzaną dla wystąpienia usługi Azure Digital Twins.

Upewnij się również, że masz rolę właściciela danych Azure Digital Twins w instancji. Instrukcje można znaleźć w temacie Konfigurowanie uprawnień dostępu użytkowników.

2. Przypisz role platformy Azure do tożsamości

Po utworzeniu tożsamości zarządzanej dla wystąpienia usługi Azure Digital Twins przypisz odpowiednie role do uwierzytelniania przy użyciu różnych typów punktów końcowych na potrzeby routingu zdarzeń do obsługiwanych miejsc docelowych. W tej sekcji opisano opcje ról i sposób przypisywania ich do tożsamości zarządzanej.

Ważne

Pamiętaj, aby wykonać ten krok. Bez niego tożsamość nie ma dostępu do punktów końcowych, a zdarzenia nie są dostarczane.

Poniżej przedstawiono minimalne role, które tożsamości usługi Azure Digital Twins muszą mieć, aby uzyskać dostęp do punktu końcowego, w zależności od typu punktu docelowego. Role z wyższymi uprawnieniami (takimi jak role właściciela danych) również działają.

Cel Rola na platformie Azure
Azure Event Hubs Nadawca danych usługi Azure Event Hubs
Azure Service Bus Nadawca danych usługi Azure Service Bus
Kontener usługi Azure Storage Współautor danych w usłudze Blob Storage

Użyj poniższych kart, aby przypisać rolę zgodnie z preferowanym doświadczeniem.

Aby przypisać rolę do tożsamości, otwórz witrynę Azure Portal w przeglądarce.

  1. Przejdź do zasobu punktu końcowego (centrum zdarzeń, tematu usługi Service Bus lub kontenera magazynu), wyszukując jego nazwę na pasku wyszukiwania portalu.

  2. Wybierz pozycję Kontrola dostępu (IAM).

  3. Wybierz Dodaj>Dodaj przypisanie roli, aby otworzyć stronę Dodawania przypisania roli.

  4. Przypisz żądaną rolę dla zarządzanej tożsamości instancji Azure Digital Twins. Aby uzyskać szczegółowe instrukcje, zobacz Przypisywanie ról platformy Azure przy użyciu witryny Azure Portal.

    Ustawienie Wartość
    Rola Wybierz odpowiednią rolę z opcji.
    Przypisz dostęp do Tożsamość zarządzana
    Członkowie Wybierz tożsamość zarządzaną przypisaną przez użytkownika lub przez system dla instancji usługi Azure Digital Twins, której przypisywana jest rola. Tożsamość przypisana przez użytkownika ma nazwę wybraną podczas tworzenia tożsamości, a tożsamość przypisana przez system ma nazwę zgodną z nazwą wystąpienia usługi Azure Digital Twins.

    Zrzut ekranu przedstawiający stronę

3. Utwórz punkt końcowy przy użyciu uwierzytelniania opartego na tożsamości

Po skonfigurowaniu tożsamości zarządzanej dla wystąpienia usługi Azure Digital Twins i przypisaniu jej odpowiednich ról utwórz punkty końcowe, które używają tożsamości do uwierzytelniania. Ta opcja jest dostępna tylko dla punktów końcowych usługi Event Hubs i usługi Service Bus (nie jest obsługiwana w przypadku usługi Event Grid).

Uwaga

Nie można edytować punktu końcowego utworzonego przy użyciu tożsamości opartej na kluczach, aby przełączyć na uwierzytelnianie oparte na tożsamości. Podczas pierwszego tworzenia punktu końcowego należy wybrać typ uwierzytelniania.

Skorzystaj z poniższych sekcji, aby utworzyć punkt końcowy przy użyciu wybranego sposobu.

Zacznij przestrzegać ogólnych instrukcji dotyczących tworzenia punktu końcowego usługi Azure Digital Twins.

Po wykonaniu kroku ukończenia szczegółów wymaganych dla typu punktu końcowego wybierz opcję Przypisana przez system lub Przypisana przez użytkownika (wersja zapoznawcza) dla typu uwierzytelniania.

Zrzut ekranu przedstawiający tworzenie punktu końcowego typu Event Hubs.

Zakończ konfigurowanie punktu końcowego i wybierz pozycję Zapisz.

Rozważania dotyczące wyłączenia tożsamości zarządzanych

Tożsamość jest zarządzana oddzielnie od punktów końcowych, które jej używają, dlatego ważne jest, aby rozważyć, jak każda zmiana tożsamości lub jej ról może wpłynąć na punkty końcowe w wystąpieniu usługi Azure Digital Twins. Jeśli wyłączysz tożsamość lub usuniesz niezbędną rolę dla punktu końcowego, punkt końcowy stanie się niedostępny, a przepływ zdarzeń zostanie przerwany.

Aby kontynuować korzystanie z punktu końcowego skonfigurowanego przy użyciu wyłączonej tożsamości zarządzanej, usuń punkt końcowy i utwórz go ponownie przy użyciu innego typu uwierzytelniania. Wznowienie dostarczania do punktu końcowego po tej zmianie może potrwać do godziny.

Opcje punktu końcowego: utracony zapis

Gdy punkt końcowy nie może dostarczyć zdarzenia w określonym okresie lub liczbie prób, może wysłać zdarzenie niedostarczone do konta magazynu. Ten proces jest znany jako utracony zapis.

Niezbędne zasoby magazynu można skonfigurować przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia usługi Azure Digital Twins. Jednak aby utworzyć punkt końcowy z włączonym przechwytywaniem nieprzetworzonych wiadomości, musisz użyć interfejsu wiersza polecenia usługi Azure Digital Twins lub interfejsów API płaszczyzny sterowania.

Aby dowiedzieć się więcej na temat "dead-letteringu", zobacz Punkty końcowe i trasy zdarzeń. Aby uzyskać instrukcje dotyczące konfigurowania punktu końcowego z wykorzystaniem kolejki wiadomości oznaczonych jako niedostarczone, zapoznaj się z pozostałą częścią tej sekcji.

Konfigurowanie zasobów magazynu

Przed ustawieniem lokalizacji utraconych wiadomości musisz mieć konto magazynu z kontenerem na koncie platformy Azure.

Podczas tworzenia punktu końcowego należy podać identyfikator URI tego kontenera. Lokalizacja wiadomości nie do dostarczenia jest dostarczana do punktu końcowego jako identyfikator URI kontenera z tokenem SAS. Ten token wymaga write uprawnień dla kontenera docelowego w ramach konta magazynu. W pełni sformułowany identyfikator URI sygnatury dostępu współdzielonego utraconych jest w formacie: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Aby skonfigurować te zasoby magazynu na koncie Azure, wykonaj kroki opisane w poniższej sekcji. Po skonfigurowaniu zasobów przechowywania można zainstalować połączenie punktu końcowego.

  1. Aby utworzyć konto magazynu w ramach subskrypcji platformy Azure, wykonaj kroki opisane w temacie Tworzenie konta magazynu. Zanotuj nazwę konta magazynu, aby można było go później użyć.
  2. Aby utworzyć kontener na nowym koncie magazynu, wykonaj kroki opisane w temacie Tworzenie kontenera. Zanotuj nazwę kontenera, aby można było jej użyć później.

Tworzenie tokenu SAS

Następnie utwórz token SAS dla konta magazynu, którego punkt końcowy może używać do uzyskiwania do niego dostępu.

  1. Przejdź do konta magazynu w witrynie Azure Portal (możesz go znaleźć według nazwy na pasku wyszukiwania portalu).

  2. Na stronie konta magazynu wybierz link Zabezpieczenia i sieć > Sygnatura dostępu współdzielonego na pasku nawigacyjnym po lewej stronie, aby rozpocząć konfigurowanie tokenu SAS.

    Zrzut ekranu przedstawiający stronę konta zasobów w portalu Azure.

  3. Na stronie Sygnatura dostępu współdzielonego w obszarze Dozwolone usługi i Dozwolone typy zasobów wybierz żądane ustawienia. Musisz zaznaczyć co najmniej jedno pole w każdej kategorii. W obszarze Dozwolone uprawnienia wybierz pozycję Zapisz. Możesz również wybrać inne uprawnienia.

  4. Ustaw żądane wartości dla pozostałych ustawień.

  5. Po zakończeniu wybierz Generuj token SAS i ciąg połączenia, aby wygenerować token SAS.

  6. Ukończenie tego procesu powoduje wygenerowanie kilku wartości sygnatury dostępu współdzielonego i parametrów połączenia w dolnej części tej samej strony, pod wyborami ustawień. Przewiń w dół, aby wyświetlić wartości, i użyj ikony Kopiuj do schowka , aby skopiować wartość tokenu SAS . Zapisz go do późniejszego użycia.

Utwórz punkt końcowy dla martwych listów

Aby utworzyć punkt końcowy z włączoną funkcją dead-lettering, użyj poleceń CLI lub interfejsów API płaszczyzny sterowania. Nie można utworzyć tego typu punktu końcowego w witrynie Azure Portal.

Aby uzyskać instrukcje dotyczące tworzenia tego typu punktu końcowego za pomocą interfejsu wiersza polecenia platformy Azure, przejdź do karty interfejsu wiersza polecenia dla tej sekcji.

Schemat magazynu komunikatów

Po skonfigurowaniu punktu końcowego z funkcją zarządzania komunikatami nieodebranymi, komunikaty nieodebrane są przechowywane na koncie magazynu w następującym formacie.

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Wiadomości zakolejkowane są zgodne ze schematem oryginalnego zdarzenia, które pierwotny punkt końcowy był przeznaczony do dostarczenia.

Oto przykład komunikatu o niewysłanej wiadomości dla powiadomienia o utworzeniu bliźniaka:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Następne kroki

Po utworzeniu punktu końcowego zdefiniuj trasę zdarzeń , aby wysyłać dane do punktu końcowego. Trasy zdarzeń umożliwiają skonfigurowanie przepływu zdarzeń w całym systemie i do usług podrzędnych. Pojedyncza trasa może zezwalać na wiele powiadomień i typów zdarzeń. Utwórz trasę zdarzenia do punktu końcowego, zgodnie z instrukcjami w temacie Tworzenie tras i filtrów.