Einrichten einer Azure Digital Twins-Instanz und der Authentifizierung (CLI)
Dieser Artikel beschreibt die Schritte zum Einrichten einer neuen Azure Digital Twins-Instanz, einschließlich des Erstellens der Instanz und des Einrichtens der Authentifizierung. Nachdem Sie die Schritte in diesem Artikel durchgeführt haben, verfügen Sie über eine Azure Digital Twins-Instanz, die zum Programmieren bereitsteht.
Das vollständige Setup für eine neue Azure Digital Twins-Instanz umfasst zwei Teile:
- Erstellen der Instanz
- Einrichten von Benutzerzugriffsberechtigungen: Azure-Benutzer müssen über die Rolle Azure Digital Twins-Datenbesitzer für die Azure Digital Twins-Instanz verfügen, um die Instanz und ihre Daten verwalten zu können. In diesem Schritt weisen Sie als Besitzer/Administrator des Azure-Abonnements diese Rolle der Person zu, die Ihre Azure Digital Twins-Instanz verwalten soll. Dies können Sie selbst sein oder eine andere Person in Ihrer Organisation.
Wichtig
Um diesen vollständigen Artikel abzuschließen und eine verwendbare Instanz vollständig einzurichten, benötigen Sie Berechtigungen zum Verwalten von Ressourcen und Benutzerzugriff für das Azure-Abonnement. Der erste Schritt kann von allen Personen ausgeführt werden, die Ressourcen für das Abonnement erstellen können, aber der zweite Schritt erfordert Berechtigungen für die Benutzerzugriffsverwaltung (oder die Zusammenarbeit eines Benutzers mit diesen Berechtigungen). Weitere Informationen hierzu finden Sie im Abschnitt Voraussetzungen: Erforderliche Berechtigungen für den Schritt „Benutzerzugriffsberechtigung“.
Voraussetzungen
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.
Einrichten einer CLI-Sitzung
Um mit Azure Digital Twins in der CLI zu arbeiten, müssen Sie sich zunächst anmelden und den CLI-Kontext für diese Sitzung auf Ihr Abonnement festlegen. Führen Sie diese Befehle in Ihrem CLI-Fenster aus:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Tipp
Sie können im obigen Befehl anstelle der ID auch Ihren Abonnementnamen verwenden.
Wenn Sie dieses Abonnement zum ersten Mal mit Azure Digital Twins nutzen, führen Sie diesen Befehl aus, um sich im Namespace von Azure Digital Twins zu registrieren. (Falls Sie sich nicht sicher sind, ist es in Ordnung, ihn erneut auszuführen, auch wenn Sie ihn irgendwann zuvor schon einmal ausgeführt haben.)
az provider register --namespace 'Microsoft.DigitalTwins'
Als Nächstes fügen Sie die Microsoft Azure IoT-Erweiterung für die Azure CLI hinzu, um Befehle für die Interaktion mit Azure Digital Twins und anderen IoT-Diensten zu aktivieren. Führen Sie den folgenden Befehl aus, um sicherzustellen, dass Sie über die neueste Version der Erweiterung verfügen:
az extension add --upgrade --name azure-iot
Nun können Sie in der Azure CLI mit Azure Digital Twins arbeiten.
Sie können dies durch Ausführung von az dt --help jederzeit überprüfen, um eine Liste der verfügbaren Azure Digital Twins-Befehle oberster Ebene anzuzeigen.
Erstellen der Azure Digital Twins-Instanz
In diesem Abschnitt erstellen Sie eine neue Azure Digital Twins-Instanz über den CLI-Befehl. Hierzu müssen Sie Folgendes bereitstellen:
- Eine Ressourcengruppe, in der die Instanz bereitgestellt wird. Wenn Sie noch nicht über eine Ressourcengruppe verfügen, können Sie diese jetzt mit dem folgenden Befehl erstellen:
az group create --location <region> --name <name-for-your-resource-group> - Eine Region für die Bereitstellung. Informationen zu Regionen mit Unterstützung von Azure Digital Twins finden Sie unter Verfügbare Produkte nach Region.
- Ein Name für Ihre Instanz. Wenn in Ihrem Abonnement für die Region eine weitere Azure Digital Twins-Instanz vorhanden ist, die den angegeben Namen bereits verwendet, werden Sie aufgefordert, einen anderen Namen auszuwählen.
Verwenden Sie im folgenden az dt-Befehl diese Werte, um die Instanz zu erstellen:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
Es gibt mehrere optionale Parameter, die dem Befehl hinzugefügt werden können, um bei der Erstellung zusätzliche Angaben zu Ihrer Ressource zu machen, einschließlich Erstellung einer verwalteten Identität für die Instanz oder der Aktivierung/Deaktivierung des Zugriffs auf das öffentliche Netzwerk. Eine vollständige Liste der unterstützten Parameter finden Sie in der Referenzdokumentation zu az dt create.
Erstellen der Instanz mit einer verwalteten Identität
Wenn Sie eine verwaltete Identität für Ihre Azure Digital Twins-Instanz aktivieren, wird dafür eine Identität in Microsoft Entra erstellt. Diese Identität kann dann für die Authentifizierung bei anderen Diensten verwendet werden. Sie können eine verwaltete Identität für eine Azure Digital Twins-Instanz während der Erstellung der Instanz oder später für eine vorhandene Instanz aktivieren.
Verwenden Sie den folgenden CLI-Befehl für Ihren ausgewählten Typ der verwalteten Identität.
Befehl für systemseitig zugewiesene Identität
Um eine Azure Digital Twins-Instanz mit systemseitig zugewiesener Identität zu erstellen, können Sie dem Befehl az dt create, der zur Erstellung der Instanz verwendet wird, den Parameter --mi-system-assigned hinzufügen. (Weitere Informationen zum create-Befehl finden Sie in der zugehörigen Referenzdokumentation oder in den allgemeinen Anweisungen zum Einrichten einer Azure Digital Twins-Instanz.)
Fügen Sie zum Erstellen einer Instanz mit einer systemseitig zugewiesenen Identität den --mi-system-assigned-Parameter wie folgt hinzu:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
Befehl für benutzerseitig zugewiesene Identität
Um eine Instanz mit einer benutzerseitig zugewiesenen Identität zu erstellen, geben Sie die ID einer vorhandenen benutzerseitig zugewiesenen Identität mithilfe des Parameters --mi-user-assigned wie folgt an:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
Überprüfen des Erfolgs und Erfassen wichtiger Werte
Wenn die Instanz erfolgreich erstellt wurde, sieht das Ergebnis in der CLI in etwa wie folgt aus und gibt Informationen zu der von Ihnen erstellte Ressource aus:
Beachten Sie die Angaben für hostName, name und resourceGroup der Azure Digital Twins-Instanz in der Ausgabe. Diese Werte sind alle wichtig. Sie benötigen sie möglicherweise, wenn Sie mit Ihrer Azure Digital Twins-Instanz weiterarbeiten, um die Authentifizierung und die zugehörigen Azure-Ressourcen einzurichten. Wenn andere Benutzer in der Instanz programmieren, sollten Sie diese Werte mit ihnen teilen.
Tipp
Sie können diese Eigenschaften sowie alle Eigenschaften Ihrer Instanz jederzeit durch Ausführen von az dt show --dt-name <your-Azure-Digital-Twins-instance> einsehen.
Die Azure Digital Twins-Instanz ist jetzt einsatzbereit. Im nächsten Schritt stellen Sie die entsprechenden Azure-Benutzerberechtigungen für die Verwaltung der Instanz zur Verfügung.
Einrichten von Benutzerzugriffsberechtigungen
Azure Digital Twins verwendet Microsoft Entra ID für die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC). Dies bedeutet, dass einem Benutzer eine Rolle mit entsprechenden Berechtigungen zugewiesen werden muss, bevor er Aufrufe auf Datenebene an Ihre Azure Digital Twins-Instanz richten kann.
Bei Azure Digital Twins ist dies die Rolle Azure Digital Twins Data Owner (Azure Digital Twins-Datenbesitzer). Weitere Informationen zu Rollen und Sicherheit finden Sie unter Sicherheit für Azure Digital Twins-Lösungen.
Hinweis
Diese Rolle unterscheidet sich von der Microsoft Entra ID-Rolle Besitzer, die ebenfalls im Bereich der Azure Digital Twins-Instanz zugewiesen werden kann. Es handelt sich hierbei um zwei unterschiedliche Verwaltungsrollen. Die Rolle „Besitzer“ gewährt keinen Zugriff auf Features der Datenebene, während dieser Zugriff mit Azure Digital Twins-Datenbesitzer gewährt wird.
In diesem Abschnitt erfahren Sie, wie Sie eine Rollenzuweisung für einen Benutzer in Ihrer Azure Digital Twins-Instanz erstellen, indem Sie die E-Mail-Adresse dieses Benutzers im Microsoft Entra ID-Mandanten in Ihrem Azure-Abonnement verwenden. Je nach Ihrer Rolle in Ihrer Organisation können Sie diese Berechtigung für sich selbst oder für eine andere Person einrichten, die die Azure Digital Twins-Instanz verwaltet.
Voraussetzungen: Erforderliche Benutzerberechtigungen
Damit Sie alle folgenden Schritte ausführen können, benötigen Sie eine Rolle mit den folgenden Berechtigungen für Ihr Abonnement:
- Erstellen und Verwalten von Azure-Ressourcen
- Verwalten des Benutzerzugriffs auf Azure-Ressourcen (einschließlich erteilen und delegieren von Berechtigungen)
Allgemeine Rollen, die diese Anforderung erfüllen, heißen Besitzer oder Kontoadministrator. Ebenso können die beiden Rollen Benutzerzugriffsadministrator und Mitwirkender kombiniert werden. Ausführliche Informationen zu den Rollen und Berechtigungen, einschließlich der Berechtigungen, die für andere Rollen freigeschaltet sind, finden Sie in der Dokumentation zu Azure RBAC unter Azure-Rollen, Microsoft Entra-Rollen und Administratorrollen für klassische Abonnements.
Wenn Sie herausfinden möchten, welche Rolle Ihnen für Ihr Abonnement zugewiesen ist, erhalten Sie weitere Informationen auf der Seite Abonnements im Azure-Portal. Sie können entweder diesen Link verwenden oder über die Suchleiste des Portals nach Abonnements suchen. Suchen Sie nach dem Namen des Abonnements, das Sie verwenden, und prüfen Sie Ihre Rolle in der Spalte Meine Rolle:
Wenn Sie feststellen, dass Ihnen die Rolle Mitwirkender oder eine andere Rolle zugewiesen ist, die nicht die erforderlichen Berechtigungen beinhaltet, können Sie einen Benutzer Ihres Abonnements kontaktieren, der über diese Berechtigungen verfügt (z. B. der Besitzer oder der Kontoadministrator des Abonnements), und dann eine der folgenden Möglichkeiten auswählen, um fortzufahren:
- Bitten Sie den Benutzer darum, die Schritte zur Rollenzuweisung in Ihrem Namen auszuführen.
- Bitten Sie darum, dass der Benutzer Ihnen eine höhere Rolle zuweist, damit Sie über die benötigten Berechtigungen verfügen, um selbst fortzufahren. Ob diese Vorgehensweise angemessen ist, hängt von Ihrer Organisation und Ihrer Rolle in dieser Organisation ab.
Zuweisen der Rolle
Um einem Benutzer die Berechtigung zum Verwalten einer Azure Digital Twins-Instanz zu gewähren, müssen Sie ihm die Rolle Azure Digital Twins Data Owner (Azure Digital Twins-Datenbesitzer) innerhalb der Instanz zuweisen.
Verwenden Sie den folgenden Befehl, um die Rolle zuzuweisen (dieser Vorgang muss von einem Benutzer mit ausreichenden Berechtigungen im Azure-Abonnement ausgeführt werden). In diesem Befehl müssen Sie den Benutzerprinzipalnamen im Microsoft Entra-Konto für den Benutzer übergeben, dem die Rolle zugewiesen werden soll. In den meisten Fällen entspricht dieser Wert der E-Mail-Adresse des Benutzers im Microsoft Entra-Konto.
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"
Die Ausgabe dieses Befehls enthält Informationen zur erstellten Rollenzuweisung für den Benutzer.
Hinweis
Wenn dieser Befehl den Fehler zurückgibt, dass die CLI den Benutzer- oder Dienstprinzipal in der Graphdatenbank nicht findet, gehen Sie folgendermaßen vor:
Weisen Sie die Rolle stattdessen mithilfe der Objekt-ID des Benutzers zu. Dies kann bei Benutzern mit persönlichen Microsoft-Konten (MSA) passieren.
Verwenden Sie die Azure-Portalseite von Microsoft Entra-Benutzern, um das Benutzerkonto auszuwählen und die Details zu öffnen. Kopieren Sie die Objekt-ID des Benutzers:
Wiederholen Sie dann den Listen Befehl für die Rollenzuweisung mit der Objekt-ID des Benutzers für den oben genannten assignee Parameter.
Überprüfen des erfolgreichen Abschlusses
Eine Möglichkeit, um zu überprüfen, ob die Rollenzuweisung erfolgreich eingerichtet wurde, besteht darin, die Rollenzuweisungen für die Instanz von Azure Digital Twins im Azure-Portal anzuzeigen. Navigieren Sie im Azure-Portal zu Ihrer Azure Digital Twins-Instanz. Um dorthin zu gelangen, können Sie sie auf der Seite der Azure Digital Twins-Instanzen suchen oder nach ihrem Namen in der Suchleiste des Portals suchen.
Sehen Sie sich dann unter Zugriffssteuerung (IAM) > Rollenzuweisungen alle zugewiesenen Rollen an. Ihre Rollenzuweisung sollte in der Liste angezeigt werden.
Sie verfügen nun über eine einsatzbereite Azure Digital Twins-Instanz und haben Berechtigungen zugewiesen, um diese zu verwalten.
Aktivieren/Deaktivieren der verwalteten Identität für die Instanz
Dieser Abschnitt zeigt, wie Sie eine verwaltete Identität zu einer bereits vorhandenen Azure Digital Twins-Instanz hinzufügen. Sie können auch die verwaltete Identität für eine Instanz deaktivieren, die bereits über eine verfügt.
Verwenden Sie die folgenden CLI-Befehle für Ihren ausgewählten Typ der verwalteten Identität.
Befehle für systemseitig zugewiesene Identität
Der Befehl zum Aktivieren einer systemseitig zugewiesenen Identität für eine vorhandene Instanz ist derselbe az dt create-Befehl, mit dem eine neue Instanz mit einer systemseitig zugewiesenen Identität erstellt wird. Anstatt den neuen Namen einer zu erstellenden Instanz anzugeben, können Sie den Namen einer bereits vorhandenen Instanz angeben, die bereits vorhanden ist. Fügen Sie dann den Parameter --mi-system-assigned hinzu.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
Verwenden Sie den folgenden Befehl zum Festlegen von --mi-system-assigned auf false, um die systemseitig zugewiesene Identität für einer Instanz zu deaktivieren, für die sie derzeit aktiviert ist.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
Befehle für benutzerseitig zugewiesene Identität
Um eine benutzerseitig zugewiesene Identität für eine vorhandene Instanz zu aktivieren, geben Sie im folgenden Befehl die ID einer vorhandenen benutzerseitig zugewiesenen Identität an:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Um eine benutzerseitig zugewiesene Identität für eine Instanz zu deaktivieren, für die sie derzeit aktiviert ist, geben Sie die ID der Identität im folgenden Befehl an:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Überlegungen zum Deaktivieren verwalteter Identitäten
Es ist wichtig, die Auswirkungen zu berücksichtigen, die Änderungen an der Identität oder ihren Rollen auf die Ressourcen haben können, die sie verwenden. Wenn Sie verwaltete Identitäten mit Ihren Azure Digital Twins-Endpunkten oder für den Datenverlauf verwenden und die Identität deaktiviert wird oder eine notwendige Rolle entfernt wird, kann die Verbindung mit dem Endpunkt oder Datenverlauf fehlschlagen, und der Ereignisfluss wird unterbrochen.
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.
Nächste Schritte
Testen Sie einzelne REST-API-Aufrufe für Ihre Instanz mithilfe der Befehle der Azure Digital Twins-CLI:
Sie können auch eine Verbindung zwischen Ihrer Clientanwendung und Ihrer Instanz herstellen, indem Sie Authentifizierungscode verwenden: