Connexion de données IoT Hub

  • Article

Azure IoT Hub est un service managé, hébergé dans le cloud, qui fait office de hub de messages central pour la communication bidirectionnelle entre votre application IoT et les appareils qu’il gère. Azure Data Explorer offre une ingestion continue à partir d’IoT Hubs gérés par le client, à l’aide de son point de terminaison intégré compatible Event Hub pour les messages appareil-à-cloud.

Le pipeline d’ingestion IoT passe par plusieurs étapes. Tout d’abord, vous créez un hub IoT et y inscrivez un appareil. Vous créez ensuite une table cible dans Azure Data Explorer, dans laquelle les données d’un format particulier sont ingérées à l’aide des propriétés d’ingestion indiquées. La connexion Iot Hub doit connaître le routage des événements pour se connecter à la table Azure Data Explorer. Les données sont incorporées avec les propriétés sélectionnées en fonction du mappage des propriétés du système d’événements. Ce processus peut être géré par le biais du portail Azure, programmatiquement avec C# ou Python, ou avec le modèle Azure Resource Manager.

Pour obtenir des informations générales sur l’ingestion de données dans Azure Data Explorer, consultez Vue d’ensemble de l’ingestion des données dans Azure Data Explorer.

Format de données

Propriétés d’ingestion

Les propriétés d’ingestion déterminent le processus d’ingestion où router les données et comment le traiter. Vous pouvez spécifier les propriétés d’ingestion des événements avec EventData.Properties. Vous pouvez définir les propriétés suivantes :

Propriété Description
Base de données Nom (respectant la casse) de la base de données cible. Cette propriété peut être utilisée si vous voulez envoyer les données vers une base de données différente de celle sur laquelle la connexion de données a été créée (la base de données par défaut). Pour router les données vers plusieurs bases de données, vous devez d’abord configurer la connexion en tant que connexion à plusieurs bases de données. Pour plus d’informations, consultez Routage des événements.
Table de charge de travail Nom (sensible à la casse) de la table cible existante. Remplace le paramètre Table défini dans le volet Data Connection.
Format Format de données. Remplace le paramètre Data format défini dans le volet Data Connection.
IngestionMappingReference Nom du mappage d’ingestion existant à utiliser. Remplace le paramètre Column mapping défini dans le volet Data Connection.
Encodage Encodage des données, la valeur par défaut est UTF8. Il peut s’agir de l’un des encodages pris en charge par .NET.

Notes

Seuls les événements mis en file d’attente après que vous avez créé la connexion de données sont ingérés.

Routage d’événements

Quand vous créez une connexion de données à votre cluster, vous spécifiez le routage pour l’emplacement où les données ingérées doivent être envoyées. Le routage par défaut se fait vers la table cible spécifiée dans la chaîne de connexion associée à la base de données cible. Le routage par défaut de vos données est également appelé routage statique. Vous pouvez spécifier un autre routage pour vos données en utilisant les propriétés des données d’événement.

Router les données d’événement vers une autre base de données

Par défaut, le routage des données vers une autre base de données est désactivé. Pour envoyer les données vers une autre base de données, vous devez d’abord définir la connexion en tant que connexion à plusieurs bases de données. Pour obtenir un exemple de procédure dans le Portail Azure, consultez Activer le routage multi-bases de données. L’utilisateur, le groupe, le principal de service ou l’identité managée utilisé pour autoriser le routage de la base de données doit disposer au minimum du rôle Contributeur et d’autorisations d’écriture sur le cluster.

Pour spécifier une autre base de données, définissez la propriété d’ingestion de la base de données.

Avertissement

Spécifier une autre base de données sans définir la connexion en tant que connexion de données à plusieurs bases de données entraîne l’échec de l’ingestion.

Activer le routage multi-bases de données

Avant de pouvoir définir une autre base de données cible, vous devez d’abord autoriser le routage des données vers plusieurs bases de données. Pour autoriser le routage des données vers d’autres bases de données, effectuez les étapes suivantes :

  1. Dans le portail Azure, accédez à votre cluster.

  2. Sélectionnez Bases de données>Connexions de données.

  3. Créez ou modifiez une connexion de données puis dans le volet Connexion de données, sous Paramètres de routage des données, activez le routage des données vers une autre base de données (connexion de données de plusieurs bases de données).

    Capture d’écran de l’U I web Azure Data Explorer , montrant l’option des paramètres de routage des données définie pour autoriser.

Router les données d’événement vers une autre table

Vous pouvez également spécifier des propriétés de la table cible pour chaque événement, à l’aide des propriétés d’événement. La connexion route dynamiquement les données comme spécifié dans EventData.Properties, en remplaçant les propriétés statiques de cet événement. Pour spécifier une autre base de données, définissez la propriété d’ingestion de la table.

Notes

Si l’option Mes données contiennent des informations de routage est sélectionnée, vous devez fournir les informations de routage nécessaires dans le cadre des propriétés des événements.

Mappage des propriétés du système d’événements

Les propriétés système sont une collection utilisée pour stocker les propriétés définies par le service IoT Hub, au moment de la réception de l’événement. La connexion Iot Hub d’Azure Data Explorer incorpore les propriétés sélectionnées dans les données qui arrivent dans votre table.

Notes

Pour un mappage csv, des propriétés sont ajoutées au début de l’enregistrement dans l’ordre indiqué dans le tableau ci-dessous. Pour un mappage json, des propriétés sont ajoutées en fonction des noms de propriété dans le tableau suivant.

Propriétés système

IoT Hub expose les propriétés système suivantes pour les messages de IoT Hub appareil à cloud :

Propriété Description
message-id Identificateur correspondant au message défini par l’utilisateur utilisé pour les modèles demande-réponse. Format: Une chaîne qui respecte la casse (jusqu’à 128 caractères) de caractères alphanumériques 7 bits ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
iothub-enqueuedtime Date et heure de réception du message Appareil-à-cloud par IoT Hub.
user-id Un ID utilisé pour spécifier l’origine des messages. Lorsque les messages sont générés par IoT Hub, cette valeur est définie sur {iot hub name}.
iothub-connection-device-id Un ID défini par IoT Hub sur les messages appareil vers cloud. Elle contient la propriété deviceId de l’appareil qui a envoyé le message.
iothub-connection-module-id Un ID défini par IoT Hub sur les messages appareil vers cloud. Il contient la propriété moduleId de l’appareil qui a envoyé le message.
iothub-connection-auth-generation-id Un ID défini par IoT Hub sur les messages appareil vers cloud. Il contient la propriété connectionDeviceGenerationId (conformément aux Propriétés d’identité des appareils) de l’appareil qui a envoyé le message.
iothub-connection-auth-method Une méthode d’authentification définie par IoT Hub sur les messages appareil-à-cloud. Cette propriété contient des informations sur la méthode d’authentification utilisée pour authentifier l’appareil qui a envoyé le message.
iothub-app-iothub-creation-time-utc Permet à l’appareil d’envoyer l’heure de création de l’événement lors de l’envoi de données dans un lot.
iothub-creation-time-utc Permet à l’appareil d’envoyer l’heure de création de l’événement lors de l’envoi d’un message à la fois.
dt-dataschema Cette valeur est définie par IoT Hub sur les messages appareil-à-cloud. Elle contient l’ID du modèle d’appareil défini dans la connexion de l’appareil.
dt-subject Nom du composant qui envoie les messages appareil-à-cloud.

Si vous avez sélectionné Propriétés du système d’événements dans la section Source de données de la table, vous devez inclure les propriétés dans le schéma et le mappage de table.

Exemples de mappage de schéma

Exemple de mappage de schéma de table

Si vos données comprennent trois colonnes (Timespan, Metricet Value) et que les propriétés que vous incluez sont iothub-connection-device-id et sequence-number, créez ou modifiez le schéma de table à l’aide de la commande suivante :

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, IotHubDeviceId:long, IotHubSequenceNumber:long)

Exemple de mappage CSV

Exécutez les commandes suivantes pour ajouter des données au début de l’enregistrement. Notez les valeurs ordinales.

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "IotHubDeviceId", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "IotHubSequenceNumber", "Properties":{"Ordinal":"1"}}'
    ']'

Exemple de mappage JSON

Les données sont ajoutées à l’aide du mappage des propriétés système. Exécutez les commandes suivantes :

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.metric_value"}},'
    '    { "column" : "IotHubDeviceId", "Properties":{"Path":"$.iothub-connection-device-id"}},'
    '    { "column" : "IotHubSequenceNumber", "Properties":{"Path":"$.sequence-number"}}'
    ']'

Mappage des propriétés de l’utilisateur d’événement

Il n’existe aucune prise en charge pour enrichir la charge utile des événements IoT Hub avec les propriétés utilisateur. Envisagez d’incorporer des propriétés utilisateur dans le corps de l’événement en amont.

Connexion au hub IoT

Notes

Pour des performances optimales, créez toutes les ressources dans la même région que le cluster Azure Data Explorer.

Création d’un IoT Hub

Créez un hub IoT si vous n’en avez pas déjà un. La connexion à IoT Hub peut être gérée par le biais du portail Azure, programmatiquement avec C# ou Python, ou avec le modèle Azure Resource Manager.

Notes

  • Le nombre de device-to-cloud partitions n’étant pas modifiable, définissez-le dans une perspective à long terme.
  • Le groupe de consommateurs doit être unique par consommateur. Créez un groupe de consommateurs dédié à la connexion Azure Data Explorer. Recherchez votre ressource dans le portail Azure et accédez à Built-in endpoints pour ajouter un nouveau groupe de consommateurs.
  • La connexion de données utilise les Built-in endpoint d’IoT Hub. Si vous configurez un autre Message routing endpoint, les messages cessent de circuler vers le Built-in endpoint sauf si une route est créée vers ce point de terminaison. Pour garantir la circulation des messages vers le point de terminaison intégré malgré l’ajout d’une nouvelle route, configurez une route vers le point de terminaison events. Pour plus d’informations, consultez Résoudre les problèmes de routage des messages IoT Hub.

Envoi des événements

Consultez l’exemple de projet qui simule un appareil et génère des données.

Étape suivante

Créer une connexion de données IoT Hub