Udostępnij za pośrednictwem


Tworzenie tras i filtrów zdarzeń w usłudze Azure Digital Twins

W tym artykule przedstawiono proces tworzenia tras zdarzeń przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure az dt route, interfejsów API płaszczyzny danych tras zdarzeń i zestawu SDK platformy .NET (C#).

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 drugi krok, konfigurowanie tras w celu kontrolowania, które zdarzenia są dostarczane do których punktów końcowych usługi Azure Digital Twin. Aby przejść do tego artykułu, należy mieć już utworzone punkty końcowe .

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.

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

  • Utwórz punkt końcowy, korzystając z instrukcji w temacie Tworzenie punktów końcowych. W tym artykule utworzysz trasę do wysyłania danych do tego punktu końcowego.

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

Tworzenie trasy zdarzeń

Po utworzeniu punktu końcowego należy zdefiniować trasę zdarzeń, aby rzeczywiście wysyłać dane do punktu końcowego. 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ń. Przeczytaj więcej na temat tras zdarzeń w punktach końcowych i trasach zdarzeń.

Uwaga

Przed przejściem do tworzenia trasy upewnij się, że utworzono co najmniej jeden punkt końcowy zgodnie z opisem w sekcji Wymagania wstępne .

Jeśli ostatnio wdrożono punkty końcowe, sprawdź, czy zostały one wdrożone przed podjęciem próby użycia ich dla nowej trasy zdarzeń. Jeśli wdrożenie trasy zakończy się niepowodzeniem, ponieważ punkty końcowe nie są gotowe, zaczekaj kilka minut i spróbuj ponownie.

Jeśli używasz skryptów tego przepływu, możesz chcieć to uwzględnić, tworząc 2–3 minuty czasu oczekiwania na zakończenie wdrażania usługi punktu końcowego przed przejściem do konfiguracji trasy.

Definicja trasy może zawierać następujące elementy:

  • Nazwa trasy, której chcesz użyć
  • Nazwa punktu końcowego, którego chcesz użyć
  • Filtr definiujący, które zdarzenia są wysyłane do punktu końcowego
    • Aby wyłączyć trasę tak, aby żadne zdarzenia nie zostały wysłane, użyj wartości filtru false
    • Aby włączyć trasę, która nie ma określonego filtrowania, użyj wartości filtru true
    • Aby uzyskać szczegółowe informacje na temat dowolnego innego typu filtru, zobacz sekcję Filtry zdarzeń poniżej

Jeśli nie ma nazwy trasy, żadne komunikaty nie są kierowane poza usługą Azure Digital Twins. Jeśli istnieje nazwa trasy i filtr to true, wszystkie komunikaty są kierowane do punktu końcowego. Jeśli istnieje nazwa trasy i zostanie dodany inny filtr, komunikaty będą filtrowane na podstawie filtru.

Trasy zdarzeń można tworzyć za pomocą witryny Azure Portal, interfejsów API płaszczyzny danych usługi EventRoutes lub poleceń interfejsu wiersza polecenia az dt route. W pozostałej części tej sekcji przedstawiono proces tworzenia.

Aby utworzyć trasę zdarzeń, przejdź do strony szczegółów wystąpienia usługi Azure Digital Twins w witrynie Azure Portal (wystąpienie można znaleźć, wprowadzając jego nazwę na pasku wyszukiwania portalu).

Z menu wystąpienia wybierz pozycję Trasy zdarzeń. Następnie na stronie Trasy zdarzeń wybierz pozycję + Utwórz trasę zdarzeń.

Na stronie Tworzenie trasy zdarzeń, która zostanie otwarta, wybierz co najmniej:

  • Nazwa trasy w polu Nazwa
  • Punkt końcowy , którego chcesz użyć do utworzenia trasy

Aby trasa została włączona, należy również dodać filtr trasy zdarzeń co najmniej true. (Pozostawienie wartości domyślnej false polecenia spowoduje utworzenie trasy, ale żadne zdarzenia nie zostaną do niej wysłane). W tym celu przełącz przełącznik edytora zaawansowanego, aby go włączyć, i zapisz true w polu Filtr.

Zrzut ekranu przedstawiający tworzenie trasy zdarzeń dla wystąpienia w witrynie Azure Portal.

Po zakończeniu wybierz przycisk Zapisz , aby utworzyć trasę zdarzeń.

Filtrowanie zdarzeń

Jak opisano powyżej, trasy mają pole filtru. Jeśli wartość filtru na trasie to false, żadne zdarzenia nie zostaną wysłane do punktu końcowego.

Po włączeniu minimalnego filtru truepunktów końcowych będą otrzymywać różne rodzaje zdarzeń z usługi Azure Digital Twins:

  • Telemetria wyzwolona przez cyfrowe reprezentacje bliźniacze przy użyciu interfejsu API usługi Azure Digital Twins
  • Powiadomienia o zmianie właściwości bliźniaczej reprezentacji, wyzwolone na zmiany właściwości dla każdej reprezentacji bliźniaczej w wystąpieniu usługi Azure Digital Twins
  • Zdarzenia cyklu życia, wyzwalane po utworzeniu lub usunięciu bliźniaczych reprezentacji lub relacji

Można ograniczyć typy wysyłanych zdarzeń, definiując bardziej szczegółowy filtr.

Uwaga

Filtry są wrażliwe na wielkość liter i muszą być zgodne z wielkością liter. W przypadku filtrów telemetrycznych oznacza to, że wielkość liter musi być zgodna z wielkością liter w telemetrii wysyłanej przez urządzenie.

Aby dodać filtr zdarzeń podczas tworzenia trasy zdarzeń, użyj sekcji Dodawanie filtru tras zdarzeń na stronie Tworzenie trasy zdarzeń.

Możesz wybrać jedną z podstawowych typowych opcji filtrowania lub użyć zaawansowanych opcji filtrowania, aby napisać własne filtry niestandardowe.

Korzystanie z podstawowych filtrów

Aby użyć filtrów podstawowych, rozwiń opcję Typy zdarzeń i zaznacz pola wyboru odpowiadające zdarzeniu, które chcesz wysłać do punktu końcowego.

Zrzut ekranu przedstawiający tworzenie trasy zdarzeń z podstawowym filtrem w witrynie Azure Portal z wyróżnionymi polami wyboru zdarzeń.

Spowoduje to automatyczne wypełnienie pola tekstowego filtru tekstem wybranego filtru:

Zrzut ekranu przedstawiający tworzenie trasy zdarzeń z podstawowym filtrem w witrynie Azure Portal z wyróżnionym automatycznie wypełnionym tekstem filtru po wybraniu zdarzeń.

Korzystanie z filtrów zaawansowanych

Możesz również użyć opcji filtru zaawansowanego, aby napisać własne filtry niestandardowe.

Aby utworzyć trasę zdarzeń z zaawansowanymi opcjami filtrowania, przełącz przełącznik edytora zaawansowanego, aby go włączyć. Następnie możesz napisać własne filtry zdarzeń w polu Filtr :

Zrzut ekranu przedstawiający tworzenie trasy zdarzeń z zaawansowanym filtrem w witrynie Azure Portal.

Obsługiwane filtry tras

Oto obsługiwane filtry tras.

Nazwa filtru opis Filtruj schemat tekstu Obsługiwane wartości
Prawda/fałsz Umożliwia tworzenie trasy bez filtrowania lub wyłączanie trasy, dzięki czemu żadne zdarzenia nie są wysyłane <true/false> true = trasa jest włączona bez filtrowania
false = trasa jest wyłączona
Typ Typ zdarzenia przepływającego przez wystąpienie cyfrowej reprezentacji bliźniaczej type = '<event-type>' Poniżej przedstawiono możliwe wartości typów zdarzeń:
Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
Microsoft.DigitalTwins.Twin.Update
Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
microsoft.iot.telemetry
Źródło Nazwa wystąpienia usługi Azure Digital Twins source = '<host-name>' Poniżej przedstawiono możliwe wartości nazw hostów:

W przypadku powiadomień: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net

W przypadku telemetrii: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Temat Opis zdarzenia w kontekście powyższego źródła zdarzeń subject = '<subject>' Poniżej przedstawiono możliwe wartości podmiotu:

W przypadku powiadomień: Temat jest <twin-ID>
lub format identyfikatora URI dla podmiotów, które są jednoznacznie identyfikowane przez wiele części lub identyfikatorów:
<twin-ID>/relationships/<relationship-ID>

W przypadku telemetrii: temat jest ścieżką składnika (jeśli telemetria jest emitowana ze składnika bliźniaczej reprezentacji), na przykład comp1.comp2. Jeśli dane telemetryczne nie są emitowane ze składnika, pole tematu jest puste.
Schemat danych Identyfikator modelu DTDL dataschema = '<model-dtmi-ID>' W przypadku danych telemetrycznych: schemat danych to identyfikator modelu bliźniaczej reprezentacji lub składnika, który emituje dane telemetryczne. Na przykład dtmi:example:com:floor4;2

W przypadku powiadomień (tworzenie/usuwanie): schemat danych można uzyskać w treści powiadomienia pod adresem $body.$metadata.$model.

W przypadku powiadomień (aktualizacja): dostęp do schematu danych można uzyskać w treści powiadomienia pod adresem $body.modelId
Typ zawartości Typ zawartości wartości danych datacontenttype = '<content-type>' Typ zawartości to application/json
Wersja specyfikacji Wersja używanego schematu zdarzeń specversion = '<version>' Wersja musi mieć wartość 1.0. Ta wartość wskazuje schemat CloudEvents w wersji 1.0
Treść powiadomienia Odwołuj się do data dowolnej właściwości w polu powiadomienia $body.<property> Zobacz Powiadomienia o zdarzeniach , aby zapoznać się z przykładami powiadomień. Przy użyciu dowolnej właściwości w data polu można odwoływać się $body

Uwaga

Usługa Azure Digital Twins obecnie nie obsługuje filtrowania zdarzeń na podstawie pól w tablicy. Obejmuje to filtrowanie właściwości w patch sekcji powiadomienia o zmianie cyfrowej reprezentacji bliźniaczej.

Następujące typy danych są obsługiwane jako wartości zwracane przez odwołania do powyższych danych:

Typ danych Przykład
String STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
CONTAINS(subject, '<twin-ID>')
Liczba całkowita $body.errorCode > 200
Liczba rzeczywista $body.temperature <= 5.5
Bool $body.poweredOn = true
Null (zero) $body.prop != null

Następujące operatory są obsługiwane podczas definiowania filtrów tras:

Rodzina Operatory Przykład
Wartość logiczna AND, OR, ( ) (type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Porównanie <, <=, >, >=, =, != $body.temperature <= 5.5

Podczas definiowania filtrów tras obsługiwane są następujące funkcje:

Function opis Przykład
STARTS_WITH(x,y) Zwraca wartość true, jeśli wartość x rozpoczyna się od ciągu y. STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y) Zwraca wartość true, jeśli wartość x kończy się ciągiem y. ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y) Zwraca wartość true, jeśli wartość x zawiera ciąg y. CONTAINS(subject, '<twin-ID>')

Podczas implementowania lub aktualizowania filtru zmiana może potrwać kilka minut, aby odzwierciedlić je w potoku danych.

Monitorowanie tras zdarzeń

Metryki routingu, takie jak liczba, opóźnienia i szybkość awarii, można wyświetlić w witrynie Azure Portal.

Aby uzyskać informacje na temat wyświetlania metryk i zarządzania nimi za pomocą usługi Azure Monitor, zobacz Rozpoczynanie pracy z eksploratorem metryk. Aby uzyskać pełną listę metryk routingu dostępnych dla usługi Azure Digital Twins, zobacz Azure Digital Twins routing metrics (Metryki routingu usługi Azure Digital Twins).

Następne kroki

Przeczytaj o różnych typach komunikatów zdarzeń, które można odbierać: