Creación de una conexión de datos de IoT Hub para Azure Data Explorer

En este artículo se muestra cómo ingerir datos en Azure Data Explorer desde IoT Hub, una plataforma de streaming de macrodatos y un servicio de ingesta de IoT.

Para información general sobre la ingesta en Azure Data Explorer desde IoT Hub, consulte Conexión a IoT Hub.

Nota:

Solamente se ingieren los eventos en cola después de crear la conexión de datos.

Requisitos previos

• Suscripción a Azure. Cree una cuenta de Azure gratuita.
• Un clúster y la base de datos de Azure Data Explorer. Cree un clúster y una base de datos.
• Una tabla de destino. Cree una tabla o use una tabla existente.
• Una asignación de ingesta para la tabla.
• Un IoT Hub con datos para la ingesta.

Crear una conexión de datos de IoT Hub

En esta sección, establecerá una conexión entre IoT Hub y la tabla de Azure Data Explorer. Siempre que esta conexión esté en vigor, los datos se transmiten desde IoT Hub a la tabla de destino.

Portal

1. En el menú izquierdo del clúster de Azure Data Explorer, seleccione Bases de datos y, a continuación, seleccione la base de datos que contiene la tabla de destino.

   

2. Seleccione Conexiones de datos y Agregar la conexión de datos. En la lista desplegable, seleccione IoT Hub.

   

3. Rellene el formulario con la siguiente información.

   Configuración	Descripción del campo
   Nombre de la conexión de datos	Nombre de la conexión que desea crear en Azure Data Explorer.
   Subscription	Identificador de la suscripción donde se encuentra el recurso de Event Hubs.
   IoT Hub	Nombre de IoT Hub
   Directiva de acceso compartido	Nombre de la directiva de acceso compartido. Debe tener permisos de lectura.
   Grupo de consumidores	Grupo de consumidores definido en el punto de conexión integrado de IoT Hub
   Propiedades del sistema de eventos	Propiedades del sistema de eventos de IoT Hub Cuando agregue las propiedades del sistema, cree o actualice el esquema de tabla y la asignación para incluir las propiedades seleccionadas.

   

   Nota:

   • Las propiedades del sistema de eventos se admiten para eventos de registro único.
   • Para la asignación de CSV, las propiedades se agregan al principio del registro. Para la asignación de JSON, las propiedades se agregan según el nombre que aparece en la lista desplegable.

4. En función de su caso de uso, es posible que desee activar el enrutamiento de varias bases de datos. Para más información acerca del enrutamiento de bases de datos, consulte Enrutamiento de eventos.

   

5. Rellene la siguiente configuración de enrutamiento:

   Configuración	Valor sugerido	Descripción del campo
   Nombre de la tabla	TestTable	La tabla que creó en testdb.
   Formato de datos	JSON	Los formatos admitidos son AVRO, CSV, JSON, ORC, PARQUET, PSV, SCSV, SOHSV, TSV, TXT, TSVE, APACHE AVRO y W3CLOG.
   Asignación	TestMapping	Asignación que creó en testdb, que asigna los datos entrantes a los nombres de columnas y tipos de datos de testdb. Si no se especifica, se usa una asignación de datos de identidad derivada del esquema de la tabla.

   

   Nota:

   • Los datos JSON se analizan como multijson de forma predeterminada. Seleccione Omitir errores de formato para ingerir los datos en formato JSON estricto.
   • Si seleccionó Propiedades del sistema de eventos, debe incluir propiedades del sistema en el esquema de tabla y la asignación.

6. Seleccione Crear.

Advertencia

En el caso de una conmutación por error manual, vuelva a crear la conexión de datos.

C#

1. Instale el paquete Microsoft.Azure.Management.Kusto NuGet.

2. Cree una entidad de seguridad de aplicación de Azure AD que se usará para la autenticación. Necesitará el identificador de directorio (inquilino), el identificador de aplicación y el secreto de cliente.

3. Ejecute el código siguiente:

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

   Configuración	Valor sugerido	Descripción del campo
   tenantId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	El identificador de inquilino. También conocido como identificador de directorio.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Identificador de suscripción que se usa para la creación de recursos.
   clientId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Identificador del cliente de la aplicación que puede acceder a los recursos del inquilino.
   clientSecret	PlaceholderClientSecret	Secreto del cliente de la aplicación que puede acceder a los recursos del inquilino.
   resourceGroupName	testrg	Nombre del grupo de recursos que contiene el clúster.
   clusterName	mykustocluster	Nombre del clúster.
   databaseName	mykustodatabase	Nombre de la base de datos de destino del clúster.
   iotHubConnectionName	myiothubconnect	Nombre que desea asignar a la conexión de datos.
   tableName	StormEvents	Nombre de la tabla de destino de la base de datos de destino.
   mappingRuleName	StormEvents_CSV_Mapping	Nombre de la asignación de columnas asociada a la tabla de destino.
   dataFormat	csv	Formato de datos del mensaje.
   iotHubResourceId	Identificador del recurso	Identificador del recurso del centro de IoT que contiene los datos que se van a ingerir.
   sharedAccessPolicyName	iothubforread	Nombre de la directiva de acceso compartido que define los permisos para que los dispositivos y los servicios se conecten a IoT Hub.
   consumerGroup	$Default	Grupo de consumidores del centro de eventos.
   ubicación	Centro de EE. UU.	Ubicación del recurso de conexión de datos.
   databaseRouting	Múltiple o Sencillo	Enrutamiento de la base de datos para la conexión. Si establece el valor en Sencillo, la conexión de datos se enruta a una base de datos única del clúster, tal y como se especifica en la opción databaseName. Si establece el valor en Múltiple, puede invalidar la base de datos de destino predeterminada mediante la propiedad de ingesta Base de datos. Para más información, consulte Enrutamiento de eventos.

Python

1. Instale las bibliotecas necesarias.

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

2. Cree una entidad de seguridad de aplicación de Azure AD que se usará para la autenticación. Necesitará el identificador de directorio (inquilino), el identificador de aplicación y el secreto de cliente.

3. Ejecute el código siguiente:

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

   Configuración	Valor sugerido	Descripción del campo
   tenant_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	El identificador de inquilino. También conocido como identificador de directorio.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Identificador de suscripción que se usa para la creación de recursos.
   client_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	Identificador del cliente de la aplicación que puede acceder a los recursos del inquilino.
   client_secret	xxxxxxxxxxxxxx	Secreto del cliente de la aplicación que puede acceder a los recursos del inquilino.
   resource_group_name	testrg	Nombre del grupo de recursos que contiene el clúster.
   cluster_name	mykustocluster	Nombre del clúster.
   database_name	mykustodatabase	Nombre de la base de datos de destino del clúster.
   data_connection_name	myeventhubconnect	Nombre que desea asignar a la conexión de datos.
   table_name	StormEvents	Nombre de la tabla de destino de la base de datos de destino.
   mapping_rule_name	StormEvents_CSV_Mapping	Nombre de la asignación de columnas asociada a la tabla de destino.
   data_format	csv	Formato de datos del mensaje.
   iot_hub_resource_id	Identificador del recurso	Identificador del recurso del centro de IoT que contiene los datos que se van a ingerir.
   shared_access_policy_name	iothubforread	Nombre de la directiva de acceso compartido que define los permisos para que los dispositivos y los servicios se conecten a IoT Hub.
   consumer_group	$Default	Grupo de consumidores del centro de eventos.
   ubicación	Centro de EE. UU.	Ubicación del recurso de conexión de datos.
   database_routing	Múltiple o Sencillo	Enrutamiento de la base de datos para la conexión. Si establece el valor en Sencillo, la conexión de datos se enruta a una base de datos única del clúster, tal y como se especifica en la opción databaseName. Si establece el valor en Múltiple, puede invalidar la base de datos de destino predeterminada mediante la propiedad de ingesta Base de datos. Para más información, consulte Enrutamiento de eventos.

Plantilla ARM

En el ejemplo siguiente se muestra una plantilla de Azure Resource Manager para agregar una conexión de datos de IoT Hub. Puede editar e implementar la plantilla en Azure Portal mediante el formulario.

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

Eliminar una conexión de datos de IoT Hub

Portal

Para quitar la conexión de IoT Hub de Azure Portal, haga lo siguiente:

1. Vaya al clúster. En el menú de la izquierda, seleccione Bases de datos. A continuación, seleccione la base de datos que contiene la tabla de destino.
2. En el menú de la izquierda, seleccione Conexiones de datos. A continuación, active la casilla situada junto a la conexión de datos de IoT Hub correspondiente.
3. Seleccione Eliminar en la barra de menús superior.

C#

Para quitar la conexión de IoT Hub, ejecute el siguiente comando:

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

Python

Para quitar la conexión de IoT Hub, ejecute el siguiente comando:

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)

Pasos siguientes

• Consulta de datos en Azure Data Explorer