Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Les enrichissements de messages sont la capacité du IoT Hub à horodater des messages avec des informations supplémentaires avant que les messages ne soient envoyés au point de terminaison désigné. Vous pouvez utiliser les enrichissements de messages pour inclure des données permettant de simplifier le traitement en aval. Par exemple, enrichir des messages de télémétrie d’appareil avec une balise de jumeau d’appareil peut réduire la charge de clients en leur évitant d’effectuer des appels d’API doubles pour cette information.
Un enrichissement de message comporte trois éléments clés :
Clé ou nom de l’enrichissement
Une valeur
Un ou plusieurs points de terminaison pour lesquels l’enrichissement doit être appliqué.
La clé est une chaîne. Une clé ne peut contenir que des caractères alphanumériques ou ces caractères spéciaux : trait d’union (-), trait de soulignement (_) et point (.).
La valeur peut être l’un des exemples suivants :
Toute chaîne statique. Les valeurs dynamiques telles que les conditions, la logique, les opérations et les fonctions ne sont pas autorisées. Par exemple, si vous développez une application SaaS utilisée par plusieurs clients, vous pouvez affecter un identificateur à chaque client et rendre cet identificateur disponible dans l’application. Lorsque l’application s’exécute, IoT Hub marque les messages de télémétrie de l’appareil avec l’identificateur du client, ce qui permet de traiter les messages différemment pour chaque client.
Nom du hub IoT envoyant le message. Cette valeur est $iothubname.
Informations du jumeau d’appareil, comme son chemin d’accès. Les exemples sont $twin.tags.field et $twin.tags.latitude.
Remarque
À ce stade, seuls $iothubname, $twin.tags, $twin.properties.souhaité et $twin.properties.reported sont des variables prises en charge pour l’enrichissement des messages. En outre, seuls les types primitifs sont pris en charge pour les enrichissements. Les messages ne peuvent pas être enrichis avec des types d’objets.
Les enrichissements de messages sont ajoutés en tant que propriétés d’application aux messages envoyés aux points de terminaison choisis.
Application des enrichissements
Les messages peuvent provenir de n’importe quelle source de données prise en charge par le routage des messages IoT Hub, y compris les exemples suivants :
- télémétrie des appareils, telles que la température ou la pression
- notifications de modification du jumeau d’appareil, modifications du jumeau d’appareil
- événements de cycle de vie de l’appareil, tels que lorsque l’appareil est créé ou supprimé
Vous pouvez ajouter des enrichissements aux messages qui vont au point de terminaison intégré d’un hub IoT ou aux messages routés vers des points de terminaison personnalisés tels que le stockage Blob Azure, une file d’attente Service Bus ou une rubrique Service Bus.
Vous pouvez également ajouter des enrichissements aux messages publiés dans Event Grid en créant d’abord un abonnement Event Grid avec le type de message de télémétrie de l’appareil. En fonction de cet abonnement, nous allons créer un itinéraire par défaut dans Azure IoT Hub pour la télémétrie. Cet itinéraire unique peut gérer tous vos abonnements Event Grid. Vous pouvez ensuite configurer des enrichissements pour le point de terminaison à l’aide de l’onglet Enrichir les messages de la section Routage des messages IoT Hub. Pour plus d’informations sur la réaction aux événements à l’aide d’Event Grid, consultez IoT Hub et Event Grid.
Les enrichissements sont appliqués par point de terminaison. Si vous spécifiez cinq enrichissements à marquer pour un point de terminaison spécifique, tous les messages qui vont à ce point de terminaison sont marqués avec les cinq mêmes enrichissements.
Les enrichissements peuvent être configurés à l’aide des méthodes suivantes :
| Méthode | Commande |
|---|---|
| Portail | Portail Azure Consultez le didacticiel sur les enrichissements de messages |
| Azure CLI (Interface de ligne de commande Azure) | Az IoT Hub Message-Enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichissement |
L’ajout d’enrichissements de messages n’ajoute pas de latence au routage des messages.
Pour tester les enrichissements de messages, consultez le didacticiel sur les enrichissements de messages
Limites
Vous pouvez ajouter jusqu’à 10 enrichissements par IoT Hub pour ces hubs au niveau standard ou de base. Pour les hubs IoT dans le niveau gratuit, vous pouvez ajouter jusqu’à 2 enrichissements.
Dans certains cas, si vous enrichissez un message avec une valeur définie sur une balise ou une propriété dans le jumeau d’appareil, la valeur sera marquée avec le chemin d’accès du jumeau d’appareil spécifié. Par exemple, si une valeur de l’enrichissement est définie sur $twin.tags.field, les messages sont horodatés avec la chaîne « $twin.tags.field » plutôt qu’avec la valeur de ce champ de l’appareil jumeau. Ce comportement se produit dans les cas suivants :
Votre ioT Hub se trouve dans le niveau de base. Les hubs IoT de niveau de base ne prennent pas en charge les jumeaux d’appareil.
Votre hub IoT est dans le niveau standard, mais le chemin d’accès de l’appareil jumeau utilisé pour la valeur de l’enrichissement n’existe pas. Par exemple, si la valeur de l’enrichissement est définie sur $twin.tags.location et que le jumeau d’appareil n’a pas de propriété location dans les balises, le message est horodaté avec la chaîne « $twin.tags.location ».
Votre hub IoT est dans le niveau standard, mais le chemin d’accès du jumeau d’appareil utilisé pour la valeur de l’enrichissement correspond à un objet plutôt qu’à une simple propriété. Par exemple, si la valeur d’enrichissement est définie sur $twin.tags.location et que la propriété de localisation sous balises est un objet qui contient des propriétés enfants comme
{"building": 43, "room": 503}, le message est marqué avec la chaîne « $twin.tags.location ».
Les mises à jour d’un jumeau d’appareil peuvent prendre jusqu’à cinq minutes pour apparaître dans la valeur d’enrichissement correspondante.
La taille totale du message, y compris les enrichissements, ne peut pas dépasser 256 Ko. Si une taille de message dépasse 256 Ko, le hub IoT supprime le message. Vous pouvez utiliser les métriques IoT Hub pour identifier et déboguer des erreurs lorsque les messages sont supprimés. Par exemple, vous pouvez surveiller les messages de télémétrie incompatibles (d2c.telemetry.egress.invalid) dans les métriques de routage. Pour plus d’informations, consultez Surveiller IoT Hub.
Les enrichissements de message ne s’appliquent pas aux événements de changement de jumeau numérique.
Les modules n’héritent pas des étiquettes jumelles de leurs appareils correspondants. Les enrichissements pour les messages provenant des modules d’appareil (par exemple des modules IoT Edge) doivent utiliser les étiquettes de jumeau définies sur le jumeau du module.
Tarification
Les enrichissements de messages sont disponibles sans frais supplémentaires. Actuellement, vous êtes facturé lorsque vous envoyez un message à un hub IoT. Vous n’êtes facturé qu’une seule fois pour ce message, même si le message passe à plusieurs points de terminaison.
Étapes suivantes
Consultez ces articles pour plus d’informations sur le routage des messages vers un hub IoT :