Connexion de données IoT Hub
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 des IoT Hubs gérés par le client, en utilisant son Event Hub compatible avec les messages de l'appareil vers le nuage.
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
- Les données sont lues à partir du point de terminaison Event Hub sous forme d’objets EventData.
- Examinez les formats pris en charge.
Remarque
IoT Hub ne prend pas en charge le format .raw.
- Examinez les compressions prises en charge.
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 | 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. |
Remarque
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-base 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 base de données de la propriété d’ingestion.
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 à plusieurs 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 :
Dans le portail Azure, accédez à votre cluster.
Sélectionnez Bases de données>Connexions de données.
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).
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 table de la propriété d’ingestion.
Remarque
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.
Remarque
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 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
Remarque
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.
Remarque
- Le nombre de
device-to-cloud partitionsn’é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 endpointspour ajouter un nouveau groupe de consommateurs. - La connexion de données utilise les
Built-in endpointd’IoT Hub. Si vous configurez un autreMessage routing endpoint, les messages cessent de circuler vers leBuilt-in endpointsauf 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 terminaisonevents. Pour plus d’informations, consultez Résoudre les problèmes de routage des messages IoT Hub.
Envoyer des événements
Consultez l’exemple de projet qui simule un appareil et génère des données.