Créer des points de terminaison dans Azure Digital Twins
Cet article explique comment créer un point de terminaison pour les événements Azure Digital Twin à l’aide de la Portail Azure ou d’Azure CLI. Vous pouvez également gérer les points de terminaison avec les API de plan de contrôle DigitalTwinsEndpoint.
Le routage des notifications d’événements d’Azure Digital Twins vers des services en aval ou des ressources de calcul connectées est un processus en deux étapes : créer des points de terminaison, puis créer des itinéraires d’événements pour envoyer des données à ces points de terminaison. Cet article décrit la première étape, la configuration des points de terminaison qui peuvent recevoir les événements. Plus tard, vous pouvez créer des itinéraires d’événements qui spécifient quels événements générés par Azure Digital Twins sont remis aux points de terminaison.
Prérequis
Vous aurez besoin d’un compte Azure, qui peut être configuré gratuitement
Vous aurez besoin d’une instance Azure Digital Twins dans votre abonnement Azure. Si vous n’avez pas encore d’instance, vous pouvez en créer une en suivant les étapes décrites dans Configurer une instance et l’authentification. Utilisez les valeurs suivantes du programme d’installation pour les utiliser plus loin dans cet article :
- Nom de l'instance
- Resource group
Vous trouverez ces informations dans le portail Azure après avoir configuré votre instance.
Suivez ensuite les instructions ci-dessous si vous envisagez d’utiliser Azure CLI tout en suivant ce guide.
Préparation de votre environnement pour Azure CLI
Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans 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 connaître les autres options de connexion, consultez Se connecter avec 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 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.
Créer les ressources nécessaires
Ces services sont les types de points de terminaison pris en charge que vous pouvez créer pour votre instance :
- Rubrique Event Grid
- Pour les points de terminaison Event Grid, seules les rubriques Event Grid sont prises en charge. Les domaines Event Grid ne sont pas pris en charge en tant que points de terminaison.
- Hub Event Hubs
- Rubrique Service Bus
Pour lier un point de terminaison à Azure Digital Twins, la rubrique Event Grid, Event Hub ou Service Bus que vous utilisez pour le point de terminaison doit pré-exister.
Utilisez le graphique suivant pour identifier les ressources qui doivent être configurées avant de créer votre point de terminaison.
| Type de point de terminaison | Ressources requises (liées aux instructions de création) |
|---|---|
| Point de terminaison Event Grid | Rubrique Event Grid * Le schéma d’événement doit être Schéma Event Grid ou Schéma d’événement cloud v1.0 |
| Point de terminaison Event Hubs | Espace de noms Event Hubs Event Hub (Facultatif) Règle d’autorisation pour l’authentification basée sur une clé |
| Point de terminaison de Service Bus | Espace de noms Service Bus Rubrique Service Bus (Facultatif) Règle d’autorisation pour l’authentification basée sur une clé |
Créer le point de terminaison
Une fois que vous avez créé les ressources du point de terminaison, vous pouvez les utiliser pour un point de terminaison Azure Digital Twins.
Pour créer un point de terminaison, accédez à la page de votre instance dans le portail Azure (vous pouvez rechercher l’instance en entrant son nom dans la barre de recherche du portail).
Dans le menu de l’instance, sélectionnez Points de terminaison. Ensuite, à partir de la page Points de terminaison qui suit, sélectionnez + Créer un point de terminaison. Cette opération ouvre la page Créer un point de terminaison, dont vous allez remplir les champs lors des étapes suivantes.
Entrez le nom de votre point de terminaison, puis choisissez le type de point de terminaison.
Renseignez les autres détails requis pour votre type de point de terminaison, y compris votre abonnement et les ressources de point de terminaison décrites précédemment.
- Pour les points de terminaison Event Hubs et Service Bus uniquement, vous devez sélectionner un type d’authentification. Vous pouvez utiliser l’authentification basée sur des clés avec une règle d’autorisation précréée, ou une identité managée affectée par le système ou affectée par l’utilisateur. Pour plus d’informations sur l’utilisation des options d’authentification d’identité, consultez options de point de terminaison : Authentification basée sur l’identité.
Terminez la création de votre point de terminaison en sélectionnant Enregistrer.
Après avoir créé votre point de terminaison, vous pouvez le vérifier en sélectionnant l’icône de notification dans la barre supérieure du portail Azure :
Si la création du point de terminaison échoue, observez le message d’erreur et réessayez après quelques minutes.
Vous pouvez également afficher le point de terminaison qui a été créé dans la page Points de terminaison de votre instance Azure Digital Twins.
La rubrique Event Grid, Event Hub ou Service Bus est désormais disponible sous forme de point de terminaison dans Azure Digital Twins, sous le nom que vous avez choisi pour le point de terminaison. Vous utiliserez généralement ce nom comme cible d’un itinéraire d’événement, que vous pouvez créer dans Créer des itinéraires et des filtres.
Options de point de terminaison : Authentification basée sur l’identité
Cette section explique comment utiliser une identité managée pour une instance Azure Digital Twins lors du transfert d’événements vers des destinations de routage prises en charge. La configuration d’une identité managée n’est pas nécessaire pour le routage, mais elle peut aider l’instance à accéder facilement à d’autres ressources protégées par Microsoft Entra, telles que Event Hubs, les destinations Service Bus et Stockage Azure Conteneur. Les identités managées peuvent être affectées par le système ou affectées par l’utilisateur.
Le reste de cette section décrit trois étapes pour configurer un point de terminaison avec une identité managée.
1. Activer l’identité managée pour l’instance
Utilisez les onglets ci-dessous pour obtenir des instructions qui correspondent à votre expérience préférée.
Tout d’abord, vérifiez que vous avez activé une identité managée pour votre instance Azure Digital Twins.
Vérifiez également que vous disposez du rôle Propriétaire des données Azure Digital Twins sur l’instance. Vous trouverez des instructions dans Configurer les autorisations d’accès utilisateur.
2. Attribuer des rôles Azure à l’identité
Une fois l’identité managée créée pour votre instance Azure Digital Twins, vous devez lui attribuer les rôles appropriés pour l’authentification avec différents types de points de terminaison pour le routage des événements vers des destinations prises en charge. Cette section décrit les options de rôle et comment les attribuer à l’identité managée.
Important
Veillez à effectuer cette étape. Sans cela, l’identité ne pourra pas accéder à vos points de terminaison et les événements ne seront pas remis.
Voici les rôles minimaux dont votre identité Azure Digital Twins a besoin pour accéder à un point de terminaison, en fonction du type de destination. Les rôles avec des autorisations plus élevées (comme les rôles de propriétaire des données) conviennent également.
| Destination | Rôle Azure |
|---|---|
| Hubs d'événements Azure | Expéditeur de données Azure Event Hubs |
| Azure Service Bus | Expéditeur de données Azure Service Bus |
| Conteneur de stockage Windows Azure | Contributeur aux données Blob du stockage |
Utilisez les onglets ci-dessous pour attribuer le rôle à l’aide de votre expérience préférée.
Pour affecter un rôle à l’identité, commencez par ouvrir le portail Azure dans un navigateur.
Accédez à votre ressource de point de terminaison (votre rubrique Event Hub, Service Bus, ou votre conteneur de stockage) en recherchant son nom dans la barre de recherche du portail.
Sélectionnez Contrôle d’accès (IAM) .
Sélectionnez Ajouter>Ajouter une attribution de rôle pour ouvrir la page Ajouter une attribution de rôle.
Attribuez le rôle souhaité à l’identité gérée de votre instance Azure Digital Twins à l’aide des informations ci-dessous. Pour connaître les étapes détaillées, consultez Attribuer des rôles Azure à l’aide du portail Azure.
Paramètre Valeur Role Sélectionnez le rôle souhaité dans les options. Attribuer l’accès à Identité gérée Membres Sélectionnez l’identité managée affectée par l’utilisateur ou affectée par le système de votre instance Azure Digital Twins affectée au rôle. Une identité affectée par l’utilisateur aura le nom que vous avez choisi lors de la création de l’identité, et une identité affectée par le système aura un nom qui correspond au nom de votre instance Azure Digital Twins. 
3. Créer le point de terminaison avec l’authentification basée sur l’identité
Après avoir configuré une identité managée pour votre instance Azure Digital Twins et lui attribuer le ou les rôles appropriés, vous pouvez créer les points de terminaison qui utilisent l’identité pour l’authentification. Cette option est uniquement disponible pour les points de terminaison de type Event Hubs et Service Bus (elle n’est pas prise en charge pour Event Grid).
Notes
Vous ne pouvez pas modifier un point de terminaison déjà créé avec une identité basée sur une clé pour passer à l’authentification basée sur l’identité. Vous devez choisir le type d’authentification lorsque le point de terminaison est créé pour la première fois.
Utilisez les onglets ci-dessous pour créer le point de terminaison à l’aide de votre expérience préférée.
Commencez à suivre les instructions générales pour créer un point de terminaison Azure Digital Twins.
Lorsque vous accédez à l’étape consistant à fournir les détails de votre type de point de terminaison, veillez à sélectionner Affectée par le système ou Affectée par l’utilisateur (préversion) comme type d’authentification.
Terminez la configuration de votre point de terminaison et sélectionnez Enregistrer.
Considérations relatives à la désactivation d’identités managées
Étant donné qu’une identité est gérée séparément des points de terminaison qui l’utilisent, il est important de prendre en compte les effets que toute modification apportée à l’identité ou à ses rôles peut avoir sur les points de terminaison de votre instance Azure Digital Twins. Si l’identité est désactivée, ou si un rôle nécessaire à un point de terminaison est supprimé de celui-ci, le point de terminaison peut devenir inaccessible, et le flux des événements est interrompu.
Pour continuer à utiliser un point de terminaison configuré avec une identité gérée maintenant désactivée, vous devez supprimer le point de terminaison et le recréer avec un autre type d’authentification. L’opération peut prendre jusqu’à une heure avant que les événements ne soient remis au point de terminaison après cette modification.
Options de point de terminaison : lettres mortes
Lorsqu’un point de terminaison ne peut pas remettre un événement dans un laps de temps donné ou après avoir essayé de remettre l’événement un certain nombre de fois, il peut envoyer l’événement non remis à un compte de stockage. Ce processus est appelé mise en file d’attente de lettres mortes.
Vous pouvez configurer les ressources de stockage nécessaires à l’aide du portail Azure ou de l’interface Azure Digital Twins. Cependant, pour créer un point de terminaison avec mise en file d’attente de lettres mortes, vous devrez utiliser l’interface CLI ou les API de plan de contrôle Azure Digital Twins.
Pour en savoir plus sur les lettres mortes, consultez Points de terminaison et routes d’événements. Pour obtenir des instructions sur la configuration d’un point de terminaison avec une mise en file d’attente de lettres mortes, suivez le reste de cette section.
Configurer des ressources de stockage
Avant de définir l’emplacement des messages non distribués, vous devez disposer d’un compte de stockage avec un conteneur configurés dans votre compte Azure.
Vous devrez fournir l’URI de ce conteneur au moment de créer le point de terminaison ultérieurement. L’emplacement de la file d’attente de lettres mortes est fourni au point de terminaison en tant qu’URI de conteneur avec un jeton SAS. Ce jeton a besoin de l’autorisation write pour le conteneur de destination dans le compte de stockage. L’URI SAS de lettre morte entièrement formée sera au format suivant : https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.
Suivez les étapes ci-dessous pour configurer ces ressources de stockage dans votre compte Azure, afin de préparer la configuration de la connexion du point de terminaison dans la section suivante.
- Suivez les étapes de création d’un compte de stockage pour créer un compte de stockage dans votre abonnement Azure. Prenez note du nom du compte de stockage ; vous en aurez besoin plus tard.
- Suivez les étapes décrites dans Créer un conteneur pour créer un conteneur dans le nouveau compte de stockage. Notez le nom de conteneur ; vous en aurez besoin plus tard.
Créez un jeton SAP
Ensuite, créez un jeton SAS pour votre compte de stockage que le point de terminaison peut utiliser pour y accéder.
Commencez par accéder à votre compte de stockage dans le portail Azure (vous pouvez le rechercher par son nom dans la barre de recherche du portail).
Dans la page du compte de stockage, choisissez le lien Signature d’accès partagé dans la barre de navigation de gauche afin de lancer la configuration du jeton SAP.
Dans la page Signature d’accès partagé, sous Services autorisés et Types de ressources autorisés, sélectionnez les paramètres de votre choix. Vous devez sélectionner au moins une case dans chaque catégorie. Sous Autorisations acceptées, choisissez Écriture (vous pouvez également sélectionner d’autres autorisations si vous le souhaitez).
Définissez les valeurs de votre choix pour les autres paramètres.
Lorsque vous avez terminé, sélectionnez le bouton Générer la chaîne de connexion et SAP pour générer le jeton SAP.
Cela a pour effet de générer plusieurs valeurs de chaîne de connexion et SAP au bas de la même page, sous les sélections de paramètres. Faites défiler l’écran pour afficher les valeurs et utilisez l’icône de copie dans le presse-papiers pour copier la valeur du jeton SAP. Enregistrez-la en vue d’une utilisation ultérieure.
Créer le point de terminaison de lettres mortes
Pour créer un point de terminaison avec mise en file d’attente de lettres mortes, il est préférable d’utiliser les commandes CLI ou les API de plan de contrôle pour créer votre point de terminaison, plutôt que le portail Azure.
Pour obtenir des instructions sur la façon de créer ce type de point de terminaison avec l’interface CLI Azure, basculez vers l’onglet CLI pour cette section.
Schéma de stockage des messages
Une fois que le point de terminaison avec la file d’attente de lettres mortes est configuré, les messages associés sont stockés au format suivant dans votre compte de stockage :
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
Les messages en file d’attente de lettres mortes correspondent au schéma de l’événement d’origine qui a été conçu pour être remis à votre point de terminaison d’origine.
Voici un exemple de message de lettres mortes pour une notification de création de jumeau :
{
"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"
}
Étapes suivantes
Pour envoyer concrètement des données d’Azure Digital Twins à un point de terminaison, vous devez définir un itinéraire d’événement. Ces itinéraires permettent aux développeurs d’associer le flux d’événements au sein du système et aux services en aval. Un seul itinéraire peut permettre la sélection de plusieurs notifications et types d’événements. Continuez pour créer un itinéraire d’événement vers votre point de terminaison dans Créer des itinéraires et des filtres.