Erstellen von Ereignisrouten und Filtern in Azure Digital Twins

Artikel
01/03/2024

Dieser Artikel führt Sie durch den Prozess des Erstellens von Ereignisrouten mithilfe der Azure-Portal, Azure CLI az dt Route-Befehle, Event Routes-Datenebenen-APIs und des .NET (C#)-SDK.

Das Routing von Ereignisbenachrichtigungen von Azure Digital Twins an nachgeschaltete Dienste oder verbundene Computeressourcen ist ein zweistufiger Prozess: Erstellen von Endpunkten und Erstellen von Ereignisrouten zum Senden von Daten an diese Endpunkte. In diesem Artikel wird der zweite Schritt behandelt, indem Routen eingerichtet werden, um zu steuern, welche Ereignisse an welche Azure Digital Twin-Endpunkte übermittelt werden. Um mit diesem Artikel fortzufahren, sollten Sie bereits Endpunkte erstellt haben.

Voraussetzungen

Sie benötigen ein Azure-Konto, das Sie kostenlos einrichten können.
Sie benötigen eine Azure Digital Twins-Instanz in Ihrem Azure-Abonnement. Falls Sie noch keine Instanz besitzen, können Sie zum Erstellen die Schritte in Einrichten einer Instanz und Authentifizierung befolgen. Notieren Sie sich die folgenden Werte aus dem Setup, um sie später in diesem Artikel zu verwenden:
- Instanzname
- Resource group
Nachdem Sie Ihre Instanz eingerichtet haben, können Sie diese Details im Azure-Portal anzeigen.
Erstellen Sie einen Endpunkt mithilfe der Anweisungen in "Endpunkte erstellen". In diesem Artikel erstellen Sie eine Route zum Senden von Daten an diesen Endpunkt.

Folgen Sie als Nächstes den nachstehenden Anweisungen, wenn Sie beabsichtigen, die Azure CLI zu verwenden, während Sie diesem Leitfaden folgen.

Vorbereiten der Umgebung für die Azure CLI

Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.
- Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Erstellen einer Ereignisroute

Nach dem Erstellen eines Endpunkts müssen Sie eine Ereignisroute definieren, um tatsächlich Daten an den Endpunkt zu senden. Diese Routen ermöglichen es Entwicklern, den Ereignisdatenfluss im gesamten System und zu Downstreamdiensten einzurichten. Eine einzelne Route kann es ermöglichen, dass mehrere Benachrichtigungen und Ereignistypen ausgewählt werden. Weitere Informationen zu Ereignisrouten finden Sie unter Endpunkte und Ereignisrouten.

Hinweis

Stellen Sie sicher, dass Sie mindestens einen Endpunkt erstellt haben, wie in den Voraussetzungen beschrieben, bevor Sie mit dem Erstellen einer Route fortfahren.

Wenn Sie Ihre Endpunkte erst kürzlich bereitgestellt haben, überprüfen Sie, ob sie die Bereitstellung abgeschlossen haben, bevor Sie versuchen, sie für eine neue Ereignisroute zu verwenden. Wenn die Routenbereitstellung fehlschlägt, weil die Endpunkte noch nicht bereit sind, warten Sie einige Minuten, und versuchen Sie es dann erneut.

Wenn Sie eine Skripterstellung für diesen Flow durchführen, sollten Sie dies berücksichtigen, indem Sie eine Wartezeit von zwei bis drei Minuten vorsehen, damit der Endpunktdienst die Bereitstellung abschließen kann, bevor mit der Routeneinrichtung fortgefahren wird.

Eine Routendefinition kann folgende Elemente enthalten:

Den Routennamen, den Sie verwenden möchten.
Den Namen des Endpunkts, den Sie verwenden möchten.
Ein Filter, der definiert, welche Ereignisse an den Endpunkt gesendet werden
- Um die Route zu deaktivieren, damit keine Ereignisse gesendet werden, verwenden Sie den Filterwert false.
- Um eine Route zu aktivieren, für die keine bestimmte Filterung gilt, verwenden Sie den Filterwert true.
- Ausführliche Informationen zu allen anderen Filtertypen finden Sie unten im Abschnitt Filtern von Ereignissen.

Wenn es keinen Routennamen gibt, werden keine Nachrichten außerhalb von Azure Digital Twins weitergeleitet. Wenn es einen Routennamen gibt und der Filter true lautet, werden alle Nachrichten an den Endpunkt weitergeleitet. Wenn es einen Routennamen gibt und ein anderer Filter hinzugefügt wird, werden Nachrichten auf der Grundlage des Filters gefiltert.

Ereignisrouten können mit dem Azure-Portal, den EventRoutes-Datenebenen-APIs oder den az dt route-CLI-Befehlen erstellt werden. Der Rest dieses Abschnitts führt Sie durch den Erstellungsprozess.

Navigieren Sie zum Erstellen einer Ereignisroute im Azure-Portal zur Detailseite für Ihre Azure Digital Twins-Instanz. (Sie können auf die Instanz zugreifen, indem Sie ihren Namen im Portal in der Suchleiste eingeben.)

Wählen Sie im Instanzmenü die Option Ereignisrouten aus. Wählen Sie anschließend auf der Seite Ereignisrouten die Option + Create an event route (+ Ereignisroute erstellen) aus.

Wählen Sie auf der Seite Create an event route (Ereignisroute erstellen) mindestens Folgendes aus:

Einen Namen für Ihre Route im Feld Name.
Den Endpunkt, den Sie zum Erstellen der Route verwenden möchten.

Zum Aktivieren der Route müssen Sie auch einen Ereignisroutenfilter hinzufügen, für den mindestens true festgelegt ist. (Wenn Sie den Standardwert false beibehalten, wird die Route erstellt, aber es werden keine Ereignisse dafür gesendet.) Verwenden Sie hierfür den Umschalter für Erweiterter Editor, um ihn zu aktivieren, und geben Sie im Feld Filter die Zeichenfolge true ein.

Wählen Sie nach Abschluss des Vorgangs die Schaltfläche Speichern aus, um Ihre Ereignisroute zu erstellen.

In diesem Abschnitt wird gezeigt, wie Sie eine Ereignisroute mit dem .NET SDK (C#) erstellen.

CreateOrReplaceEventRouteAsync ist der SDK-Aufruf, der zum Hinzufügen einer Ereignisroute verwendet wird. Hier ist ein Beispiel für seine Verwendung:

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

Tipp

Alle SDK-Funktionen sind in synchronen und asynchronen Versionen enthalten.

Beispielcode für Ereignisroute mit SDK

Die folgende Beispielmethode zeigt, wie Sie eine Ereignisroute mit dem C#-SDK erstellen, auflisten und löschen:

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}");
    }
}

Filtern von Ereignissen

Wie oben beschrieben, verfügen Routen über das Feld Filter. Wenn der Filterwert für Ihre Route false lautet, werden keine Ereignisse an Ihren Endpunkt gesendet.

Nachdem mindestens true als Filterwert ausgewählt wurde, erhalten Endpunkte verschiedene Arten von Ereignissen von Azure Digital Twins:

Telemetrie, die von digitalen Zwillingen mit der Azure Digital Twins-Dienst-API ausgelöst wird
Änderungsbenachrichtigungen für Zwillingseigenschaften, ausgelöst bei Eigenschaftsänderungen für einen Zwilling in der Azure Digital Twins-Instanz.
Lebenszyklusereignisse, die ausgelöst werden, wenn Zwillinge oder Beziehungen erstellt oder gelöscht werden.

Sie können die Ereignistypen beschränken, die gesendet werden, indem Sie einen spezifischeren Filter definieren.

Hinweis

Filter unterscheiden zwischen Groß- und Kleinschreibung und müssen mit der Groß-/Kleinschreibung der Nutzlast übereinstimmen. Bei Telemetriefiltern bedeutet dies, dass die Groß-/Kleinschreibung mit der Groß-/Kleinschreibung in der vom Gerät gesendeten Telemetrie übereinstimmen muss.

Portal
API

Verwenden Sie auf der Seite Ereignisroute erstellen den Abschnitt Ereignisroutenfilter hinzufügen, um beim Erstellen einer Ereignisroute einen Ereignisfilter hinzuzufügen.

Sie können entweder eine Auswahl aus einigen grundlegenden allgemeinen Filteroptionen treffen oder die erweiterten Filteroptionen verwenden, um Ihre eigenen benutzerdefinierten Filter zu schreiben.

Verwenden der grundlegenden Filter

Erweitern Sie zur Verwendung der grundlegenden Filter die Option Ereignistypen, und wählen Sie die Kontrollkästchen für die Ereignisse aus, die Sie an Ihren Endpunkt senden möchten.

Dies führt dazu, dass das Filtertextfeld automatisch mit dem Text des von Ihnen ausgewählten Filters gefüllt wird:

Verwenden der erweiterten Filter

Sie können auch die erweiterte Filteroption verwenden, um Ihre eigenen benutzerdefinierten Filter zu schreiben.

Aktivieren Sie Erweiterter Editor mit dem Umschalter, um ihn zu aktivieren, wenn Sie eine Ereignisroute mit erweiterten Filteroptionen erstellen möchten. Sie können im Feld Filter dann Ihre eigenen Ereignisfilter schreiben:

Sie können die Datenebenen-APIs für Ereignisrouten verwenden, um benutzerdefinierte Filter zu schreiben. Um einen Filter hinzuzufügen, können Sie eine PUT-Anforderung https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 mit dem folgenden Textkörper verwenden:

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

Unterstützte Routenfilter

Dies sind die unterstützten Routenfilter.

Filtername	Beschreibung	Filtertextschema	Unterstützte Werte
True/False	Ermöglicht das Erstellen einer Route ohne Filterung oder das Deaktivieren einer Route, sodass keine Ereignisse gesendet werden.	`<true/false>`	`true` = Route ist ohne Filterung aktiviert. `false` = Route ist deaktiviert.
Typ	Der Ereignistyp, der durch Ihre digitale Zwillingsinstanz fließt.	`type = '<event-type>'`	Hier sind die möglichen Ereignistypwerte: `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`
Quelle	Der Name der Azure Digital Twins-Instanz.	`source = '<host-name>'`	Hier sind die möglichen Hostnamenwerte: Für Benachrichtigungen: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` Für Telemetrie: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
Betreff	Eine Beschreibung des Ereignisses im Zusammenhang mit der oben genannten Ereignisquelle.	`subject = '<subject>'`	Hier sind die möglichen Betreffwerte: Für Benachrichtigungen: Der Betreff ist `<twin-ID>`. oder ein URI-Format für Betreffelemente, die durch mehrere Teile oder IDs eindeutig identifiziert werden: `<twin-ID>/relationships/<relationship-ID>` Für Telemetrie: Der Betreff ist der Komponentenpfad (wenn die Telemetrie von einer Zwillingskomponente ausgegeben wird), z. B. `comp1.comp2`. Wenn die Telemetrie nicht von einer Komponente ausgegeben wird, dann ist ihr Betrefffeld leer.
Datenschema	DTDL-Modell-ID	`dataschema = '<model-dtmi-ID>'`	Für Telemetrie: Das Datenschema ist die Modell-ID des Zwillings oder der Komponente, der bzw. die die Telemetrie ausgibt. Beispiel: `dtmi:example:com:floor4;2` Für Benachrichtigungen (Erstellen/Löschen): Der Zugriff auf das Datenschema kann im Benachrichtigungstext unter `$body.$metadata.$model` erfolgen. Für Benachrichtigungen (Aktualisieren): Der Zugriff auf das Datenschema kann im Benachrichtigungstext unter `$body.modelId` erfolgen.
Inhaltstyp	Der Inhaltstyp des Datenwerts.	`datacontenttype = '<content-type>'`	Der Inhaltstyp lautet `application/json`.
Spezifikationsversion	Die Version des von Ihnen verwendeten Ereignisschemas	`specversion = '<version>'`	Die Version muss `1.0` sein. Dieser Wert gibt das CloudEvents-Schema, Version 1.0, an.
Benachrichtigungstext	Verweisen auf eine beliebige Eigenschaft im Feld `data` einer Benachrichtigung.	`$body.<property>`	Beispiele für Benachrichtigungen finden Sie unter Ereignisbenachrichtigungen. Auf jede Eigenschaft im Feld `data` kann mit `$body` verwiesen werden.

Hinweis

Azure Digital Twins unterstützt derzeit kein Filtern von Ereignissen basierend auf Feldern innerhalb eines Arrays. Dies schließt auch das Filtern nach Eigenschaften innerhalb eines patch-Abschnitts einer Änderungsbenachrichtigung für digitale Zwillinge ein.

Die folgenden Datentypen werden als Werte unterstützt, die von Verweisen auf die oben aufgeführten Daten zurückgegeben werden:

Datentyp	Beispiel
String	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Integer	`$body.errorCode > 200`
Double	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Null	`$body.prop != null`

Die folgenden Operatoren werden beim Definieren von Routenfiltern unterstützt:

Familie	Operatoren	Beispiel
Logisch	AND, OR, ( )	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
Vergleich	<, <=, >, >=, =, !=	`$body.temperature <= 5.5`

Die folgenden Funktionen werden beim Definieren von Routenfiltern unterstützt:

Funktion	Description	Beispiel
STARTS_WITH(x,y)	Gibt TRUE zurück, wenn der Wert `x` mit der Zeichenfolge `y` beginnt.	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
ENDS_WITH(x,y)	Gibt TRUE zurück, wenn der Wert `x` mit der Zeichenfolge `y` endet.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
CONTAINS(x,y)	Gibt TRUE zurück, wenn der Wert `x` die Zeichenfolge `y` enthält.	`CONTAINS(subject, '<twin-ID>')`

Wenn Sie einen Filter implementieren oder aktualisieren, kann es einige Minuten dauern, bis sich die Änderung in der Datenpipeline widerspiegelt.

Überwachen von Ereignisrouten

Routingmetriken wie Anzahl, Wartezeit und Ausfallrate können im Azure-Portal angezeigt werden.

Informationen zum Anzeigen und Verwalten von Metriken mit Azure Monitor finden Sie unter Erste Schritte mit dem Metrik-Explorer. Eine vollständige Liste der für Azure Digital Twins verfügbaren Routingmetriken finden Sie unter Azure Digital Twins-Routingmetriken.

Nächste Schritte

Informieren Sie sich über die verschiedenen Arten von Ereignismeldungen, die Sie erhalten können:

Ereignisbenachrichtigungen

Erstellen von Ereignisrouten und Filtern in Azure Digital Twins

Voraussetzungen

Vorbereiten der Umgebung für die Azure CLI

Erstellen einer Ereignisroute

Filtern von Ereignissen

Verwenden der grundlegenden Filter

Verwenden der erweiterten Filter

Unterstützte Routenfilter

Überwachen von Ereignisrouten

Nächste Schritte

Zusätzliche Ressourcen