Créer des itinéraires et des filtres d’événements dans Azure Digital Twins
Cet article vous guide tout au long du processus de création d’itinéraires d’événements à l’aide des Portail Azure, des commandes d’itinéraire Azure CLI az dt route, des API de plan de données Event Routes et du SDK .NET (C#).
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 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 disposer de points de terminaison déjà créés .
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éez un point de terminaison à l’aide des instructions dans Créer des points de terminaison. Dans cet article, vous allez créer un itinéraire pour envoyer des données à ce point de terminaison.
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é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 réellement 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 conditions préalables avant de passer à la création d’un itinéraire.
Si vous n’avez déployé que récemment vos points de terminaison, vérifiez qu’ils ont terminé le déploiement 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 qui définit 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
- Pour désactiver l’itinéraire afin qu’aucun événement ne soit envoyé, utilisez une valeur de filtre
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énementstrue 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.
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 :
- Télémétrie déclenchée par des jumeaux numériques à l’aide de 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 dans les données de télémétrie envoyées par l’appareil.
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 :
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>' |
Voici les valeurs possibles du type d’événement : Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.UpdateMicrosoft.DigitalTwins.Relationship.CreateMicrosoft.DigitalTwins.Relationship.UpdateMicrosoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry |
| Source | Nom de l’instance Azure Digital Twins. | source = '<host-name>' |
Voici les valeurs possibles du nom d’hôte : 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>' |
Voici les valeurs possibles de l’objet : 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>') |
| Entier | $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 :
Commentaires
Bientôt disponible : Tout au long de l’année 2024, nous abandonnerons progressivement le mécanisme de retour d’information GitHub Issues pour le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez : https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour