Erstellen von Ereignisrouten und -filtern in Azure Digital Twins
In diesem Artikel wird der Prozess zum Erstellen von Ereignisrouten mithilfe des Azure-Portals, der Azure CLI-Befehle vom Typ „az dt route“, der Datenebenen-APIs für Ereignisrouten und des .NET (C#) SDK erläutert.
Das Routing von Ereignisbenachrichtigungen von Azure Digital Twins an nachgeschaltete Dienste oder verbundene Computeressourcen ist ein zweistufiger Prozess: Zuerst müssen Endpunkte erstellt werden und danach Ereignisrouten, um Daten an diese Endpunkte zu senden. In diesem Artikel wird der zweite Schritt behandelt, in dem 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 anhand der Anweisungen unter Erstellen von Endpunkten. In diesem Artikel erstellen Sie eine Route zum Senden von Daten an diesen Endpunkt.
Befolgen Sie als Nächstes die nachstehenden Anweisungen, wenn Sie die Azure-Befehlszeilenschnittstelle verwenden möchten, während Sie diesen Leitfaden befolgen.
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 gerade erst bereitgestellt haben, vergewissern Sie sich, dass die Bereitstellung abgeschlossen ist, bevor Sie versuchen, die Endpunkte 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.
- Um die Route zu deaktivieren, damit keine Ereignisse gesendet werden, verwenden Sie den Filterwert
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.
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 unter Verwendung 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. Für Telemetriefilter bedeutet dies, dass die Groß-/Kleinschreibung mit der Groß-/Kleinschreibung in den vom Gerät gesendeten Telemetriedaten übereinstimmen muss.
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:
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. |
| type | Der Ereignistyp, der durch Ihre digitale Zwillingsinstanz fließt. | type = '<event-type>' |
Folgende Werte für Ereignistypen sind möglich: Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.UpdateMicrosoft.DigitalTwins.Relationship.CreateMicrosoft.DigitalTwins.Relationship.UpdateMicrosoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry |
| Quelle | Der Name der Azure Digital Twins-Instanz. | source = '<host-name>' |
Dies sind die möglichen Werte für Hostnamen: 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>' |
Folgende Werte für den Betreff sind möglich: 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>') |
| Ganzzahl | $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: