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ń w celu wysyłania danych 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
Potrzebujesz konta platformy Azure, które można skonfigurować bezpłatnie
Będziesz potrzebować wystąpienia usługi Azure Digital Twins w ramach subskrypcji platformy Azure. Jeśli nie masz jeszcze wystąpienia, możesz go utworzyć, wykonując kroki opisane w temacie Konfigurowanie wystąpienia i uwierzytelniania. Skorzystaj z poniższych wartości z konfiguracji, aby użyć ich w dalszej części tego artykułu:
- Nazwa wystąpienia
- Grupa zasobów
Te szczegóły można znaleźć w witrynie Azure Portal po skonfigurowaniu wystąpienia.
Następnie postępuj zgodnie z poniższymi instrukcjami, jeśli zamierzasz użyć interfejsu wiersza polecenia platformy Azure, korzystając z tego przewodnika.
Przygotowywanie środowiska dla interfejsu wiersza polecenia platformy Azure
Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.
Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.
Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.
Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.
Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.
Tworzenie wymaganych zasobów
Te usługi są obsługiwanymi typami punktów końcowych, które można utworzyć dla wystąpienia:
- Temat usługi Event Grid
- W przypadku punktów końcowych usługi Event Grid obsługiwane są tylko tematy usługi Event Grid. Domeny usługi Event Grid nie są obsługiwane jako punkty końcowe.
- Centrum usługi Event Hubs
- Temat usługi Service Bus
Aby połączyć punkt końcowy z usługą Azure Digital Twins, temat usługi Event Grid, centrum zdarzeń lub temat usługi Service Bus, który jest używany dla punktu końcowego, musi już istnieć.
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 usługi 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 usługi 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 ich użyć dla punktu końcowego usługi Azure Digital Twins.
Aby utworzyć nowy punkt końcowy, przejdź do strony wystąpienia w witrynie Azure Portal (wystąpienie można znaleźć, wprowadzając jego nazwę na pasku wyszukiwania portalu).
Z menu wystąpienia wybierz pozycję Punkty końcowe. Następnie na stronie Punkty końcowe wybierz pozycję + Utwórz punkt końcowy. Spowoduje to otwarcie strony Tworzenie punktu końcowego , na której wypełnisz pola w poniższych krokach.
Wprowadź nazwę punktu końcowego i wybierz typ punktu końcowego.
Wypełnij pozostałe szczegóły wymagane dla typu punktu końcowego, w tym subskrypcję i zasoby punktu końcowego opisane wcześniej.
- W przypadku tylko punktów końcowych usługi Event Hubs i Service Bus należy wybrać typ uwierzytelniania. Uwierzytelnianie oparte na kluczach można użyć ze wstępnie utworzoną regułą autoryzacji lub tożsamością zarządzaną przypisaną przez system lub przypisaną przez użytkownika. 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.
Zakończ tworzenie punktu końcowego, wybierając pozycję Zapisz.
Po utworzeniu punktu końcowego możesz sprawdzić, czy punkt końcowy został pomyślnie utworzony, sprawdzając ikonę powiadomienia na górnym pasku witryny 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 został utworzony z powrotem 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 używasz tej nazwy jako miejsca docelowego 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 wystąpieniu w łatwym dostępie do innych chronionych zasobów firmy Microsoft, takich jak event hubs, miejsca docelowe usługi Service Bus i kontener usługi 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łączanie tożsamości zarządzanej dla wystąpienia
Skorzystaj z poniższych kart, aby uzyskać instrukcje zgodne z preferowanym środowiskiem.
Najpierw upewnij się, że włączono tożsamość zarządzaną dla wystąpienia usługi Azure Digital Twins.
Upewnij się również, że masz rolę właściciela danych usługi Azure Digital Twins w wystąpieniu. Instrukcje można znaleźć w temacie Konfigurowanie uprawnień dostępu użytkowników.
2. Przypisywanie ról platformy Azure do tożsamości
Po utworzeniu tożsamości zarządzanej dla wystąpienia usługi Azure Digital Twins należy przypisać 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 będzie mogła uzyskać dostępu do punktów końcowych, a zdarzenia nie zostaną dostarczone.
Poniżej przedstawiono minimalne role, których tożsamość usługi Azure Digital Twins musi uzyskać dostęp do punktu końcowego w zależności od typu miejsca docelowego. Role z wyższymi uprawnieniami (takimi jak role właściciela danych) również będą działać.
| Element docelowy | 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ę przy użyciu preferowanego środowiska.
Aby przypisać rolę do tożsamości, zacznij od otwarcia witryny Azure Portal w przeglądarce.
Przejdź do zasobu punktu końcowego (centrum zdarzeń, tematu usługi Service Bus lub kontenera magazynu), wyszukując jego nazwę na pasku wyszukiwania portalu.
Wybierz pozycję Kontrola dostępu (IAM) .
Wybierz pozycję Dodaj>przypisanie roli, aby otworzyć stronę Dodawanie przypisania roli.
Przypisz żądaną rolę do tożsamości zarządzanej wystąpienia usługi Azure Digital Twins, korzystając z poniższych informacji. 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 przypisaną przez system dla wystąpienia usługi Azure Digital Twins, do którego jest przypisana rola. Tożsamość przypisana przez użytkownika będzie miała nazwę wybraną podczas tworzenia tożsamości, a tożsamość przypisana przez system będzie miała nazwę zgodną z nazwą wystąpienia usługi Azure Digital Twins. 
3. Tworzenie punktu końcowego przy użyciu uwierzytelniania opartego na tożsamościach
Po skonfigurowaniu tożsamości zarządzanej dla wystąpienia usługi Azure Digital Twins i przypisaniu jej odpowiednich ról można utworzyć 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, który został już utworzony przy użyciu tożsamości opartej na kluczach, aby zmienić uwierzytelnianie oparte na tożsamościach. Należy wybrać typ uwierzytelniania po pierwszym utworzeniu punktu końcowego.
Użyj poniższych kart, aby utworzyć punkt końcowy przy użyciu preferowanego środowiska.
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.
Zakończ konfigurowanie punktu końcowego i wybierz pozycję Zapisz.
Zagadnienia dotyczące wyłączania tożsamości zarządzanych
Ponieważ tożsamość jest zarządzana oddzielnie od punktów końcowych, które go używają, ważne jest, aby wziąć pod uwagę skutki, jakie wszelkie zmiany tożsamości lub jej ról mogą znajdować się w punktach końcowych w wystąpieniu usługi Azure Digital Twins. Jeśli tożsamość jest wyłączona lub z niego zostanie usunięta niezbędna rola punktu końcowego, punkt końcowy może stać się niedostępny, a przepływ zdarzeń zostanie przerwany.
Aby nadal korzystać z punktu końcowego skonfigurowanego przy użyciu tożsamości zarządzanej, która została teraz wyłączona, musisz usunąć ten punkt końcowy i utworzyć go ponownie przy użyciu innego typu uwierzytelniania. Po tej zmianie może minąć do 1 godziny, zanim nastąpi wznowienie dostarczania zdarzeń do punktu końcowego.
Opcje punktu końcowego: utracony zapis
Jeśli punkt końcowy nie może dostarczyć zdarzenia w określonym czasie lub po próbie dostarczenia zdarzenia określoną liczbę razy, może wysłać zdarzenie nieuprawnione 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łączoną obsługą utraconych komunikatów, 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 utraconych komunikatów, zobacz Punkty końcowe i trasy zdarzeń. Aby uzyskać instrukcje dotyczące konfigurowania punktu końcowego za pomocą utraconych komunikatów, przejdź do pozostałej części tej sekcji.
Konfigurowanie zasobów magazynu
Przed ustawieniem lokalizacji utraconych wiadomości musisz mieć konto magazynu z kontenerem skonfigurowanym na koncie platformy Azure.
Podczas tworzenia punktu końcowego podasz identyfikator URI dla tego kontenera. Lokalizacja utraconych komunikatów zostanie udostępniona punktowi końcowemu jako identyfikator URI kontenera z tokenem SAS. Ten token wymaga write uprawnień dla kontenera docelowego na koncie magazynu. W pełni sformułowany identyfikator URI sygnatury dostępu współdzielonego utraconych wiadomości będzie mieć format: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.
Wykonaj poniższe kroki, aby skonfigurować te zasoby magazynu na koncie platformy Azure, aby przygotować się do skonfigurowania połączenia punktu końcowego w następnej sekcji.
- Wykonaj kroki opisane w temacie Tworzenie konta magazynu, aby utworzyć konto magazynu w ramach subskrypcji platformy Azure. Zanotuj nazwę konta magazynu, aby użyć jej później.
- Wykonaj kroki opisane w temacie Tworzenie kontenera , aby utworzyć kontener na nowym koncie magazynu. Zanotuj nazwę kontenera, aby użyć jej 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.
Zacznij od nawigowania do konta magazynu w witrynie Azure Portal (możesz go znaleźć według nazwy na pasku wyszukiwania portalu).
Na stronie konta magazynu wybierz link Sygnatura dostępu współdzielonego na pasku nawigacyjnym po lewej stronie, aby rozpocząć konfigurowanie tokenu SAS.
Na stronie Sygnatura dostępu współdzielonego w obszarze Dozwolone usługi i Dozwolone typy zasobów wybierz dowolne 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, jeśli chcesz).
Ustaw dowolne wartości dla pozostałych ustawień.
Po zakończeniu wybierz przycisk Generuj sygnaturę dostępu współdzielonego i parametry połączenia, aby wygenerować token SAS.
Spowoduje to wygenerowanie kilku wartości SAS i parametry 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.
Tworzenie punktu końcowego utraconych komunikatów
Aby utworzyć punkt końcowy z włączoną obsługą utraconych komunikatów, musisz użyć poleceń interfejsu wiersza polecenia lub interfejsów API płaszczyzny sterowania, aby utworzyć punkt końcowy, a nie witrynę 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 utraconymi komunikatami komunikaty będą przechowywane w następującym formacie na koncie magazynu:
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
Komunikaty z komunikatami utraconymi będą zgodne ze schematem oryginalnego zdarzenia, które miało zostać dostarczone do oryginalnego punktu końcowego.
Oto przykład komunikatu informującego o utworzeniu bliźniaczej reprezentacji bliźniaczej:
{
"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
Aby rzeczywiście wysyłać dane z usługi Azure Digital Twins do punktu końcowego, należy zdefiniować trasę zdarzeń. Te trasy umożliwiają deweloperom połączenie przepływu zdarzeń w całym systemie i do usług podrzędnych. Pojedyncza trasa może zezwalać na wybór wielu powiadomień i typów zdarzeń. Kontynuuj, aby utworzyć trasę zdarzeń do punktu końcowego w obszarze Tworzenie tras i filtrów.