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.

  

• 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

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

Portal

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.

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

Interfejs wiersza polecenia

Trasy można zarządzać za pomocą poleceń az dt route dla interfejsu wiersza polecenia usługi Azure Digital Twins.

Aby uzyskać więcej informacji na temat korzystania z interfejsu wiersza polecenia i dostępnych poleceń, zobacz Zestaw poleceń interfejsu wiersza polecenia usługi Azure Digital Twins.

Zestaw SDK platformy .NET

W tej sekcji pokazano, jak utworzyć trasę zdarzeń przy użyciu zestawu SDK platformy .NET (C#).

CreateOrReplaceEventRouteAsync to wywołanie zestawu SDK używane do dodawania trasy zdarzeń. Oto przykład użycia:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

Napiwek

Wszystkie funkcje zestawu SDK są dostępne w wersjach synchronicznych i asynchronicznych.

Przykładowy kod zestawu SDK trasy zdarzeń

Poniższa przykładowa metoda pokazuje, jak utworzyć, wyświetlić listę i usunąć trasę zdarzeń przy użyciu zestawu SDK języka C#:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

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.

Portal

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.

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

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 :

API

Interfejsy API płaszczyzny danych tras zdarzeń umożliwiają zapisywanie filtrów niestandardowych. Aby dodać filtr, możesz użyć żądania PUT do https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 z następującą treścią:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

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

• Powiadomienia o zdarzeniach