Enrichissements de messages pour les messages IoT Hub appareil-à-cloud
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 lequel l’enrichissement doit être appliqué.
La clé est une chaîne. Une clé ne peut contenir que des caractères alphanumériques ou les caractères spéciaux suivants : trait d’union (-), trait de soulignement (_) et point (.).
La valeur peut être l’un des exemples suivants :
N’importe quelle chaîne statique. Des valeurs dynamiques telles que des conditions, une logique et des fonctions ne sont pas autorisées. Par exemple, si vous développez une application SaaS utilisée par plusieurs clients, vous pouvez attribuer un identificateur à chaque client et rendre cet identificateur disponible dans l’application. Lorsque l’application s’exécute, IoT Hub horodate 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.
Le nom de l’IoT Hub qui envoie le message. Cette valeur est $iothubname.
Informations du jumeau d’appareil, comme son chemin d’accès. Des exemples seraient $twin.tags.field et $twin.tags.latitude.
Notes
Pour l’instant, seuls $iothubname, $twin.tags, $twin.properties.desired et $twin.properties.reported sont des variables prises en charge pour l’enrichissement de message. 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 message 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 :
- données de télémétrie de l’appareil comme la température ou la pression
- notifications de modification du jumeau d’appareil, modifications du jumeau d’appareil
- événements du cycle de vie de l’appareil, tels que la date de la création ou de la suppression de l’appareil
Vous pouvez ajouter des enrichissements aux messages destinés au point de terminaison intégré d’un hub IoT, ou aux messages acheminés vers des points de terminaison personnalisés comme le stockage d’objets 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. Sur la base 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 d’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 à horodater pour un point de terminaison spécifique, tous les messages acheminés vers ce point de terminaison sont horodatés avec les cinq mêmes enrichissements.
Des enrichissements peuvent être configurés à l’aide des méthodes suivantes :
| Méthode | Commande |
|---|---|
| Portail | Portail Azure Voir le tutoriel sur les enrichissements de messages |
| Azure CLI | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
L’ajout d’enrichissements de message n’ajoute pas de latence au routage des messages.
Pour essayer les enrichissements de messages, consultez le tutoriel sur les enrichissements de messages
Limites
Vous pouvez ajouter jusqu’à 10 enrichissements par hub IoT pour ces hubs dans le niveau de base ou standard. Pour les hubs IoT du 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 hub IoT est dans le niveau de base. Les IoT Hubs 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 de l’enrichissement est définie sur $twin.tags.location et que la propriété location sous les balises est un objet contenant des propriétés enfants telles que
{"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 des enrichissements, ne peut pas dépasser 256 Ko. Si la taille d’un message dépasse 256 Ko, le hub IoT supprimera 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 analyser la métrique 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 de jumeau 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.
Tarifs
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 fois pour ce message, même s’il est envoyé à plusieurs points de terminaison.
Étapes suivantes
Pour plus d’informations sur le routage des messages vers un hub IoT, consultez les articles suivants :