Einrichten einer Azure Digital Twins-Instanz und der Authentifizierung (CLI)

Dieser Artikel behandelt 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:

  1. Erstellen der Instanz
  2. 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 Azure Cloud Shell-Schnellstart: Bash. Starten von Cloud Shell in einem neuen Fenster

  • 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 Azure-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 systemseitig 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 systemseitig verwalteten Identität

Wenn Sie eine systemseitig zugewiesene Identität für Ihre Azure Digital Twins-Instanz aktivieren, erstellt Azure dafür automatisch eine Identität in Azure Active Directory (Azure AD). Diese Identität kann dann für die Authentifizierung bei Azure Digital Twins-Endpunkten für die Ereignisweiterleitung verwendet werden. Sie können eine systemseitig 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.

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 --assign-identity hinzufügen. (Weitere Informationen zu diesem 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 verwalteten Identität den Parameter --assign-identity wie folgt hinzu:

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --assign-identity

Ü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:

Screenshot: Fenster „Cloud Shell“ mit erfolgreicher Erstellung einer Ressourcengruppe und Azure Digital Twins-Instanz im Azure-Portal.

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 ihnen diese Werte mitteilen.

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

In Azure Digital Twins wird Azure Active Directory (Azure AD) für die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) verwendet. 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 Azure AD-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 Azure AD-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: Berechtigungsanforderungen

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 Administratorrollen für klassische Abonnements, Azure-Rollen und Azure AD-Rollen.

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:

Screenshot der Seite „Abonnements“ im Azure-Portal, die den Benutzer als Besitzer anzeigt

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 darin 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 Azure AD-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 Azure AD-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 mit den Azure Active Directory-Benutzern, um das Benutzerkonto auszuwählen und die zugehörigen Details zu öffnen. Kopieren Sie die Objekt-ID des Benutzers:

Screenshot: Benutzerseite im Azure-Portal mit Hervorhebung der GUID im Feld „Objekt-ID“.

Wiederholen Sie dann den list-Befehl für die Rollenzuweisung mit der Objekt-ID des Benutzers für den oben genannten Parameter assignee.

Ü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.

Screenshot der Rollenzuweisungen für eine Azure Digital Twins-Instanz im Azure-Portal.

Sie verfügen nun über eine einsatzbereite Azure Digital Twins-Instanz und haben Berechtigungen zugewiesen, um diese zu verwalten.

Aktivieren/Deaktivieren der systemseitig verwalteten Identität für die Instanz

In diesem Abschnitt erfahren Sie, wie Sie einer vorhandenen Azure Digital Twins-Instanz eine systemseitig verwaltete Identität hinzufügen. Sie können auch die systemseitig verwaltete Identität für eine Instanz deaktivieren, die sie bereits hat.

Der Befehl zum Aktivieren der verwalteten Identität für eine vorhandene Instanz ist derselbe Befehl az dt create, mit dem eine neue Instanz mit einer systemseitig verwalteten 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 --assign-identity hinzu.

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --assign-identity

Verwenden Sie den folgenden ähnlichen Befehl zum Festlegen von --assign-identity auf false, um die verwaltete 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> --assign-identity false

Überlegungen zum Deaktivieren von systemseitig verwalteten 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: