Créer une connexion de données IoT Hub pour Azure Data Explorer

Cet article vous montre comment ingérer des données dans Azure Data Explorer depuis IoT Hub, plateforme de streaming de big data et service d’ingestion IoT.

Pour obtenir des informations générales sur l’ingestion dans Azure Data Explorer à partir d’IoT Hub, consultez Connexion à IoT Hub.

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.

Prérequis

• Un abonnement Azure. Créez un compte Azure gratuit.
• Un cluster et une base de données Azure Data Explorer. Créez un cluster et une base de données.
• Une table de destination. Créez une table ou utilisez une table existante.
• Un mappage d’ingestion pour la table.
• Un hub IoT avec des données pour l’ingestion.

Créer une connexion de données IoT Hub

Dans cette section, vous allez établir une connexion entre IoT Hub et votre table Azure Data Explorer. Tant que cette connexion est en place, les données sont transmises depuis le hub IoT dans votre table cible.

Portail

1. Dans le menu de gauche de votre cluster Azure Data Explorer, sélectionnez Bases de données , puis sélectionnez la base de données qui contient votre table cible.

   

2. Sélectionnez Connexion de données, puis Ajouter une connexion de données. Dans la liste déroulante, sélectionnez IoT Hub.

   

3. Renseignez le formulaire avec les informations suivantes.

   Paramètre	Description du champ
   Nom de la connexion de données	Nom de la connexion que vous souhaitez créer dans Azure Data Explorer
   Abonnement	ID d’abonnement dans lequel se trouve la ressource Event Hubs.
   IoT Hub	Nom de l’IoT Hub
   Stratégie d’accès partagé	Nom de la stratégie d’accès partagé. Doit avoir des autorisations de lecture
   Groupe de consommateurs	Groupe de consommateurs défini dans le point de terminaison intégré au hub IoT
   Propriétés du système d’événements	Propriétés système d’événement du hub IoT. Lors de l’ajout des propriétés système, créez ou mettez à jour le schéma de table et le mappage pour inclure les propriétés sélectionnées.

   

   Remarque

   • Les propriétés du système d’événements sont prises en charge pour les événements à enregistrement unique.
   • Pour le mappage CSV, les propriétés sont ajoutées au début de l’enregistrement. Pour le mappage JSON, les propriétés sont ajoutées en fonction du nom qui apparaît dans la liste déroulante.

4. Selon votre cas d’usage, vous pouvez activer le routage multi-base de données. Pour plus d’informations sur le routage de base de données, consultez Routage des événements.

   

5. Renseignez les paramètres de routage suivants :

   Paramètre	Valeur suggérée	Description du champ
   Nom de la table	TestTable	Table que vous avez créée dans testdb.
   Format de données	JSON	Les formats pris en charge sont AVRO, CSV, JSON, ORC, PARQUET, PSV, SCSV, SOHSV, TSV, TXT, TSVE, APACHE AVRO et W3CLOG.
   Mappage	TestMapping	Mappage que vous avez créé dans testdb, qui mappe les données entrantes aux noms de colonnes et aux types de données de testdb. Si ce n’est pas spécifié, un mappage de données d’identité dérivé du schéma de la table est utilisé.

   

   Remarque

   • Par défaut, les données JSON sont analysées en tant que multijson. Sélectionnez Ignorer les erreurs de format pour ingérer les données au format JSON strict.
   • Si vous avez sélectionné les propriétés du système d’événements, vous devez inclure les propriétés système dans le schéma de table et le mappage.

6. Sélectionnez Créer.

Avertissement

En cas de basculement manuel, recréez la connexion de données.

C#

1. Installez le package NuGet Microsoft.Azure.Management.Kusto.

2. Créez un principal d’application Azure AD à utiliser pour l’authentification. Vous aurez besoin de l’ID (de locataire) d’annuaire, de l’ID d’application et de la clé secrète client.

3. Exécutez le code suivant.

   var tenantId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"; //Directory (tenant) ID
   var clientId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"; //Application ID
   var clientSecret = "PlaceholderClientSecret"; //Client Secret
   var subscriptionId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx";
   var authClient = ConfidentialClientApplicationBuilder.Create(clientId)
       .WithAuthority($"https://login.microsoftonline.com/{tenantId}")
       .WithClientSecret(clientSecret)
       .Build();
   var result = authClient.AcquireTokenForClient(new[] { "https://management.core.windows.net/" }).ExecuteAsync().Result;
   var credentials = new TokenCredentials(result.AccessToken, result.TokenType);
   var kustoManagementClient = new KustoManagementClient(credentials) { SubscriptionId = subscriptionId };
   var resourceGroupName = "testrg";
   //The cluster and database that are created as part of the Prerequisites
   var clusterName = "mykustocluster";
   var databaseName = "mykustodatabase";
   var iotHubConnectionName = "myiothubconnect";
   //The IoT hub that is created as part of the Prerequisites
   var iotHubResourceId = "/subscriptions/<iotHubSubscriptionId>/resourceGroups/<iotHubResourceGroupName>/providers/Microsoft.Devices/IotHubs/<iotHubName>";
   var sharedAccessPolicyName = "iothubforread";
   var consumerGroup = "$Default";
   var location = "Central US";
   //The table and column mapping are created as part of the Prerequisites
   var tableName = "StormEvents";
   var mappingRuleName = "StormEvents_CSV_Mapping";
   var dataFormat = DataFormat.CSV;
   var databaseRouting = "Multi";
   var iotHubConnectionData = new IotHubDataConnection(
       iotHubResourceId, consumerGroup, sharedAccessPolicyName,
       tableName: tableName, location: location, mappingRuleName: mappingRuleName,
       dataFormat: dataFormat, databaseRouting: databaseRouting
   );
   await kustoManagementClient.DataConnections.CreateOrUpdateAsync(resourceGroupName, clusterName, databaseName, iotHubConnectionName, iotHubConnectionData);
   

   Paramètre	Valeur suggérée	Description du champ
   tenantId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Votre ID de client. Également appelé ID de répertoire.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	ID d’abonnement que vous utilisez pour la création de ressources.
   clientId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	ID client de l’application qui peut accéder aux ressources figurant dans votre locataire.
   clientSecret	PlaceholderClientSecret	Secret client de l’application qui peut accéder aux ressources figurant dans votre locataire.
   resourceGroupName	testrg	Nom du groupe de ressources qui contient votre cluster.
   clusterName	mykustocluster	Nom de votre cluster.
   databaseName	mykustodatabase	Nom de la base de données cible dans votre cluster.
   iotHubConnectionName	myiothubconnect	Nom souhaité de votre connexion de données.
   tableName	StormEvents	Nom de la table cible dans la base de données cible.
   mappingRuleName	StormEvents_CSV_Mapping	Nom de votre mappage de colonnes associé à la table cible.
   dataFormat	csv	Format de données du message.
   iotHubResourceId	ID de ressource	ID de ressource de votre hub IoT qui contient les données à des fins d’ingestion.
   sharedAccessPolicyName	iothubforread	Nom de la stratégie d’accès partagé qui définit les autorisations pour que les périphériques et les services se connectent au hub IoT.
   consumerGroup	$Default	Groupe de consommateurs de votre hub d’événements.
   location	USA Centre	Emplacement de la ressource de connexion de données.
   databaseRouting	Multi ou Single	Routage de la base de données pour la connexion. Si vous définissez la valeur sur Un seul, la connexion de données est routée vers une base de données unique dans le cluster, comme spécifié dans le paramètre databaseName. Si vous définissez la valeur sur Multi, vous pouvez remplacer la base de données cible par défaut en utilisant la propriété ingestion de la base de données. Pour plus d’informations, consultez Routage des événements.

Python

1. Installez les bibliothèques nécessaires.

   pip install azure-common
   pip install azure-mgmt-kusto
   

2. Créez un principal d’application Azure AD à utiliser pour l’authentification. Vous aurez besoin de l’ID (de locataire) d’annuaire, de l’ID d’application et de la clé secrète client.

3. Exécutez le code suivant.

   from azure.mgmt.kusto import KustoManagementClient
   from azure.mgmt.kusto.models import IotHubDataConnection
   from azure.common.credentials import ServicePrincipalCredentials
   
   #Directory (tenant) ID
   tenant_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   #Application ID
   client_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   #Client Secret
   client_secret = "xxxxxxxxxxxxxx"
   subscription_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   credentials = ServicePrincipalCredentials(
           client_id=client_id,
           secret=client_secret,
           tenant=tenant_id
       )
   kusto_management_client = KustoManagementClient(credentials, subscription_id)
   
   resource_group_name = "testrg"
   #The cluster and database that are created as part of the Prerequisites
   cluster_name = "mykustocluster"
   database_name = "mykustodatabase"
   data_connection_name = "myeventhubconnect"
   #The IoT hub that is created as part of the Prerequisites
   iot_hub_resource_id = "/subscriptions/xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx/resourceGroups/xxxxxx/providers/Microsoft.Devices/IotHubs/xxxxxx";
   shared_access_policy_name = "iothubforread"
   consumer_group = "$Default"
   location = "Central US"
   #The table and column mapping that are created as part of the Prerequisites
   table_name = "StormEvents"
   mapping_rule_name = "StormEvents_CSV_Mapping"
   data_format = "csv"
   database_routing = "Multi"
   
   #Returns an instance of LROPoller, check https://learn.microsoft.com/python/api/msrest/msrest.polling.lropoller?view=azure-python
   poller = kusto_management_client.data_connections.create_or_update(resource_group_name=resource_group_name, cluster_name=cluster_name, database_name=database_name, data_connection_name=data_connection_name,
                                               parameters=IotHubDataConnection(iot_hub_resource_id=iot_hub_resource_id, shared_access_policy_name=shared_access_policy_name,
                                                                                   consumer_group=consumer_group, table_name=table_name, location=location, mapping_rule_name=mapping_rule_name, data_format=data_format, database_routing=database_routing))
   

   Paramètre	Valeur suggérée	Description du champ
   tenant_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Votre ID de client. Également appelé ID de répertoire.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	ID d’abonnement que vous utilisez pour la création de ressources.
   client_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	ID client de l’application qui peut accéder aux ressources figurant dans votre locataire.
   client_secret	xxxxxxxxxxxxxx	Secret client de l’application qui peut accéder aux ressources figurant dans votre locataire.
   resource_group_name	testrg	Nom du groupe de ressources qui contient votre cluster.
   nom_cluster	mykustocluster	Nom de votre cluster.
   database_name	mykustodatabase	Nom de la base de données cible dans votre cluster.
   data_connection_name	myeventhubconnect	Nom souhaité de votre connexion de données.
   table_name	StormEvents	Nom de la table cible dans la base de données cible.
   mapping_rule_name	StormEvents_CSV_Mapping	Nom de votre mappage de colonnes associé à la table cible.
   data_format	csv	Format de données du message.
   iot_hub_resource_id	ID de ressource	ID de ressource de votre hub IoT qui contient les données à des fins d’ingestion.
   shared_access_policy_name	iothubforread	Nom de la stratégie d’accès partagé qui définit les autorisations pour que les périphériques et les services se connectent au hub IoT.
   consumer_group	$Default	Groupe de consommateurs de votre hub d’événements.
   location	USA Centre	Emplacement de la ressource de connexion de données.
   database_routing	Multi ou Single	Routage de la base de données pour la connexion. Si vous définissez la valeur sur Un seul, la connexion de données est routée vers une base de données unique dans le cluster, comme spécifié dans le paramètre databaseName. Si vous définissez la valeur sur Multi, vous pouvez remplacer la base de données cible par défaut en utilisant la propriété ingestion de la base de données. Pour plus d’informations, consultez Routage des événements.

Modèle ARM

L’exemple suivant montre un modèle Azure Resource Manager pour l’ajout d’une connexion de données IoT Hub. Vous pouvez modifier et déployer le modèle dans le portail Azure en utilisant le formulaire.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "IotHubs_iothubdemo_name": {
            "type": "string",
            "defaultValue": "iothubdemo",
            "metadata": {
                "description": "Specifies the IoT Hub name."
            }
        },
        "iothubpolices_iothubowner_name": {
            "type": "string",
            "defaultValue": "iothubowner",
            "metadata": {
                "description": "Specifies the shared access policy name."
            }
        },
        "consumergroup_default_name": {
            "type": "string",
            "defaultValue": "$Default",
            "metadata": {
                "description": "Specifies the consumer group of the IoT Hub."
            }
        },
        "Clusters_kustocluster_name": {
            "type": "string",
            "defaultValue": "kustocluster",
            "metadata": {
                "description": "Specifies the name of the cluster"
            }
        },
        "databases_kustodb_name": {
            "type": "string",
            "defaultValue": "kustodb",
            "metadata": {
                "description": "Specifies the name of the database"
            }
        },
        "tables_kustotable_name": {
            "type": "string",
            "defaultValue": "kustotable",
            "metadata": {
                "description": "Specifies the name of the table"
            }
        },
        "mapping_kustomapping_name": {
            "type": "string",
            "defaultValue": "kustomapping",
            "metadata": {
                "description": "Specifies the name of the mapping rule"
            }
        },
        "dataformat_type": {
            "type": "string",
            "defaultValue": "csv",
            "metadata": {
                "description": "Specifies the data format"
            }
        },
           "databaseRouting_type": {
            "type": "string",
            "defaultValue": "Single",
            "metadata": {
                "description": "The database routing for the connection. If you set the value to **Single**, the data connection will be routed to a single database in the cluster as specified in the *databaseName* setting. If you set the value to **Multi**, you can override the default target database using the *Database* EventData property."
            }
        },
        "dataconnections_kustodc_name": {
            "type": "string",
            "defaultValue": "kustodc",
            "metadata": {
                "description": "Name of the data connection to create"
            }
        },
        "subscriptionId": {
            "type": "string",
            "defaultValue": "[subscription().subscriptionId]",
            "metadata": {
                "description": "Specifies the subscriptionId of the IoT Hub"
            }
        },
        "resourceGroup": {
            "type": "string",
            "defaultValue": "[resourceGroup().name]",
            "metadata": {
                "description": "Specifies the resourceGroup of the IoT Hub"
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
                "description": "Location for all resources."
            }
        }
    },
    "variables": {
    },
    "resources": [{
            "type": "Microsoft.Kusto/Clusters/Databases/DataConnections",
            "apiVersion": "2019-09-07",
            "name": "[concat(parameters('Clusters_kustocluster_name'), '/', parameters('databases_kustodb_name'), '/', parameters('dataconnections_kustodc_name'))]",
            "location": "[parameters('location')]",
            "kind": "IotHub",
            "properties": {
                "iotHubResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.Devices/IotHubs', parameters('IotHubs_iothubdemo_name'))]",
                "consumerGroup": "[parameters('consumergroup_default_name')]",
                "sharedAccessPolicyName": "[parameters('iothubpolices_iothubowner_name')]",
                "tableName": "[parameters('tables_kustotable_name')]",
                "mappingRuleName": "[parameters('mapping_kustomapping_name')]",
                "dataFormat": "[parameters('dataformat_type')]",
                 "databaseRouting": "[parameters('databaseRouting_type')]"
            }
        }
    ]
}

Supprimer une connexion de données IoT Hub

Portail

Pour supprimer la connexion IoT Hub de l’Portail Azure, procédez comme suit :

1. Accédez à votre cluster. Dans le menu de gauche, sélectionnez Bases de données. Sélectionnez ensuite la base de données qui contient la table cible.
2. Dans le menu de gauche, sélectionnez Connexions de données. Ensuite, cochez la case en regard de la connexion de données IoT Hub appropriée.
3. Dans la barre de menus supérieure, sélectionnez Supprimer.

C#

Pour supprimer la connexion IoT Hub, exécutez la commande suivante :

kustoManagementClient.DataConnections.Delete(resourceGroupName, clusterName, databaseName, dataConnectionName);

Python

Pour supprimer la connexion IoT Hub, exécutez la commande suivante :

kusto_management_client.data_connections.delete(resource_group_name=resource_group_name, cluster_name=kusto_cluster_name, database_name=kusto_database_name, data_connection_name=kusto_data_connection_name)

Étapes suivantes

• Interroger des données dans Azure Data Explorer