Erstellen von Endpunkten in Azure Digital Twins
In diesem Artikel wird erläutert, wie Sie einen Endpunkt für Azure Digital Twin-Ereignisse mithilfe des Azure-Portals oder der Azure-Befehlszeilenschnittstelle erstellen. Sie können Endpunkte auch mit den DigitalTwinsEndpoint-Steuerungsebenen-APIs verwalten.
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 erste Schritt behandelt, in dem Endpunkte eingerichtet werden, die Ereignisse empfangen können. Anschließend können Sie Ereignisrouten erstellen, die angeben, welche von Azure Digital Twins generierten Ereignisse an welche Endpunkte übermittelt werden.
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.
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 der erforderlichen Ressourcen
Die folgenden Dienste sind die unterstützten Typen von Endpunkten, die Sie für Ihre Instanz erstellen können:
- Event Grid thema
- Für Event Grid-Endpunkte werden nur Event Grid-Themen unterstützt. Event Grid-Domänen werden nicht als Endpunkte unterstützt.
- Event Hubs hub
- Service Bus-Topic
Das für den Endpunkt verwendete Event Grid-, Event Hub- oder Service Bus-Thema muss bereits vorhanden sein, um einen Endpunkt mit Azure Digital Twins zu verknüpfen.
Verwenden Sie die folgenden Tabelle, um herauszufinden, welche Ressourcen eingerichtet werden sollten, bevor Sie den Endpunkt erstellen.
| Endpunkttyp | Erforderliche Ressourcen (mit Erstellungsanweisungen verknüpft) |
|---|---|
| Event Grid-Endpunkt | Event Grid-Thema *Ereignisschema muss Event Grid Schema oder Cloud Event Schema v1.0 sein |
| Event Hubs-Endpunkt | Event Hubs-Namespace Event Hub (Optional) Autorisierungsregel für schlüsselbasierte Authentifizierung |
| Service Bus-Endpunkt | Service Bus-Namespace Service Bus-Topic (Optional) Autorisierungsregel für schlüsselbasierte Authentifizierung |
Erstellen des Endpunkts
Sobald Sie die Endpunktressourcen erstellt haben, können Sie sie für einen Azure Digital Twins-Endpunkt verwenden.
Navigieren Sie im Azure-Portal zur Seite Ihrer Instanz, um einen neuen Endpunkt zu erstellen. Die Instanz finden Sie, indem Sie ihren Namen in die Suchleiste im Portal eingeben.
Wählen Sie im Instanzmenü die Option Endpunkte aus. Wählen Sie anschließend auf der darauffolgenden Seite Endpunkte die Option + Endpunkt erstellen aus. Dadurch wird die Seite Endpunkt erstellen geöffnet. Dort füllen Sie in den nächsten Schritten die Felder aus.
Geben Sie einen Namen für Ihren Endpunkt ein, und wählen Sie den Endpunkttyp.
Geben Sie die restlichen für Ihren Endpunkttyp erforderlichen Informationen an, einschließlich Ihres Abonnements und der oben beschriebenen Endpunktressourcen.
- Nur für Event Hubs- und Service Bus-Endpunkte müssen Sie einen Authentifizierungstyp auswählen. Sie können die schlüsselbasierte Authentifizierung mit einer vorab erstellten Autorisierungsregel oder eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität verwenden. Weitere Informationen zur Verwendung der Identitätsauthentifizierungsoptionen finden Sie unter Endpunktoptionen: Identitätsbasierte Authentifizierung.
Schließen Sie die Erstellung Ihres Endpunkts ab, indem Sie auf Speichern klicken.
Nach Erstellung Ihres Endpunkts können Sie überprüfen, ob der Endpunkt erfolgreich erstellt wurde, indem Sie das Benachrichtigungssymbol oben in der Leiste im Azure-Portal überprüfen:
Falls bei der Erstellung des Endpunkts ein Fehler auftritt, sollten Sie die Fehlermeldung beachten und den Vorgang nach einigen Minuten wiederholen.
Sie können auch den Endpunkt anzeigen, der erstellt wurde, indem Sie auf der Seite Endpunkte für Ihre Azure Digital Twins-Instanz nachsehen.
Nun ist das Event Grid-, Event Hub- oder Service Bus-Thema als Endpunkt in Azure Digital Twins unter dem Namen verfügbar, den Sie für den Endpunkt ausgewählt haben. Normalerweise verwenden Sie diesen Namen als Ziel einer Ereignisroute, die Sie in Routen und Filter erstellen erstellen können.
Endpunktoptionen: Identitätsbasierte Authentifizierung
In diesem Abschnitt wird beschrieben, wie Sie eine verwaltete Identität für eine Azure Digital Twins-Instanz beim Weiterleiten von Ereignissen an unterstützte Routingziele verwenden. Das Einrichten einer verwalteten Identität ist für das Routing nicht erforderlich, aber es kann der Instanz helfen, einfach auf andere durch Microsoft Entra geschützte Ressourcen wie Event Hubs, Service Bus-Ziele und Azure Storage-Container zuzugreifen. Verwaltete Identitäten können systemseitig oder benutzerseitig zugewiesen werden.
Im restlichen Abschnitt werden die drei Schritte zum Einrichten eines Endpunkts mit einer verwalteten Identität beschrieben.
1. Aktivieren der verwalteten Identität für die Instanz
Verwenden Sie die nachstehenden Registerkarten, um Anweisungen zu Ihrer bevorzugten Benutzeroberfläche zu erhalten.
Stellen Sie zunächst sicher, dass Sie eine verwaltete Identität für Ihre Azure Digital Twins-Instanz aktiviert haben.
Vergewissern Sie sich außerdem, dass Sie über die Rolle Azure Digital Twins-Datenbesitzer für die Instanz verfügen. Anweisungen finden Sie unter Einrichten von Benutzerzugriffsberechtigungen.
2. Zuweisen von Azure-Rollen zur Identität
Nachdem Sie eine verwaltete Identität für Ihre Azure Digital Twins-Instanz erstellt haben, müssen Sie dieser die entsprechenden Rollen für die Authentifizierung bei verschiedenen Arten von Endpunkten zum Weiterleiten von Ereignissen an unterstützte Ziele zuweisen. In diesem Abschnitt werden die Rollenoptionen und deren Zuweisung an die verwaltete Identität beschrieben.
Wichtig
Sie müssen diesen Schritt unbedingt ausführen. Wenn Sie diesen Schritt nicht durchführen, kann die Identität nicht auf Ihre Endpunkte zugreifen, und es werden keine Ereignisse übermittelt.
Im Folgenden finden Sie die mindestens erforderlichen Rollen, die eine Azure Digital Twins-Identität je nach Art von Ziel für den Zugriff auf einen Endpunkt benötigt. Rollen mit höheren Berechtigungen (beispielsweise Datenbesitzerrollen) funktionieren ebenfalls.
| Destination | Azure-Rolle |
|---|---|
| Azure Event Hubs | Azure Event Hubs-Datensender |
| Azure Service Bus | Azure Service Bus-Datensender |
| Azure-Speichercontainer | Mitwirkender an Speicherblobdaten |
Verwenden Sie die folgenden Registerkarten, um die Rolle auf Ihrer bevorzugten Benutzeroberfläche zuzuweisen.
Öffnen Sie zum Zuweisen einer Rolle zur Identität zunächst das Azure-Portal in einem Browser.
Navigieren Sie zu Ihrer Endpunktressource (Event Hub-Instanz, Service Bus-Instanz oder Speichercontainer), indem Sie ihren Namen über die Suchleiste des Portals suchen.
Wählen Sie die Option Zugriffssteuerung (IAM) aus.
Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen aus, um den Bereich „Rollenzuweisung hinzufügen“ zu öffnen.
Weisen Sie der verwalteten Identität Ihrer Azure Digital Twins-Instanz mithilfe der folgenden Informationen die gewünschte Rolle zu. Ausführliche Informationen finden Sie unter Zuweisen von Azure-Rollen über das Azure-Portal.
Einstellung Wert Rolle Wählen Sie die gewünschte Rolle unter den Optionen aus. Zugriff zuweisen zu Verwaltete Identität Member Wählen Sie die benutzerseitig oder systemseitig zugewiesene verwaltete Identität Ihrer Azure Digital Twins-Instanz aus, der die Rolle zugewiesen wird. Eine benutzerseitig zugewiesene Identität hat den Namen, den Sie beim Erstellen der Identität ausgewählt haben, und eine systemseitig zugewiesene Identität hat einen Namen, der dem Namen Ihrer Azure Digital Twins-Instanz entspricht. 
3. Erstellen des Endpunkts mit identitätsbasierter Authentifizierung
Nachdem Sie eine verwaltete Identität für Ihre Azure Digital Twins-Instanz eingerichtet und dieser die entsprechenden Rollen zugewiesen haben, können Sie die Endpunkte erstellen, die diese Identität für die Authentifizierung verwenden. Diese Option ist nur für Event Hubs- und Service Bus-Endpunkte verfügbar. (Für Event Grid wird sie nicht unterstützt.)
Hinweis
Sie können einen Endpunkt nicht bearbeiten, der bereits mit einer schlüsselbasierten Identität erstellt wurde, um zur identitätsbasierten Authentifizierung zu wechseln. Sie müssen den Authentifizierungstyp auswählen, wenn der Endpunkt erstellt wird.
Verwenden Sie die folgenden Registerkarten, um den Endpunkt auf Ihrer bevorzugten Benutzeroberfläche zu erstellen.
Befolgen Sie zunächst die allgemeinen Anweisungen zum Erstellen eines Azure Digital Twins-Endpunkts.
Wenn Sie zum Schritt zum Eingeben der erforderlichen Informationen für Ihren Endpunkttyp gelangen, wählen Sie als Authentifizierungstyp entweder systemseitig zugewiesen oder benutzerseitig zugewiesen (Vorschau) aus.
Schließen Sie das Setup Ihres Endpunkts ab, und klicken Sie auf Speichern.
Überlegungen zum Deaktivieren verwalteter Identitäten
Da Identitäten separat von den Endpunkten verwaltet werden, die sie verwenden, ist es wichtig, dass die möglichen Auswirkungen von Änderungen an der Identität oder ihrer Rollen auf die Endpunkte Ihrer Azure Digital Twins-Instanz berücksichtigt werden. Wenn die Identität deaktiviert ist oder eine notwendige Rolle für einen Endpunkt entfernt wird, kann der Endpunkt unzugänglich und der Ablauf der Ereignisse unterbrochen werden.
Sie müssen den Endpunkt löschen und mit einem anderen Authentifizierungstyp neu erstellen, um einen Endpunkt weiterhin zu verwenden, der mit einer verwalteten Identität eingerichtet wurde, die deaktiviert wurde. Es kann bis zu eine Stunde dauern, bis Ereignisse nach dieser Änderung wieder an den Endpunkt übermittelt werden.
Endpunktoptionen: Unzustellbare Nachrichten
Wenn ein Endpunkt innerhalb eines bestimmten Zeitraums oder nach einer bestimmten Anzahl von Übermittlungsversuchen nicht übermittelt werden kann, kann Event Grid das nicht übermittelte Ereignis an ein Speicherkonto senden. Dieser Prozess wird als Speicherung unzustellbarer Nachrichten bezeichnet.
Sie können die erforderlichen Speicherressourcen mithilfe des Azure-Portals oder der Azure Digital Twins-CLI einrichten. Endpunkte mit aktivierter Funktion für unzustellbare Nachrichten müssen Sie jedoch mit der Azure Digital Twins-CLI oder mit Steuerungsebenen-APIs einrichten.
Weitere Informationen zu unzustellbaren Nachrichten finden Sie unter Endpunkte und Ereignisrouten. Anweisungen zum Einrichten eines Endpunkts mit unzustellbaren Nachrichten finden Sie im Rest dieses Abschnitts.
Einrichten von Speicherressourcen
Wenn Sie den Speicherort für unzustellbare Nachrichten festlegen möchten, benötigen Sie ein Speicherkonto mit einem Containersetup in Ihrem Azure-Konto.
Später geben Sie den URI für diesen Container an, wenn Sie den Endpunkt erstellen. Die Position der unzustellbaren Nachrichten wird dem Endpunkt als Container-URI mit einem SAS-Token bereitgestellt. Dieses Token benötigt die write-Berechtigung für den Zielcontainer innerhalb des Speicherkontos. Der vollständig formatierte SAS-URI für unzustellbare Nachrichten weist das Format https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token> auf.
Führen Sie die folgenden Schritte aus, um diese Speicherressourcen in Ihrem Azure-Konto einzurichten, um so die Einrichtung der Endpunktverbindung im nächsten Abschnitt vorzubereiten.
- Befolgen Sie die Schritte in Erstellen eines Speicherkontos, um ein Speicherkonto in Ihrem Azure-Abonnement zu erstellen. Notieren Sie den Namen des Speicherkontos zur späteren Verwendung.
- Befolgen Sie die Schritte in Erstellen eines Containers, um einen Container innerhalb des neuen Speicherkontos zu erstellen. Notieren Sie sich den Containernamen, um ihn später zu verwenden.
Erstellen eines SAS-Token
Erstellen Sie als nächstes ein SAS-Token für Ihr Speicherkonto, das der Endpunkt für den Zugriff darauf verwenden kann.
Navigieren Sie zunächst zu Ihrem Speicherkonto im Azure-Portal (Sie finden es über die Suchleiste im Portal).
Wählen Sie auf der Speicherkontoseite den Link Shared Access Signature in der linken Navigationsleiste, um mit der Einrichtung des SAS-Tokens zu beginnen.
Wählen Sie auf der Seite Shared Access Signature unter Zulässige Dienste und Zulässige Ressourcentypen die gewünschten Einstellungen aus. Sie müssen mindestens ein Feld in jeder Kategorie auswählen. Wählen Sie unter Zulässige Berechtigungen die Option Schreiben aus (Sie können auch andere Berechtigungen auswählen).
Stellen Sie für die übrigen Einstellungen die gewünschten Werte ein.
Wenn Sie fertig sind, klicken Sie auf die Schaltfläche SAS und Verbindungszeichenfolge generieren, um das SAS-Token zu generieren.
Hierdurch werden im unteren Bereich der gleichen Seite unter der Einstellungsauswahl mehrere Werte für die SAS und Verbindungszeichenfolgen generiert. Scrollen Sie nach unten, um die Werte anzuzeigen, und klicken Sie auf das Symbol In Zwischenablage kopieren, um den Wert des SAS-Tokens zu kopieren. Speichern Sie ihn zur späteren Verwendung.
Erstellen des Endpunkts für unzustellbare Nachrichten
Zum Erstellen eines Endpunkts mit aktivierten unzustellbaren Nachrichten müssen Sie die CLI-Befehle oder die APIs der Steuerungsebene anstelle des Azure-Portals verwenden, um den Endpunkt zu erstellen.
Um Anweisungen zum Erstellen dieses Endpunkttyps mit der Azure CLI zu erhalten, wechseln Sie für diesen Abschnitt zur Registerkarte „CLI“.
Nachrichtenspeicherschema
Sobald der Endpunkt für unzustellbare Nachrichten eingerichtet ist, werden unzustellbare Nachrichten im folgenden Format in Ihrem Speicherkonto gespeichert:
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
Unzustellbare Nachrichten entsprechen dem Schema des ursprünglichen Ereignisses, das an den ursprünglichen Endpunkt übermittelt werden sollte.
Im Folgenden finden Sie ein Beispiel für eine unzustellbare Nachricht für eine Benachrichtigung zur Erstellung eines Zwillings:
{
"specversion": "1.0",
"id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "Microsoft.DigitalTwins.Twin.Create",
"source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
"data": {
"$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
"TwinData": "some sample",
"$metadata": {
"$model": "dtmi:test:deadlettermodel;1",
"room": {
"lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
}
}
},
"subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"time": "2020-10-14T01:11:49.3667224Z",
"datacontenttype": "application/json",
"traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}
Nächste Schritte
Wenn Sie tatsächlich Daten von Azure Digital Twins an einen Endpunkt senden möchten, müssen Sie eine Ereignisroute definieren. 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. Erstellen Sie im nächsten Schritt eine Ereignisroute zu Ihrem Endpunkt unter Erstellen von Routen und Filtern.