Erstellen einer IoT Hub-Datenverbindung für Azure Data Explorer

Artikel
05/03/2023

In diesem Artikel wird erläutert, wie Sie in Azure Data Explorer Daten aus IoT Hub (Big Data-Streamingplattform und IoT-Erfassungsdienst) erfassen.

Allgemeine Informationen zur Erfassung in Azure Data Explorer aus IoT Hub finden Sie unter Herstellen einer Verbindung mit IoT Hub.

Hinweis

Nur Ereignisse, die nach dem Erstellen der Datenverbindung in die Warteschlange eingereiht werden, werden erfasst.

Voraussetzungen

Ein Azure-Abonnement. Erstellen Sie ein kostenloses Azure-Konto.
Schnellstart: Erstellen eines Azure Data Explorer-Clusters und einer Datenbank. Erstellen eines Clusters und einer Datenbank
Eine Zieltabelle: Erstellen Sie eine Tabelle, oder verwenden Sie eine vorhandene.
Eine Erfassungszuordnung für die Tabelle.
Ein IoT Hub mit Daten für die Erfassung.

Erstellen einer IoT Hub-Datenverbindung

In diesem Abschnitt richten Sie eine Verbindung zwischen dem IoT Hub und Ihrer Azure Data Explorer-Tabelle ein. Solange diese Verbindung vorhanden ist, werden Daten vom IoT Hub in Ihre Zieltabelle übertragen.

Wählen Sie im linken Menü Ihres Azure Data Explorer-Clusters Datenbanken aus, und wählen Sie dann die Datenbank aus, die Ihre Zieltabelle enthält.
Wählen Sie Datenverbindungen und dann Datenverbindung hinzufügen aus. Wählen Sie im Dropdownmenü "IoT Hub" aus.

Füllen Sie das Formular mit den folgenden Informationen aus.

Einstellung	Feldbeschreibung
Name der Datenverbindung	Der Name der Verbindung, die Sie in Azure Data Explorer erstellen möchten.
Abonnement	Die Abonnement-ID, unter der sich die Event Hubs-Ressource befindet
IoT Hub	IoT Hub-Name
SAS-Richtlinie	Der Name der SAS-Richtlinie. Leseberechtigungen erforderlich
Consumergruppe	Die Consumergruppe, die im integrierten IoT Hub-Endpunkt definiert ist.
Ereignissystemeigenschaften	Die IoT Hub-Ereignissystemeigenschaften. Beim Hinzufügen von Systemeigenschaften erstellen oder aktualisieren Sie das Tabellenschema und die Zuordnung, um die ausgewählten Eigenschaften einzubeziehen.

Screenshot der Azure Data Explorer-Web-Benutzeroberfläche mit dem Datenverbindungsformular.

Hinweis

Ereignissystemeigenschaften werden für Einzeldatensatzereignisse unterstützt.
Für die CSV-Zuordnung werden Eigenschaften am Anfang des Datensatzes hinzugefügt. Für die JSON-Zuordnung werden Eigenschaften entsprechend dem Namen hinzugefügt, der in der Dropdownliste angezeigt wird.

Je nach Anwendungsfall sollten Sie das Routing mit mehreren Datenbanken aktivieren. Weitere Informationen zum Datenbankrouting finden Sie unter Ereignisrouting.

Füllen Sie die folgenden Routingeinstellungen aus:

Einstellung	Empfohlener Wert	Feldbeschreibung
Tabellenname	TestTable	Die Tabelle, die Sie in testdb erstellt haben.
Datenformat	JSON	Unterstützte Formate sind AVRO, CSV, JSON, ORC, PARTS, PSV, SCSV, SOHSV, TSV, TXT, TSVE, APACHE AVRO und W3CLOG.
Zuordnung	TestMapping	Die Zuordnung, die Sie in testdb erstellt haben, um eingehende Daten den Spaltennamen und Datentypen von testdb zuzuordnen. Wenn nicht angegeben, wird eine identitätsdatenzuordnung, die aus dem Schema der Tabelle abgeleitet ist, verwendet.

Screenshot der Azure Data Explorer Web UI mit den Standardroutingeinstellungen im Formular

Hinweis

JSON-Daten werden standardmäßig als Multijson analysiert. Wählen Sie "Formatfehler ignorieren" aus, um die Daten im strengen JSON-Format aufzunehmen.
Wenn Sie ereignissystemeigenschaften ausgewählt haben, müssen Sie Systemeigenschaften in das Tabellenschema und die Zuordnung einschließen.

Klicken Sie auf Erstellen.

Warnung

Erstellen Sie bei einem manuellen Failover die Datenverbindung neu.

Installieren Sie das NuGet-Paket Microsoft.Azure.Management.Kusto.
Erstellen Sie einen Azure AD-Anwendungsprinzipal , der für die Authentifizierung verwendet werden soll. Sie benötigen die Verzeichnis-ID (Mandanten-ID), die Anwendungs-ID und den geheimen Clientschlüssel.

Führen Sie den folgenden Code aus.

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);

Einstellung	Empfohlener Wert	Feldbeschreibung
tenantId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Ihre Mandanten-ID. Wird auch als Verzeichnis-ID bezeichnet.
subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Die Abonnement-ID, die Sie für die Ressourcenerstellung verwenden.
clientId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Die Client-ID der Anwendung, die auf Ressourcen in Ihrem Mandanten zugreifen kann.
clientSecret	PlaceholderClientSecret	Das Clientgeheimnis der Anwendung, die auf Ressourcen in Ihrem Mandanten zugreifen kann.
resourceGroupName	testrg	Der Name der Ressourcengruppe, die Ihren Cluster enthält.
clusterName	mykustocluster	Der Name Ihres Clusters.
databaseName	mykustodatabase	Der Name der Zieldatenbank in Ihrem Cluster.
iotHubConnectionName	myiothubconnect	Der gewünschte Name Ihrer Datenverbindung.
tableName	StormEvents	Der Name der Zieltabelle in der Zieldatenbank.
mappingRuleName	StormEvents_CSV_Mapping	Der Name der Spaltenzuordnung, die mit der Zieltabelle verknüpft ist.
dataFormat	csv	Das Datenformat der Nachricht.
iotHubResourceId	Ressourcen-ID	Die Ressourcen-ID Ihres IoT-Hubs mit den Daten für die Erfassung.
sharedAccessPolicyName	iothubforread	Der Name der SAS-Richtlinie, die Berechtigungen für Geräte und Dienste zum Herstellen einer Verbindung mit IoT Hub definiert.
consumerGroup	$Default	Die Consumergruppe Ihres Event Hubs.
location	USA, Mitte	Der Speicherort der Datenverbindungsressource.
databaseRouting	Multi oder Single	Das Datenbankrouting für die Verbindung. Wenn Sie den Wert auf Single festlegen, wird die Datenverbindung wie in der Einstellung databaseName angegeben an eine einzelne Datenbank im Cluster geroutet. Wenn Sie den Wert auf Multi festlegen, können Sie die Standardzieldatenbank mithilfe der Erfassungseigenschaft Database überschreiben. Weitere Informationen finden Sie unter Ereignisrouting.

Installieren Sie die erforderlichen Bibliotheken.

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

Erstellen Sie einen Azure AD-Anwendungsprinzipal , der für die Authentifizierung verwendet werden soll. Sie benötigen die Verzeichnis-ID (Mandanten-ID), die Anwendungs-ID und den geheimen Clientschlüssel.

Führen Sie den folgenden Code aus.

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))

Einstellung	Empfohlener Wert	Feldbeschreibung
tenant_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Ihre Mandanten-ID. Wird auch als Verzeichnis-ID bezeichnet.
subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Die Abonnement-ID, die Sie für die Ressourcenerstellung verwenden.
client_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Die Client-ID der Anwendung, die auf Ressourcen in Ihrem Mandanten zugreifen kann.
client_secret	xxxxxxxxxxxxxx	Das Clientgeheimnis der Anwendung, die auf Ressourcen in Ihrem Mandanten zugreifen kann.
resource_group_name	testrg	Der Name der Ressourcengruppe, die Ihren Cluster enthält.
cluster_name	mykustocluster	Der Name Ihres Clusters.
database_name	mykustodatabase	Der Name der Zieldatenbank in Ihrem Cluster.
data_connection_name	myeventhubconnect	Der gewünschte Name Ihrer Datenverbindung.
table_name	StormEvents	Der Name der Zieltabelle in der Zieldatenbank.
mapping_rule_name	StormEvents_CSV_Mapping	Der Name der Spaltenzuordnung, die mit der Zieltabelle verknüpft ist.
data_format	csv	Das Datenformat der Nachricht.
iot_hub_resource_id	Ressourcen-ID	Die Ressourcen-ID Ihres IoT-Hubs mit den Daten für die Erfassung.
shared_access_policy_name	iothubforread	Der Name der SAS-Richtlinie, die Berechtigungen für Geräte und Dienste zum Herstellen einer Verbindung mit IoT Hub definiert.
consumer_group	$Default	Die Consumergruppe Ihres Event Hubs.
location	USA, Mitte	Der Speicherort der Datenverbindungsressource.
database_routing	Multi oder Single	Das Datenbankrouting für die Verbindung. Wenn Sie den Wert auf Single festlegen, wird die Datenverbindung wie in der Einstellung databaseName angegeben an eine einzelne Datenbank im Cluster geroutet. Wenn Sie den Wert auf Multi festlegen, können Sie die Standardzieldatenbank mithilfe der Erfassungseigenschaft Database überschreiben. Weitere Informationen finden Sie unter Ereignisrouting.

Das folgende Beispiel zeigt eine Azure Resource Manager-Vorlage für das Hinzufügen einer IoT Hub-Datenverbindung. Sie können die Vorlage im Azure-Portal mithilfe des Formulars bearbeiten und bereitstellen.

{
    "$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')]"
            }
        }
    ]
}

Entfernen einer IoT Hub-Datenverbindung

Gehen Sie wie folgt vor, um die IoT Hub-Verbindung aus dem Azure-Portal zu entfernen:

Zum Custer wechseln Wählen Sie im linken Menü Einstellungen aus. Wählen Sie dann die Datenbank aus, die die Zieltabelle enthält.
Wählen Sie im linken Menü Datenverbindungen aus. Aktivieren Sie dann das Kontrollkästchen neben der relevanten IoT Hub-Datenverbindung.
Wählen Sie in der oberen Menüleiste Löschen aus.

Führen Sie den folgenden Befehl aus, um die IoT Hub-Verbindung zu entfernen:

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

Führen Sie den folgenden Befehl aus, um die IoT Hub-Verbindung zu entfernen:

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)

Nächste Schritte

Abfragen von Daten in Azure Data Explorer

Freigeben über

Erstellen einer IoT Hub-Datenverbindung für Azure Data Explorer

Voraussetzungen

Erstellen einer IoT Hub-Datenverbindung

Entfernen einer IoT Hub-Datenverbindung

Nächste Schritte

Zusätzliche Ressourcen