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 du 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 qui envoient des données à ces points de terminaison. Cet article aborde 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

Un compte Azure, que vous pouvez configurer gratuitement.
Instance Azure Digital Twins dans votre abonnement Azure. Si vous n’avez pas d’instance, créez-en une en suivant les étapes décrites dans Configurer une instance et une authentification. Ayez les valeurs suivantes de la configuration à disposition pour les utiliser plus tard dans cet article.
- Nom de l’instance
- Groupe de ressources
Vous trouverez ces informations dans le portail Azure après avoir configuré votre instance.

Si vous envisagez d’utiliser Azure CLI en suivant ce guide, suivez les instructions de la section suivante.

Préparation de votre environnement pour Azure CLI

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.

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 :

Sujet 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
Sujet Service Bus

Avant de lier un point de terminaison à Azure Digital Twins, vous devez créer la rubrique Event Grid, le hub d’événements ou la rubrique Service Bus que vous utilisez pour le point de terminaison.

Utilisez le graphique suivant pour voir les ressources que vous devez configurer 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 Event Grid Schema ou Cloud Event Schema 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 des clés
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 des clés

Créer le point de terminaison

Après avoir créé les ressources de point de terminaison, vous pouvez créer le point de terminaison Azure Digital Twins. Utilisez les onglets suivants pour sélectionner votre expérience préférée.

Portail
INTERFACE DE LIGNE DE COMMANDE

Pour créer un point de terminaison, accédez à la page de votre instance dans le portail Azure. Vous pouvez trouver l’instance en entrant son nom dans la barre de recherche du portail.

Dans le menu de l’instance, sélectionnez Connecter les > points de terminaison de sortie. Ensuite, dans la page Points de terminaison , sélectionnez + Créer un point de terminaison. Cette action ouvre la page Créer un point de terminaison .
Entrez le nom de votre point de terminaison, puis choisissez le type de point de terminaison.
Spécifiez les autres informations requises pour votre type de point de terminaison, y compris votre abonnement et les ressources du point de terminaison décrites plus haut.
1. Pour les points de terminaison Event Hubs et Service Bus uniquement, sélectionnez 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. L’identité affectée par le système est disponible uniquement si vous avez activé une identité affectée par le système pour l’instance. 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é plus loin dans cet article.
Terminez la création de votre point de terminaison en sélectionnant Enregistrer.

Après avoir créé votre point de terminaison, vous pouvez vérifier qu’il a été créé correctement en vérifiant l’icône de notification dans la barre supérieure du portail Azure :

Capture d’écran de la notification pour vérifier la création d’un point de terminaison dans le 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 que vous avez 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. En règle générale, vous utilisez 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.

Les exemples suivants montrent comment créer des points de terminaison à l’aide de la commande az dt endpoint create pour l’interface CLI Azure Digital Twins. Remplacez les espaces réservés dans les commandes par les informations de vos propres ressources.

Pour créer un point de terminaison Event Grid :

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Pour créer un point de terminaison Event Hubs (authentification basée sur une clé) :

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Pour créer un point de terminaison de rubrique Service Bus (authentification basée sur une clé) :

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Une fois ces commandes exécutées, la rubrique Event Grid, le hub d’événements ou la rubrique Service Bus est disponible en tant que point de terminaison dans Azure Digital Twins. Le point de terminaison a le nom que vous avez fourni avec l’argument --endpoint-name . En règle générale, vous utilisez 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 requise pour le routage, mais elle peut aider l’instance à accéder facilement à d’autres ressources protégées par Microsoft Entra, comme les destinations Event Hubs, Service Bus et un conteneur Stockage Azure. 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 une identité managée pour l’instance

Utilisez les onglets suivants pour obtenir des instructions qui correspondent à votre expérience préférée.

Portail
INTERFACE DE LIGNE DE COMMANDE

Tout d’abord, veillez à activer une identité managée pour votre instance Azure Digital Twins.

Vérifiez ensuite que vous avez le rôle Propriétaire de données Azure Digital Twins sur l’instance. Vous trouverez des instructions dans Configurer les autorisations d’accès utilisateur.

2. Affecter des rôles Azure à l’identité

Après avoir créé une identité managée pour votre instance Azure Digital Twins, attribuez-lui les rôles appropriés pour s’authentifier auprès de différents types de points de terminaison pour le routage d’é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

Assurez-vous de bien suivre cette étape. Sans cela, l'identité ne peut pas accéder à vos points de terminaison et les événements ne sont pas livrés.

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 disposant d’autorisations plus élevées (comme les rôles Propriétaire de données) fonctionnent également.

Destination	Rôle Azure
Hubs d'événements Azure	Azure Event Hubs - Expéditeur de données
Azure Service Bus (Bus de service Azure)	Expéditeur de données Azure Service Bus
Conteneur de stockage Windows Azure	Contributeur aux données Blob du stockage

Utilisez les onglets suivants pour attribuer le rôle à l’aide de votre expérience préférée.

Portail
INTERFACE DE LIGNE DE COMMANDE

Pour attribuer un rôle à l’identité, ouvrez 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é managée de votre instance Azure Digital Twins. Pour connaître les étapes détaillées, consultez Attribuer des rôles Azure à l’aide du portail Azure.

Paramètre	Valeur
Rôle	Sélectionnez le rôle souhaité dans les options.
Attribuer l’accès à	Identité gérée
Membres	Sélectionnez l'identité gérée attribuée par l'utilisateur ou par le système de l'instance Azure Digital Twins à laquelle le rôle est attribué. Une identité affectée par l’utilisateur a le nom que vous avez choisi lors de la création de l’identité, et une identité affectée par le système a un nom qui correspond au nom de votre instance Azure Digital Twins.

Vous pouvez ajouter le paramètre --scopes à la commande az dt create pour attribuer l’identité à une ou plusieurs étendues ayant le rôle spécifié. Utilisez cette commande lors de la création de l’instance ou ultérieure en passant le nom d’une instance existante.

Voici un exemple qui crée une instance avec une identité managée affectée par le système, et qui attribue à cette identité un rôle personnalisé appelé MyCustomRole dans un hub d’événements.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

Pour plus d’exemples d’attributions de rôles à l’aide de cette commande, consultez la documentation de référence relative à az dt create.

Vous pouvez également utiliser le groupe de commandes az role assignment pour créer et gérer des rôles. Utilisez cette commande pour prendre en charge d’autres scénarios où vous ne souhaitez pas regrouper l’attribution de rôle avec la commande create.

3. Créer un point de terminaison avec une authentification basée sur l’identité

Après avoir configuré une identité managée pour votre instance Azure Digital Twins et lui assignant les rôles appropriés, créez 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).

Remarque

Vous ne pouvez pas modifier un point de terminaison que vous avez créé avec l’identité basée sur des clés pour passer à l’authentification basée sur l’identité. Vous devez choisir le type d’authentification lorsque vous créez d’abord le point de terminaison.

Utilisez les sections suivantes pour créer le point de terminaison à l’aide de votre expérience préférée.

Portail
INTERFACE DE LIGNE DE COMMANDE

Commencez par 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.

Ajoutez des identités managées à un point de terminaison en ajoutant des paramètres à la az dt endpoint create commande. Pour plus d’informations sur cette commande, consultez sa documentation de référence ou les instructions générales pour créer un point de terminaison Azure Digital Twins.

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

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

Pour créer un point de terminaison qui utilise l’authentification affectée par le système, spécifiez le type d’authentification IdentityBased avec le paramètre --auth-type. L’exemple suivant illustre cette fonctionnalité pour un point de terminaison Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

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

Pour créer un point de terminaison qui utilise l’authentification d’identité affectée par l’utilisateur, spécifiez l’ID de ressource d’identité affectée par l’utilisateur avec le paramètre --user. L’exemple suivant illustre cette fonctionnalité pour un point de terminaison Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

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

Une identité est gérée séparément des points de terminaison qui l’utilisent. Il est donc important de déterminer comment toute modification apportée à l’identité ou à ses rôles peut affecter les points de terminaison de votre instance Azure Digital Twins. Si vous désactivez l’identité ou supprimez un rôle nécessaire pour un point de terminaison, le point de terminaison devient inaccessible et le flux d’événements est interrompu.

Pour continuer à utiliser un point de terminaison configuré avec une identité managée que vous avez désactivée, supprimez le point de terminaison et recréez-le 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.

Options de point de terminaison : lettres mortes

Lorsqu’un point de terminaison ne peut pas remettre un événement dans un certain délai ou un certain nombre de tentatives, 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. Toutefois, pour créer un point de terminaison avec la mise en lettres mortes activée, vous devez utiliser l’interface CLI Azure Digital Twins ou les API de plan de contrôle.

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 lettres mortes, vous devez disposer d’un compte de stockage avec un conteneur dans votre compte Azure.

Lors de la création du point de terminaison, vous fournissez l’URI de ce conteneur. L'emplacement des lettres mortes est fourni au point de terminaison sous la forme d'un 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 est au format : https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Pour configurer ces ressources de stockage dans votre compte Azure, suivez les étapes décrites dans la section suivante. Après avoir configuré les ressources de stockage, vous pouvez configurer la connexion de point de terminaison.

Pour créer un compte de stockage dans votre abonnement Azure, suivez les étapes décrites dans Créer un compte de stockage. Notez le nom du compte de stockage pour pouvoir l’utiliser ultérieurement.
Pour créer un conteneur dans le nouveau compte de stockage, suivez les étapes décrites dans Créer un conteneur. Notez le nom du conteneur pour pouvoir l’utiliser ultérieurement.

Créez un jeton SAS

Ensuite, créez un jeton SAS pour votre compte de stockage que le point de terminaison peut utiliser pour y accéder.

Portail
INTERFACE DE LIGNE DE COMMANDE

Accédez à votre compte de stockage dans le portail Azure (vous pouvez le trouver par nom avec la barre de recherche du portail).
Dans la page du compte de stockage, choisissez le lien sécurité + mise en réseau de signature d’accès partagé > dans la barre de navigation gauche pour commencer à configurer le 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 souhaités. Vous devez sélectionner au moins une case dans chaque catégorie. Sous Autorisations autorisées, choisissez Écriture. Vous pouvez également sélectionner d’autres autorisations.
Définissez les valeurs souhaitées pour les paramètres restants.
Lorsque vous avez terminé, sélectionnez Générer SAS et la chaîne de connexion pour générer le jeton SAS.
L’exécution de ce processus génère plusieurs valeurs de chaîne de connexion et SAS en bas de la même page, en dessous des sélections de paramètres. Faites défiler vers le bas pour afficher les valeurs et utilisez l’icône Copier dans le presse-papiers pour copier la valeur du jeton SAS. Enregistrez-la en vue d’une utilisation ultérieure.

Récupérez les clés de votre compte de stockage à l’aide de la commande suivante et copiez la valeur de l’une de vos clés :
```
az storage account keys list --account-name <storage-account-name>
```
Sélectionnez une date d’expiration et générez le jeton SAP pour votre compte de stockage à l’aide de la commande suivante :
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
La sortie de cette commande est le jeton SAS. Copiez la valeur du jeton SAP à utiliser ultérieurement.

Remarque

L’exemple de jeu de paramètres dans la commande précédente inclut les services « blob », « file », « queue » et « table » (--services bfqt), un type de ressource « object » (--resource-types o) et des autorisations « write » (--permissions w).

Pour plus d’informations sur la commande az storage account generate-sas et ses paramètres, consultez la documentation CLI Azure.

Créer le point de terminaison de lettres mortes

Portail
INTERFACE DE LIGNE DE COMMANDE

Pour créer un point de terminaison avec la mise en lettres mortes activée, utilisez les commandes CLI ou les API du plan de contrôle pour créer votre point de terminaison. Vous ne pouvez pas créer ce type de point de terminaison dans 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.

Pour créer un point de terminaison avec mise en file d’attente de lettres mortes, ajoutez le paramètre --deadletter-sas-uri à la commande az dt endpoint create qui crée un point de terminaison.

La valeur du paramètre représente l’URI SAS de lettre morte constitué du nom du compte de stockage, du nom du conteneur et du jeton SAP que vous avez collectés à la section précédente. Ce paramètre crée le point de terminaison avec l’authentification basée sur une clé. Ce paramètre se présente ainsi :

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Conseil

Pour créer un point de terminaison de lettre morte avec l’authentification basée sur l’identité, ajoutez à la même commande le paramètre de lettre morte de cette section et le paramètre d’identité managée approprié.

Vous pouvez également créer des points de terminaison de lettres mortes à l’aide des API de plan de contrôle Azure Digital Twins au lieu de l’interface CLI. Pour cela, consultez la documentation DigitalTwinsEndpoint pour savoir comment structurer la requête et ajouter les paramètres de lettres mortes.

Schéma de stockage des messages

Une fois que vous avez configuré le point de terminaison avec le dead-lettering, les messages dead-lettering sont stockés dans votre compte de stockage au format suivant :

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Les messages de lettres mortes correspondent au schéma de l'événement d'origine que votre point de terminaison d'origine était censé délivrer.

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

Après avoir créé un point de terminaison, définissez un itinéraire d’événement pour envoyer des données au point de terminaison. Les itinéraires d’événements vous permettent de configurer le flux d’événements dans tout le système et vers les services en aval. Un itinéraire unique peut autoriser plusieurs notifications et types d’événements. Créez un itinéraire d’événement vers votre point de terminaison avec les instructions de Créer des itinéraires et des filtres.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-06-20