Configurer une instance Azure Digital Twins et l’authentification (interface CLI)

Cet article explique comment configurer une nouvelle instance Azure Digital Twins, notamment la création de l’instance et la configuration de l’authentification. À l’issue de cet article, vous aurez une instance Azure Digital Twins prête pour la programmation.

La configuration complète d’une nouvelle instance Azure Digital Twins se déroule en deux phases :

1. Création de l’instance.
2. Configuration d’autorisations d’accès utilisateur : les utilisateurs Azure doivent avoir le rôle Propriétaire de données Azure Digital Twins sur l’instance Azure Digital Twins pour pouvoir gérer celle-ci et ses données. Dans cette étape, vous êtes propriétaire/administrateur de l’abonnement Azure qui attribue ce rôle à la personne qui gère votre instance Azure Digital Twins. Cette personne peut être vous-même ou quelqu’un d’autre dans votre organisation.

Prérequis

• Utilisez l’environnement Bash dans Azure Cloud Shell. Pour obtenir plus d’informations, consultez Démarrage d’Azure Cloud Shell.

  

• Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.

  • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour obtenir d’autres options de connexion, consultez S’authentifier auprès d’Azure à l’aide d’Azure CLI.

  • Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser et gérer des extensions avec Azure CLI.

  • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Configurer une session CLI

Pour commencer à utiliser Azure Digital Twins dans l’interface CLI, la première chose à faire est de vous connecter et de définir le contexte CLI sur votre abonnement pour cette session. Exécutez les commandes suivantes dans votre fenêtre CLI :

az login
az account set --subscription "<your-Azure-subscription-ID>"

Si vous utilisez cet abonnement avec Azure Digital Twins pour la première fois, exécutez la commande suivante pour vous inscrire auprès de l’espace de noms Azure Digital Twins. (Si vous n’êtes pas sûr, il est possible de le réexécuter même si vous l’avez exécuté dans le passé.)

az provider register --namespace 'Microsoft.DigitalTwins'

Ensuite, vous ajoutez l’extension Microsoft Azure IoT pour Azure CLI pour activer les commandes permettant d’interagir avec Azure Digital Twins et d’autres services IoT. Exécutez cette commande pour vous assurer de disposer de la version la plus récente de l’extension :

az extension add --upgrade --name azure-iot

Vous êtes maintenant prêt à utiliser Azure Digital Twins dans Azure CLI.

Vous pouvez vérifier cet état en exécutant az dt --help à tout moment pour afficher la liste des commandes Azure Digital Twins de niveau supérieur disponibles.

Créer l’instance Azure Digital Twins

Dans cette section, vous allez créer une instance d’Azure Digital Twins à l’aide de la commande CI. Vous devez fournir :

• Groupe de ressources dans lequel l’instance est déployée. Si vous n’avez pas encore de groupe de ressources existant en tête, vous pouvez en créer un maintenant à l’aide de cette commande :

  az group create --location <region> --name <name-for-your-resource-group>
  

• Une région pour le déploiement. Pour connaître les régions qui prennent en charge Azure Digital Twins, consultez Produits Azure disponibles par région.
• Un nom pour votre instance. Si votre abonnement dispose d’une autre instance Azure Digital Twins dans la région qui utilise déjà le nom spécifié, vous êtes invité à choisir un autre nom.

Utilisez ces valeurs dans la commande az dt suivante pour créer l’instance :

az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>

Plusieurs paramètres facultatifs peuvent être ajoutés à la commande pour spécifier d’autres éléments concernant votre ressource lors de la création, notamment la création d’une identité managée pour l’instance ou l’activation/désactivation de l’accès au réseau public. Pour obtenir la liste complète des paramètres pris en charge, consultez la documentation de référence d’az dt create.

Créer l’instance avec une identité managée

Lorsque vous activez une identité managée sur votre instance Azure Digital Twins, une identité est créée pour celle-ci dans Microsoft Entra ID. Cette identité peut ensuite être utilisée pour s’authentifier auprès d’autres services. Vous pouvez activer une identité managée pour une instance Azure Digital Twins lors de la création d’une instance, ou ultérieurement sur une instance existante.

Utilisez la commande CLI suivante pour votre type d’identité managée choisi.

Commande d’identité assignée par le système

Pour créer une instance Azure Digital Twins avec une identité affectée par le système activée, vous pouvez ajouter un paramètre --mi-system-assigned à la commande az dt create qui est utilisée pour créer l’instance. (Pour plus d’informations sur la commande de création, consultez sa documentation de référence ou les instructions générales relatives à la configuration d’une instance d’Azure Digital Twins).

Pour créer une instance avec une identité affectée par le système, ajoutez le paramètre --mi-system-assigned comme ceci :

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned

Commande d’identité affectée par l’utilisateur(-trice)

Pour créer une instance avec une identité affectée par l’utilisateur, fournissez l’ID d’une identité affectée par l’utilisateur existante à l’aide du paramètre --mi-user-assigned, comme suit :

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>

Vérifier le succès et collecter les valeurs importantes

Si l’instance a été créée avec succès, le résultat dans l’interface de ligne de commande ressemble à ceci, en sortant des informations sur la ressource que vous avez créée :

Notez les valeurs hostName, name et resourceGroup de l’instance Azure Digital Twins fournies dans la sortie. Ces valeurs sont toutes importantes et vous devrez peut-être les utiliser lorsque vous continuez à travailler avec votre instance Azure Digital Twins, pour configurer l’authentification et les ressources Azure associées. Si d’autres utilisateurs programment sur l’instance, vous devez partager ces valeurs avec eux.

Vous disposez maintenant d’une instance Azure Digital Twins opérationnelle. Ensuite, vous accordez aux utilisateurs Azure les autorisations appropriées pour le gérer.

Configurer les autorisations d’accès utilisateur

Azure Digital Twins utilise Microsoft Entra ID pour le contrôle d’accès en fonction du rôle (RBAC). Cela signifie qu’avant qu’un utilisateur puisse effectuer des appels à la couche de données dans votre instance de Azure Digital Twins, il faut lui attribuer un rôle disposant des autorisations appropriées.

Pour Azure Digital Twins, ce rôle est Propriétaire de données Azure Digital Twins. Vous pouvez en savoir plus sur les rôles et la sécurité dans Sécurité pour les solutions Azure Digital Twins.

Cette section vous montre comment créer une attribution de rôle pour un utilisateur dans votre instance Azure Digital Twins, à l’aide de l’e-mail de cet utilisateur dans le locataire Microsoft Entra sur votre abonnement Azure. Selon votre rôle dans votre organisation, vous pouvez configurer cette autorisation pour vous-même ou la configurer pour le compte d’une autre personne qui gère l’instance Azure Digital Twins.

Configuration requise : Spécifications relatives aux autorisations

Pour être en mesure d’effectuer toutes les étapes qui suivent, vous devez disposer d’un rôle dans votre abonnement qui dispose des autorisations suivantes :

• Créer et gérer des ressources Azure
• Gérer l’accès des utilisateurs aux ressources Azure (y compris l’octroi et la délégation des autorisations)

Les rôles communs qui répondent à cette exigence sont Propriétaire, Administrateur de compte ou la combinaison des rôles Administrateur de l’accès utilisateur et Contributeur. Pour obtenir une explication complète des rôles et des autorisations, notamment les autorisations qui sont incluses avec d’autres rôles, consultez Rôles Azure, rôles Microsoft Entra ID et rôles d’administrateur d’abonnement classique dans la documentation Azure RBAC.

Pour consulter votre rôle dans l’abonnement, accédez à la page Abonnements du portail Azure (vous pouvez utiliser ce lien ou rechercher Abonnements dans la barre de recherche du portail). Recherchez le nom de l’abonnement que vous utilisez et affichez votre rôle dans la colonne Mon rôle :

Si vous constatez que la valeur est Contributeur, ou un autre rôle qui n’a pas les autorisations requises précédemment décrites, vous pouvez contacter l’utilisateur sur votre abonnement disposant de ces autorisations (par exemple, un propriétaire d’abonnement ou un administrateur de compte) et procéder de l’une des manières suivantes :

• Demandez-leur d’effectuer les étapes d’attribution de rôle en votre nom.
• Demandez-leur d’élever votre rôle sur l’abonnement afin que vous disposiez des autorisations nécessaires pour continuer. Si cette demande est appropriée peut dépendre de votre organisation et de votre rôle au sein de celle-ci.

Attribuer le rôle

Pour accorder à un utilisateur les autorisations nécessaires pour gérer une instance Azure Digital Twins, vous devez lui attribuer le rôle Propriétaire de données Azure Digital Twins au sein de l’instance.

Utilisez la commande suivante pour attribuer le rôle. Un utilisateur disposant d’autorisations suffisantes dans l’abonnement Azure doit exécuter la commande. La commande nécessite de passer le nom d’utilisateur principal sur le compte Microsoft Entra de l’utilisateur auquel le rôle doit être attribué. Dans la plupart des cas, cette valeur correspond à l’adresse e-mail de l’utilisateur sur le compte Microsoft Entra.

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"

Le résultat de cette commande est la sortie d’informations sur l’attribution de rôle qui a été créée pour l’utilisateur.

Vérifier la réussite de l’exécution

Une façon de vérifier que vous avez correctement configuré l’attribution de rôle consiste à afficher les attributions de rôle pour l’instance Azure Digital Twins dans le Portail Azure.

Accédez à votre instance Azure Digital Twins dans le Portail Azure. Pour y accéder, vous pouvez la rechercher dans la page Instances Azure Digital Twins ou rechercher son nom dans la barre de recherche du portail.

Ensuite, affichez tous les rôles qui lui sont attribués sous Contrôle d’accès (IAM) > Attributions de rôle. Votre attribution de rôle doit s’afficher dans la liste.

Vous disposez maintenant d’une instance Azure Digital Twins prête à l’emploi et des autorisations pour la gérer.

Activer/désactiver une identité managée pour l’instance

Cette section vous montre comment ajouter une identité managée à une instance existante d’Azure Digital Twins. Vous pouvez également désactiver l’identité managée sur une instance qui l’a déjà.

Utilisez les commandes CLI suivantes pour le type d’identité managée que vous avez choisi.

Commandes d’identité affectée par le système

La commande permettant d’activer l’identité affectée par le système pour une instance existante est la même commande az dt create que celle utilisée pour créer une instance avec une identité affectée par le système. Au lieu de fournir le nouveau nom pour une instance à créer, vous pouvez indiquer le nom d’une instance qui existe déjà. Ensuite, veillez à ajouter le paramètre --mi-system-assigned.

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned

Pour désactiver l’identité affectée par le système sur une instance où elle est activée, utilisez la commande suivante afin d’affecter --mi-system-assigned à la valeur false.

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false

Commandes d’identité affectée par l’utilisateur

Pour activer une identité affectée par l’utilisateur sur une instance existante, fournissez l’ID d’une identité affectée par l’utilisateur existante dans la commande suivante :

az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

Pour désactiver une identité affectée par l’utilisateur sur une instance où elle est actuellement activée, fournissez l’ID de l’identité dans la commande suivante :

az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

Considérations relatives à la désactivation d’identités managées

Il est important de prendre en compte les effets que toute modification apportée à l’identité ou à ses rôles peut avoir sur les ressources qui l’utilisent. Si vous utilisez des identités managées avec vos points de terminaison Azure Digital Twins ou pour l’historique des données et que l’identité est désactivée, ou si un rôle nécessaire est supprimé de celle-ci, la connexion de point de terminaison ou d’historique des données peut devenir inaccessible et le flux d’événements est interrompu.

Pour continuer à utiliser un point de terminaison qui a été configuré avec une identité managée qui a maintenant été désactivée, vous devez supprimer le point de terminaison et le recréer avec un autre type d’authentification. La reprise de la livraison des événements au point de terminaison après cette modification peut prendre jusqu'à une heure.

Étapes suivantes

Testez les appels d’API REST individuels sur votre instance à l’aide des commandes CLI d’Azure Digital Twins :

• az dt reference
• Ensemble de commandes CLI Azure Digital Twins

Vous pouvez également découvrir comment connecter une application cliente à votre instance avec un code d’authentification :

• Écrire le code d’authentification de l’application cliente