Configurer la gestion des événements entre jumeaux

Article
03/09/2023

Cet article montre comment envoyer des événements d’un jumeau à l’autre de sorte que, lorsqu’un des jumeaux numériques du graphe est mis à jour, les jumeaux associés concernés par ces informations sont également mis à jour. Cette gestion des événements vous aidera à créer un graphe Azure Digital Twins entièrement connecté : les données qui arriveront dans Azure Digital Twins à partir de sources externes comme IoT Hub seront propagées dans tout le graphe.

Pour configurer ce traitement des événements de jumeau à jumeau, vous allez créer une fonction Azure qui surveille les événements du cycle de vie des jumeaux. La fonction reconnaît les événements qui doivent concerner les autres jumeaux du graphique et utilise les données de l’événement pour mettre à jour les jumeaux concernés en conséquence.

Prérequis

Pour définir la gestion entre jumeaux, vous aurez besoin d’une instance Azure Digital Twins avec laquelle travailler. Pour des instructions sur la façon de créer une instance, consultez Configurer une instance et l’authentification Azure Digital Twins. L’instance doit contenir au moins deux jumeaux entre lesquels vous voulez envoyer des données.

De manière facultative, vous pouvez configurer l’ingestion de télémétrie automatique via IoT Hub pour vos jumeaux également. Ce processus n’est pas nécessaire pour envoyer des données de jumeau à jumeau, mais il s’agit d’un élément important d’une solution complète où le graphe de jumeau est piloté par les données de télémétrie des appareils en direct.

Envoyer des événements de jumeau à un point de terminaison

Pour configurer la gestion d’événement entre jumeaux, commencez par créer un point de terminaison dans Azure Digital Twins et un itinéraire pour ce point de terminaison. Les jumeaux en cours de mise à jour utilisent l’itinéraire pour envoyer des informations sur les événements de mise à jour au point de terminaison (où Event Grid peut les sélectionner ultérieurement et les transmettre à une fonction Azure pour traitement).

Créer la rubrique Event Grid

Event Grid est un service Azure qui permet de router et de remettre les événements des services Azure à d’autres emplacements au sein d’Azure. Vous pouvez créer une rubrique Event Grid pour collecter certains événements d’une source ; les abonnés peuvent ensuite écouter la rubrique pour recevoir les événements au fur et à mesure de leur arrivée.

Dans Azure CLI, exécutez la commande suivante pour créer une rubrique Event Grid :

az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>

Les informations générées par cette commande décrivent la rubrique Event Grid que vous avez créée. Enregistrez le nom que vous avez donné à votre rubrique Event Grid, car vous l’utiliserez plus tard.

Créer le point de terminaison

Ensuite, créez un point de terminaison Event Grid dans Azure Digital Twins, qui connectera votre instance à votre rubrique Event Grid. Utilisez la commande ci-dessous, en indiquant le nom de votre rubrique Event Grid de l’étape précédente ainsi que les autres champs d’espace réservé selon les besoins.

az dt endpoint create eventgrid --dt-name <Azure-Digital-Twins-instance> --eventgrid-resource-group <your-resource-group> --eventgrid-topic <your-event-grid-topic> --endpoint-name <name-for-your-Azure-Digital-Twins-endpoint>

Les informations générées par cette commande décrivent le point de terminaison que vous avez créé.

Recherchez le champ provisioningState dans la sortie, puis vérifiez que sa valeur est « Succeeded ».

Il peut également indiquer « Approvisionnement », ce qui signifie que le point de terminaison est toujours en cours de création. Si tel est le cas, attendez quelques secondes, puis exécutez la commande suivante pour vérifier l’état du point de terminaison. Répétez l’opération jusqu’à ce que provisioningState indique « Succeeded ».

az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint>

Enregistrez le nom de votre point de terminaison, car vous l’utiliserez plus tard.

Créer la route

Vous allez à présent créer une route Azure Digital Twins qui envoie les événements au point de terminaison Event Grid que vous avez créé.

Utilisez la commande CLI suivante, en remplissant le nom de votre point de terminaison à partir de l’étape précédente et les autres champs d’espace réservé selon les besoins. Cette commande transfère tous les événements qui se produisent dans le graphe de jumeaux.

Conseil

Vous pouvez limiter les événements à des événements spécifiques si vous le souhaitez, à l’aide de filtres.

az dt route create --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> --route-name <name-for-your-Azure-Digital-Twins-route>

Les informations générées par cette commande décrivent la route que vous avez créé.

Notes

L’approvisionnement des points de terminaison (de l’étape précédente) doit être terminé pour que vous puissiez configurer un itinéraire des événements qui les utilise. Si la création d’itinéraires échoue parce que les points de terminaison ne sont pas prêts, patientez quelques minutes, puis réessayez.

Créer une fonction Azure pour mettre les jumeaux à jour

Ensuite, créez une fonction Azure qui écoute sur le point de terminaison et reçoit les événements jumeaux qui lui sont envoyés via l’itinéraire. La logique de la fonction doit utiliser les informations contenues dans les événements pour déterminer quels autres jumeaux doivent être mis à jour, puis effectuer les mises à jour.

Tout d’abord, créez un projet Azure Functions.

Pour ce faire, vous pouvez utiliser Visual Studio (pour obtenir des instructions, voir Développer Azure Functions à l’aide de Visual Studio), Visual Studio Code (pour obtenir des instructions, voir Créer une fonction C# dans Azure à l’aide de Visual Studio Code) ou d’Azure CLI (pour obtenir des instructions, consultez Créer une fonction C# dans Azure à partir de la ligne de commande).
Ajoutez les packages suivants à votre projet (vous pouvez utiliser le gestionnaire de package Visual Studio NuGet ou la commande dotnet add package dans un outil de ligne de commande).
Renseignez la logique de votre fonction. Vous pouvez afficher un exemple de code de fonction pour plusieurs scénarios dans le référentiel azure-digital-twins-getting-started pour vous aider à démarrer.
Publiez la fonction sur Azure à l’aide de votre méthode préférée.

Pour obtenir des instructions sur la façon de publier une fonction à l’aide de Visual Studio, consultez Développer des Azure Functions à l’aide de Visual Studio. Pour obtenir des instructions sur la publication de la fonction à l’aide de Visual Studio Code, consultez Créer une fonction C# dans Azure à l’aide de Visual Studio Code. Pour obtenir des instructions sur la publication de la fonction à l’aide d’Azure CLI, consultez Créer une fonction C# dans Azure à partir de la ligne de commande.

Une fois le processus de publication de la fonction terminé, vous pouvez utiliser cette commande Azure CLI pour vérifier que la publication a réussi. Il existe des espaces réservés pour votre groupe de ressources, le nom de votre application de fonction et le nom de votre fonction spécifique. La commande affiche des informations sur votre fonction.

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name <your-function>

Configurer l’application de fonction

Pour que votre fonction puisse accéder à Azure Digital Twins, elle a besoin d’informations sur l’instance et l’autorisation pour y accéder. Dans cette section, vous attribuez un rôle d’accès à la fonction et configurez les paramètres de l’application afin qu’elle puisse accéder à votre instance.

Exécutez les commandes suivantes dans Azure Cloud Shell ou une interface locale d’Azure CLI.

Remarque

Cette section doit être effectuée par un utilisateur Azure qui dispose des autorisations nécessaires pour gérer l’accès utilisateur aux ressources Azure, y compris l’octroi et la délégation d’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 plus d’informations sur les exigences d’autorisation pour les rôles Azure Digital Twins, consultez Configurer une instance et l’authentification.

Attribuer un rôle d’accès

La fonction Azure nécessite un jeton de porteur pour transmission. Pour vous assurer que le jeton du porteur est transmis, accordez à l’Application de fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins, ce qui permettra à l’application de fonction d’effectuer des activités de plan de données sur l’instance.

Utilisez la commande suivante pour créer une identité managée affectée par le système pour votre fonction (si la fonction en a déjà une, cette commande imprime les détails). Notez le principalId champ dans la sortie. Vous utiliserez cet ID pour faire référence à la fonction afin de pouvoir lui accorder des autorisations à l’étape suivante.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Utilisez la principalId valeur dans la commande suivante afin d’affecter à la fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Configurer les paramètres de l’application

Ensuite, rendez l’URL de votre instance Azure Digital Twins accessible à votre fonction en définissant une variable d’environnement pour celle-ci.

Conseil

L’URL de l’instance Azure Digital Twins est créée en ajoutant https:// au début du nom d’hôte de votre instance. Pour afficher le nom d’hôte, ainsi que toutes les propriétés de votre instance, exécutez az dt show --dt-name <your-Azure-Digital-Twins-instance>.

La commande suivante définit une variable d’environnement pour l’URL d’instance que votre fonction utilisera chaque fois qu’elle aura besoin d’accéder à l’instance.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Connecter la fonction au point de terminaison

Ensuite, inscrivez la fonction Azure au point de terminaison Event Grid créé précédemment. Ainsi, les données peuvent circuler, en passant par la rubrique Event Grid, d’un jumeau mis à jour à la fonction. Celle-ci peut si nécessaire utiliser les informations de l’événement pour mettre à jour d’autres jumeaux.

Pour abonner votre fonction Azure, vous allez créer un abonnement Event Grid qui envoie des données de la rubrique Event Grid déjà créée à votre fonction Azure.

Utilisez la commande CLI suivante, en renseignant les espaces réservés pour votre ID d’abonnement, le groupe de ressources, l’application de fonction et le nom de la fonction.

az eventgrid event-subscription create --name <name-for-your-event-subscription> --source-resource-id /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.EventGrid/topics/<your-event-grid-topic> --endpoint-type azurefunction --endpoint /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app-name>/functions/<function-name>

À présent, votre fonction peut recevoir des événements par le biais de votre rubrique Event Grid. La configuration du flux de données est terminée.

Tester et vérifier les résultats

La dernière étape consiste à vérifier que le flux fonctionne, en mettant à jour un jumeau et en vérifiant que les jumeaux concernés sont mis à jour en fonction de la logique dans votre fonction Azure.

Pour lancer le processus, mettez à jour le jumeau qui est la source du flux d’événement. Vous pouvez utiliser l’Azure CLI, le kit de développement logiciel (SDK) Azure Digital Twins ou les API REST Azure Digital Twins pour effectuer la mise à jour.

Ensuite, interrogez votre instance Azure Digital Twins pour le jumeau concerné. Vous pouvez utiliser l’Azure CLI ou les API REST et le kit de développement logiciel (SDK) Azure Digital Twins. Vérifiez que le jumeau a reçu les données et les a mises à jour comme prévu.

Étapes suivantes

Dans cet article, vous configurez la gestion des événements entre jumeaux dans Azure Digital Twins. Ensuite, configurez une fonction Azure pour déclencher automatiquement ce flux en fonction de la télémétrie entrante à partir de périphériques IoT Hub : Ingérer la télémétrie depuis IoT Hub.