Einrichten der Verarbeitung von Ereignissen zwischen Zwillingen
In diesem Artikel wird das Senden von Ereignissen zwischen Zwillingen gezeigt, damit im Falle einer Aktualisierung des digitalen Zwillings die zugehörigen Zwillinge im Graphen, für die diese Information relevant ist, ebenfalls aktualisiert werden können. Diese Ereignisbehandlung ist hilfreich, wenn Sie einen vollständig verbundenen Azure Digital Twins-Graphen erstellen möchten, in dem Daten, die aus externen Quellen wie IoT Hub bei Azure Digital Twins eingehen, über den gesamten Graphen verteilt werden.
Für diese zwillingsübergreifende Ereignisbehandlung muss eine Azure-Funktion zur Überwachung auf Lebenszyklusereignisse für Zwillinge erstellt werden. Die Funktion erkennt, welche Ereignisse sich auf andere Zwillinge im Graphen auswirken, und verwendet die Ereignisdaten, um die betroffenen Zwillinge entsprechend zu aktualisieren.
Voraussetzungen
Um die Verarbeitung von Ereignissen zwischen Zwillingen einzurichten, benötigen Sie eine Azure Digital Twins-Instanz. Informationen über das Erstellen einer Azure Digital Twins-Instanz erhalten Sie unter Einrichten einer Azure Digital Twins-Instanz und der Authentifizierung. Die Instanz sollte mindestens zwei Zwillinge enthalten, zwischen denen Sie Daten senden wollen.
Optional können Sie außerdem die automatische Telemetriedatenerfassung über IoT Hub für Ihre Zwillinge einrichten. Dieser Vorgang ist zwar nicht erforderlich, um Daten von einem Zwilling an einen anderen zu senden, aber es ist ein wichtiger Bestandteil einer vollständigen Lösung, bei der der Zwillingsgraph durch Livetelemetriedaten des Geräts gesteuert wird.
Senden von Zwillingsereignissen an einen Endpunkt
Um die Ereignisverarbeitung zwischen Zwillingen einzurichten, müssen Sie zunächst einen Endpunkt in Azure Digital Twins sowie eine Route zu diesem Endpunkt erstellen. Zwillinge, die aktualisiert werden, nutzen die Route, um Informationen über ihre Updateereignisse an den Endpunkt zu senden (von dort kann Event Grid sie später abholen und zur Verarbeitung an eine Azure-Funktion übergeben).
Erstellen des Event Grid-Themas
Event Grid ist ein Azure-Dienst, mit dem Sie von Azure-Diensten stammende Ereignisse an andere Orte in Azure weiterleiten und übermitteln können. Sie können ein Event Grid-Thema erstellen, um bestimmte Ereignisse von einer Quelle zu erfassen. Abonnementdatenbanken können dann über das Thema lauschen, um Ereignisse abzurufen, sobald sie verfügbar sind.
Führen Sie in der Azure CLI den folgenden Befehl aus, um ein Event Grid-Thema zu erstellen:
az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>
Die Ausgabe dieses Befehls enthält Informationen zum von Ihnen erstellten Event Grid-Thema. Speichern Sie den Namen, den Sie Ihrem Event Grid-Thema gegeben haben, da Sie ihn später benötigen.
Erstellen des Endpunkts
Erstellen Sie als Nächstes einen Event Grid-Endpunkt in Azure Digital Twins, über den Ihre Instanz mit Ihrem Event Grid-Thema verbunden wird. Verwenden Sie den folgenden Befehl. Geben Sie dabei den Namen Ihres Event Grid-Themas aus dem vorherigen Schritt an, und füllen Sie bei Bedarf die weiteren Platzhalterfelder aus.
az dt endpoint create eventgrid --dt-name <Azure-Digital-Twins-instance> --eventgrid-resource-group <your-resource-group> --eventgrid-topic <your-event-grid-topic> --endpoint-name <name-for-your-Azure-Digital-Twins-endpoint>
Die Ausgabe dieses Befehls enthält Informationen zum von Ihnen erstellten Endpunkt.
Suchen Sie in der Ausgabe nach dem Feld provisioningState, und vergewissern Sie sich, dass der Wert „Succeeded“ (Erfolgreich) lautet.
Er kann auch „Provisioning“ lauten. Dies bedeutet, dass die Erstellung des Endpunkts noch nicht abgeschlossen ist. Falls ja, warten Sie einige Sekunden, und führen Sie den folgenden Befehl aus, um den Status des Endpunkts zu überprüfen. Wiederholen Sie diesen Schritt, bis provisioningState den Wert „Succeeded“ (Erfolgreich) hat.
az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint>
Speichern Sie den Namen Ihres Endpunkts für später.
Erstellen der Route
Erstellen Sie als Nächstes eine Azure Digital Twins-Route, über die Ereignisse an den von Ihnen erstellten Event Grid-Endpunkt gesendet werden.
Verwenden Sie den folgenden CLI-Befehl. Geben Sie dabei den Namen Ihres Endpunkts aus dem vorherigen Schritt an, und füllen Sie bei Bedarf die weiteren Platzhalterfelder aus. Durch diesen Befehl werden alle Ereignisse weitergeleitet, die im Zwillingsgraphen auftreten.
Tipp
Auf Wunsch können die Ereignisse mithilfe von Filtern auf bestimmte Ereignisse beschränkt werden.
az dt route create --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> --route-name <name-for-your-Azure-Digital-Twins-route>
Die Ausgabe dieses Befehls enthält einige Informationen zur von Ihnen erstellten Route.
Hinweis
Die Bereitstellung der Endpunkte (aus dem vorherigen Schritt) muss abgeschlossen sein, bevor Sie eine Ereignisroute einrichten können, in der diese verwendet werden. Wenn die Routenerstellung fehlschlägt, weil die Endpunkte noch nicht bereit sind, sollten Sie einige Minuten warten und es dann erneut versuchen.
Erstellen einer Azure-Funktion zum Aktualisieren von Zwillingen
Erstellen Sie als Nächstes eine Azure-Funktion, die am Endpunkt lauscht und die Ereignisse der Zwillinge empfängt, die über die Route dorthin gesendet werden. Die Logik der Funktion muss anhand der Informationen in den Ereignissen bestimmen, welche anderen Zwillinge aktualisiert werden müssen, und dann die Aktualisierungen vornehmen.
Erstellen Sie zuerst ein neues Azure Functions-Projekt.
Dazu können Sie Folgendes verwenden: Visual Studio (Anweisungen finden Sie unter Entwickeln von Azure Functions mithilfe von Visual Studio), Visual Studio Code (Anweisungen finden Sie unter Erstellen einer C#-Funktion in Azure mit Visual Studio Code) oder die Azure CLI (Anweisungen finden Sie unter Erstellen einer C#-Funktion über die Befehlszeile in Azure).
Fügen Sie Ihrem Projekt die folgenden Pakete hinzu (Sie können dazu den Visual Studio NuGet-Paket-Manager oder den Befehl dotnet add package in einem Befehlszeilentool verwenden).
Füllen Sie die Logik Ihrer Funktion aus. Um den Einstieg zu erleichtern, können Sie sich Funktionscodebeispiele für mehrere Szenarien im Repository azure-digital-twins-getting-started ansehen.
Veröffentlichen Sie die Funktion mit der von Ihnen bevorzugten Methode in Azure.
Anweisungen zum Veröffentlichen der Funktion mithilfe von Visual Studio finden Sie unter Entwickeln von Azure Functions mithilfe von Visual Studio. Anweisungen zum Veröffentlichen der Funktion mithilfe von Visual Studio Code finden Sie unter Erstellen einer C#-Funktion in Azure mit Visual Studio Code. Anweisungen zum Veröffentlichen der Funktion mithilfe der Azure CLI finden Sie unter Erstellen einer C#-Funktion über die Befehlszeile in Azure.
Sobald der Prozess der Veröffentlichung der Funktion abgeschlossen ist, können Sie mithilfe dieses Azure CLI-Befehls überprüfen, ob die Veröffentlichung erfolgreich war. Es gibt Platzhalter für Ihre Ressourcengruppe, den Namen Ihrer Funktions-App und den Namen Ihrer spezifischen Funktion. Der Befehl gibt Informationen zu Ihrer Funktion aus.
az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name <your-function>
Konfigurieren der Funktions-App
Bevor Ihre Funktion auf Azure Digital Twins zugreifen kann, benötigt sie einige Informationen über die Instanz und die notwendige Zugriffsberechtigung. In diesem Abschnitt weisen Sie eine Zugriffsrolle für die Funktion zu, und konfigurieren die Anwendungseinstellungen, damit sie die Instanz finden und darauf zugreifen kann.
Führen Sie die folgenden Befehle in Azure Cloud Shell oder einer lokalen Installation der Azure CLI aus.
Hinweis
Dieser Abschnitt muss von einem Azure-Benutzer durchgeführt werden, der über die nötigen Berechtigungen zum Verwalten des Benutzerzugriffs auf Azure-Ressourcen (einschließlich des Gewährens und Delegieren von Berechtigungen) verfügt. Allgemeine Rollen, die diese Anforderung erfüllen, heißen Besitzer oder Kontoadministrator. Ebenso können die beiden Rollen Benutzerzugriffsadministrator und Mitwirkender kombiniert werden. Weitere Informationen zu den erforderlichen Berechtigungen für Azure Digital Twins-Rollen finden Sie unter Einrichten einer Azure Digital Twins-Instanz und der Authentifizierung (Portal).
Zuweisen einer Zugriffsrolle
Die Azure-Funktion erfordert die Übergabe eines Bearertokens. Um sicherzustellen, dass das Bearertoken übergeben wird, erteilen Sie der Funktions-App die Rolle Azure Digital Twins-Datenbesitzer für Ihre Azure Digital Twins-Instanz, die der Funktions-App die Berechtigung zum Ausführen von Datenebenenaktivitäten für die Instanz erteilt.
Verwenden Sie den folgenden Befehl, um eine systemseitig verwaltete Identität für Ihre Funktion zu erstellen (wenn die Funktion bereits über eine verfügt, gibt dieser Befehl deren Details aus). Notieren Sie sich das Feld
principalIdin der Ausgabe. Sie verwenden diese ID, um auf die Funktion zu verweisen, damit Sie ihr im nächsten Schritt Berechtigungen erteilen können.az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>Verwenden Sie den Wert
principalIdim folgenden Befehl, um der Funktion die Rolle Azure Digital Twins-Datenbesitzer für Ihre Azure Digital Twins-Instanz zuzuweisen.az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
Konfigurieren von Anwendungseinstellungen
Ermöglichen Sie Ihrer Funktion dann den Zugriff auf die URL Ihrer Azure Digital Twins-Instanz, indem Sie eine Umgebungsvariable für sie festlegen.
Tipp
Die URL der Azure Digital Twins-Instanz wird durch das Hinzufügen von https:// am Anfang des Hostnamens der Instanz erstellt. Um den Hostnamen mit allen Eigenschaften der Instanz anzuzeigen, führen Sie Folgendes aus: az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Der folgende Befehl legt eine Umgebungsvariable für die URL Ihrer Instanz fest, die Ihre Funktion immer dann verwendet, wenn sie auf die Instanz zugreifen muss.
az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"
Verbinden der Funktion mit dem Endpunkt
Abonnieren Sie als Nächstes Ihre Azure-Funktion für den zuvor erstellten Event Grid-Endpunkt. Dadurch wird sichergestellt, dass Daten von einem aktualisierten Zwilling über das Event Grid-Thema zu der Funktion gelangen. Die Funktion kann dann die Ereignisinformationen verwenden, um andere Zwillinge nach Bedarf zu aktualisieren.
Zum Abonnieren Ihrer Azure-Funktion wird ein Event Grid-Abonnement erstellt, das Daten aus dem zuvor erstellten Event Grid-Thema an Ihre Azure-Funktion sendet.
Verwenden Sie den folgenden CLI-Befehl und geben Sie Platzhalter für Ihre Abonnement-ID, die Ressourcengruppe, die Funktions-App und den Funktionsnamen ein.
az eventgrid event-subscription create --name <name-for-your-event-subscription> --source-resource-id /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.EventGrid/topics/<your-event-grid-topic> --endpoint-type azurefunction --endpoint /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app-name>/functions/<function-name>
Nun kann Ihre Funktion Ereignisse über Ihr Event Grid-Thema empfangen. Die Einrichtung des Datenflusses ist damit abgeschlossen.
Testen und Überprüfen der Ergebnisse
Der letzte Schritt besteht darin, zu überprüfen, ob der Flow funktioniert. Dazu müssen Sie einen Zwilling aktualisieren und überprüfen, ob die zugehörigen Zwillinge gemäß der Logik in Ihrer Azure-Funktion ebenfalls aktualisiert werden.
Um den Prozess zu starten, aktualisieren Sie zunächst den Zwilling, der die Quelle des Ereignisflusses ist. Für das Update können Sie die Azure CLI, das Azure Digital Twins-SDK oder die Azure Digital Twins-REST APIs verwenden.
Senden Sie danach eine Abfrage zu dem zugehörigen Zwilling an Ihre Azure Digital Twins-Instanz. Dafür können Sie die Azure CLI oder die Azure Digital Twins-REST APIs und das SDK verwenden. Überprüfen Sie, ob der Zwilling die Daten empfangen hat und wie erwartet aktualisiert wurde.
Nächste Schritte
In diesem Artikel richten Sie die Ereignisverarbeitung zwischen Zwillingen in Azure Digital Twins ein. Richten Sie als Nächstes eine Azure-Funktion ein, um diesen Flow automatisch basierend auf den eingehenden Telemetriedaten von IoT Hub-Geräten auszulösen: Erfassen von Telemetriedaten aus IoT Hub.