Créer des itinéraires et des filtres d’évènement dans Azure Digital Twins

Article
08/01/2024

Cet article vous guide tout au long du processus de création d’itinéraires d’évènement en utilisant le Portail Azure, les commandes d’itinéraire Azure CLI az dt route, les API de plan de données Event Routes et lekit de développement logiciel (SDK) .NET (C#).

Le routage de 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 deuxième étape, la configuration d’itinéraires pour contrôler les évènements remis aux points de terminaison Azure Digital Twin. Pour continuer avec cet article, vous devez avoir déjà créé des 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.
Créer un point de terminaison en utilisant les instructions de Créer des points de terminaison. Dans cet article, vous créez un itinéraire pour envoyer des données à ce point de terminaison.

Suivez ensuite les instructions ci-dessous si vous avez l’intention 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éation d’un itinéraire d’événements

Après avoir créé un point de terminaison, vous devez définir un itinéraire d’évènement pour envoyer effectivement des données au point de terminaison. 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. En savoir plus sur les routes d’événements dans Points de terminaison et routes d’événements.

Remarque

Vérifiez que vous avez créé au moins un point de terminaison, comme décrit dans les Prérequis avant de passer à la création d’un itinéraire.

Si vous avez que récemment déployé vos points de terminaison, vérifiez que le déploiement est terminé avant de tenter de les utiliser pour un nouvel itinéraire d’évènement. Si le déploiement de l’itinéraire échoue parce que les points de terminaison ne sont pas prêts, patientez quelques minutes, puis réessayez.

Si vous créez un script pour ce flux, vous pouvez prendre cela en compte en intégrant un temps d’attente de 2-3 minutes pour permettre au service de point de terminaison d’achever le déploiement avant de passer à la configuration de l’itinéraire.

Une définition d’itinéraire peut contenir les éléments suivants :

nom de l’itinéraire que vous souhaitez utiliser ;
nom du point de terminaison que vous souhaitez utiliser ;
filtre définissant les événements envoyés au point de terminaison.
- Pour désactiver l’itinéraire afin qu’aucun événement ne soit envoyé, utilisez une valeur de filtre false.
- Pour activer un itinéraire qui n’a pas de filtrage spécifique, utilisez une valeur de filtre true.
- Pour plus d’informations sur les autres types de filtre, consultez la section Filtrer les événements ci-dessous

En l’absence de nom d’itinéraire, aucun message n’est acheminé en dehors d’Azure Digital Twins. S’il existe un nom d’itinéraire et que le filtre est true, tous les messages sont acheminés vers le point de terminaison. Si un nom d’itinéraire et un filtre différent sont ajoutés, les messages sont filtrés en fonction du filtre.

Les itinéraires d'événements peuvent être créés à l’aide duportail Azure, des API de plan de données EventRoutes ou des commandes CLI az dt route. Le reste de cette section décrit le processus de création.

Pour créer un itinéraire d’événement, accédez à la page de détails de votre instance Azure Digital Twins 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 Itinéraires d’événements. Ensuite, à partir de la page Itinéraires d’événements qui suit, sélectionnez + Créer un itinéraire d’événements.

Dans la page Créer un itinéraire d’événement qui s’ouvre, choisissez au minimum :

Un nom pour votre itinéraire dans le champ Nom
Le point de terminaison que vous souhaitez utiliser pour créer la route

Pour que l’itinéraire soit activé, vous devez également ajouter un filtre d’itinéraires d’événements true au minimum. (Laisser la valeur false par défaut créera l’itinéraire, mais aucun événement ne lui sera envoyé.) Pour ce faire, appuyez sur le bouton bascule de l’éditeur avancé pour l’activer, puis écrivez true dans la zone Filtre.

Lorsque vous avez terminé, sélectionnez le bouton Enregistrer pour créer votre itinéraire d’événement.

Cette section montre comment créer un itinéraire d’événement à l’aide du Kit de développement logiciel (SDK) .net (C#).

CreateOrReplaceEventRouteAsync est l’appel du kit de développement logiciel (SDK) utilisé pour ajouter un itinéraire d’événement. Voici un exemple d’utilisation :

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

Conseil

Toutes les fonctions du Kit de développement logiciel (SDK) sont disponibles en versions synchrone et asynchrone.

Exemple de code SDK d’itinéraire d’événement

L’exemple de méthode suivant montre comment créer, lister et supprimer une route d’événement avec le SDK C# :

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Filtrer les événements

Comme décrit ci-dessus, les itinéraires ont un champ Filtre. Si la valeur de filtre sur votre itinéraire est false, aucun événement n’est envoyé à votre point de terminaison.

Dès que vous activez le filtre minimal true, les points de terminaison reçoivent plusieurs types d’événements d’Azure Digital Twins :

Données de télémétrie déclenchées par des jumeaux numériques en utilisant l’API de service Azure Digital Twins
notifications de changement de propriété de jumeau, déclenchées par des modifications des propriétés d’un jumeau dans l’instance Azure Digital Twins ;
événements de cycle de vie déclenchés lors de la création ou de la suppression de jumeaux ou de relations ;

Vous pouvez restreindre les types d’événements envoyés en définissant un filtre plus spécifique.

Remarque

Les filtres respectent la casse et doivent correspondre à la casse de la charge utile. Pour les filtres de télémétrie, cela signifie que la casse doit correspondre à la casse des données de télémétrie envoyées par l’appareil.

Portail
API

Pour ajouter un filtre d’événements lors de la création d’une route d’événement, utilisez la section Ajouter un filtre de route d’événement de la page Créer une route d’événement.

Vous pouvez sélectionner l’une des options de filtre courantes de base ou utiliser les options de filtre avancées pour écrire vos propres filtres personnalisés.

Utiliser les filtres de base

Pour utiliser les filtres de base, développez l’option Types d’événements, puis cochez les cases correspondant aux événements que vous souhaitez envoyer à votre point de terminaison.

Cette opération remplit automatiquement la zone de texte de filtre avec le texte du filtre que vous avez sélectionné :

Utiliser les filtres avancés

Vous pouvez également utiliser l’option de filtre avancée pour écrire vos propres filtres personnalisés.

Pour créer un itinéraire d’événement avec des options de filtre avancées, appuyez sur le bouton bascule de l’éditeur avancé pour l’activer. Vous pouvez ensuite écrire vos propres filtres d’événement dans la zone Filtre :

Vous pouvez utiliser les API de plan de données Event Routes pour écrire des filtres personnalisés. Pour ajouter un filtre, vous pouvez utiliser une requête PUT pour https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 avec le corps suivant :

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Filtres de routage pris en charge

Voici les filtres d’itinéraire pris en charge.

Nom du filtre	Description	Schéma du texte du filtre	Valeurs prises en charge
True / False	Autorise la création d'un itinéraire sans filtrage ou la désactivation d'un itinéraire afin qu'aucun événement ne soit envoyé	`<true/false>`	`true` = l’itinéraire est activé sans filtrage. `false` = l’itinéraire est désactivé
Type	Type d’événement circulant dans votre instance de jumeau numérique.	`type = '<event-type>'`	Les valeurs de type d'événement possibles sont les suivantes : `Microsoft.DigitalTwins.Twin.Create` `Microsoft.DigitalTwins.Twin.Delete` `Microsoft.DigitalTwins.Twin.Update` `Microsoft.DigitalTwins.Relationship.Create` `Microsoft.DigitalTwins.Relationship.Update` `Microsoft.DigitalTwins.Relationship.Delete` `microsoft.iot.telemetry`
Source	Nom de l’instance Azure Digital Twins.	`source = '<host-name>'`	Les valeurs de nom d’hôte possibles sont les suivantes : Pour les notifications : `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` Pour la télémétrie : `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
Objet	Description de l’événement dans le contexte de la source de l’événement ci-dessus	`subject = '<subject>'`	Les valeurs d'objet sont les suivantes : Pour les notifications : l’objet est `<twin-ID>` ou un format d’URI pour les objets identifiés de façon unique par plusieurs éléments ou ID : `<twin-ID>/relationships/<relationship-ID>` Pour la télémétrie : l’objet est le chemin du composant (si la télémétrie est émise à partir d’un composant jumeau), par exemple `comp1.comp2`. Si la télémétrie n’est pas émise à partir d’un composant, son champ d’objet est vide.
Schéma de données	ID de modèle DTDL	`dataschema = '<model-dtmi-ID>'`	Pour la télémétrie : le schéma de données est l'ID de modèle du jumeau ou du composant qui émet les données de télémétrie. Par exemple, `dtmi:example:com:floor4;2` Pour les notifications (créer/supprimer) : le schéma de données est accessible dans le corps de la notification à `$body.$metadata.$model`. Pour les notifications (mettre à jour) : le schéma de données est accessible dans le corps de la notification à `$body.modelId`
Type de contenu	Type de contenu de la valeur de données	`datacontenttype = '<content-type>'`	Le type de contenu est `application/json`
Version de spécification	Version du schéma d’événement que vous utilisez	`specversion = '<version>'`	La version doit être `1.0`. Cette valeur indique le schéma CloudEvents version 1.0
Corps de la notification	Référencer n’importe quelle propriété dans le champ `data` d’une notification	`$body.<property>`	Consultez Notifications d'événements pour accéder à des exemples de notifications. Toute propriété du champ `data` peut être référencée à l’aide de `$body`

Remarque

Azure Digital Twins ne prend actuellement pas en charge le filtrage d’événements basés sur les champs d’un tableau. Cela comprend le filtrage des propriétés au sein d’une section patch d’une notification de modification de jumeau numérique.

Les types de données suivants sont pris en charge en tant que valeurs retournées par les références aux données ci-dessus :

Type de données	Exemple
Chaîne	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Integer	`$body.errorCode > 200`
Double	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Null	`$body.prop != null`

Les opérateurs suivants sont pris en charge lors de la définition de filtres de route :

Famille	Opérateurs	Exemple
Logical	AND, OR, ( )	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
Comparaison	<, <=, >, >=, =, !=	`$body.temperature <= 5.5`

Les fonctions suivantes sont prises en charge lors de la définition de filtres de route :

Fonction	Description	Exemple
STARTS_WITH(x,y)	Retourne la valeur true si la valeur `x` commence par la chaîne `y`.	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
ENDS_WITH(x,y)	Retourne la valeur true si la valeur `x` se termine par la chaîne `y`.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
CONTAINS(x,y)	Retourne la valeur true si la valeur `x` contient la chaîne `y`.	`CONTAINS(subject, '<twin-ID>')`

Lorsque vous implémentez ou mettez à jour un filtre, quelques minutes peuvent s’écouler avant que la modification apparaisse dans le pipeline de données.

Surveiller les itinéraires d’événements

Vous pouvez consulter les métriques de routage telles que le nombre, la latence et le taux d’échec dans le portail Azure.

Pour plus d’informations sur l’affichage et la gestion des métriques avec Azure Monitor, consultez Démarrage de l’explorateur de mesures. Pour obtenir la liste complète des mesures de routage disponibles pour Azure Digital Twins, consultez Mesures de routage Azure Digital Twins.

Étapes suivantes

Apprenez-en davantage sur les différents types de messages d’événements que vous pouvez recevoir :

Notifications d’événement

Partage via

Créer des itinéraires et des filtres d’évènement dans Azure Digital Twins

Prérequis

Préparation de votre environnement pour Azure CLI

Création d’un itinéraire d’événements

Exemple de code SDK d’itinéraire d’événement

Filtrer les événements

Utiliser les filtres de base

Utiliser les filtres avancés

Filtres de routage pris en charge

Surveiller les itinéraires d’événements

Étapes suivantes

Commentaires

Ressources supplémentaires