Criar uma conexão de dados do Hub IoT para o Azure Data Explorer

Este artigo mostra como ingerir dados no Azure Data Explorer do Hub IoT, de uma plataforma de streaming de Big Data e do serviço de ingestão de IoT.

Para obter informações gerais sobre a ingestão no Azure Data Explorer do Hub IoT, confira Conectar-se ao Hub IoT.

Observação

Somente os eventos enfileirados após a criação da conexão de dados são ingeridos.

Pré-requisitos

• Uma assinatura do Azure. Criar uma conta gratuita do Azure.
• Um cluster e um banco de dados do Azure Data Explorer. Criar um cluster e um banco de dados.
• Uma tabela de destino. Criar uma tabela ou usar uma tabela existente.
• Um mapeamento de ingestão para a tabela.
• Um Hub IoT com dados para ingestão.

Criar uma conexão de dados do Hub IoT

Nesta seção, você estabelecerá uma conexão entre o Hub IoT e a sua tabela do Azure Data Explorer. Enquanto essa conexão estiver em vigor, os dados serão transmitidos do Hub IoT para a tabela de destino.

Portal

1. No menu esquerdo do cluster do Azure Data Explorer, selecione Bancos de dados e, em seguida, selecione o banco de dados que contém a tabela de destino.

   

2. Selecione conexões de dados e Adicionar conexão de dados. Na lista suspensa, selecione Hub IoT.

   

3. Preencha o formulário com as seguintes informações.

   Configuração	Descrição do campo
   Nome da conexão de dados	O nome da conexão que você deseja criar no Azure Data Explorer
   Assinatura	A ID da assinatura em que o recurso dos Hubs de Eventos está localizado.
   Hub IoT	Nome do Hub IoT
   Política de acesso compartilhado	O nome da política de acesso compartilhado. Deve ter permissões de leitura
   Grupo de consumidores	O grupo de consumidores definido no ponto de extremidade interno do Hub IoT
   Propriedades do sistema de eventos	As propriedades do sistema de eventos do Hub IoT. Ao adicionar propriedades do sistema, crie ou atualize o esquema de tabela e o mapeamento de maneira a incluir as propriedades selecionadas.

   

   Observação

   • As propriedades do sistema de eventos são suportadas para eventos de registro único.
   • Para mapeamento CSV, as propriedades são adicionadas no início do registro. Para o mapeamento JSON, as propriedades são adicionadas de acordo com o nome que aparece na lista suspensa.

4. Dependendo do seu caso de uso, talvez você queira ativar o roteamento de vários bancos de dados. Para obter mais informações sobre o roteamento do banco de dados, confira Roteamento de eventos.

   

5. Preencha as seguintes configurações de roteamento:

   Configuração	Valor sugerido	Descrição do campo
   Nome da tabela	TestTable	A tabela criada em testdb.
   Formato de dados	JSON	Os formatos suportados são AVRO, CSV, JSON, ORC, PARQUET, PSV, SCSV, SOHSV, TSV, TXT, TSVE, APACHE AVRO e W3CLOG.
   Mapeamento	TestMapping	O mapeamento criado em testdb, que mapeia os dados de entrada para os tipos de dados e nomes de coluna de testdb. Se não for especificado, um mapeamento de dados de identidade derivado do esquema da tabela será usado.

   

   Observação

   • Os dados JSON são analisados como multijson por padrão. Selecione Ignorar erros de formato para ingerir os dados no formato JSON estrito.
   • Se você selecionou Propriedades do sistema de eventos, deverá incluir as propriedades do sistema no esquema e no mapeamento da tabela.

6. Selecione Criar.

Aviso

No caso de um failover manual, recrie a conexão de dados.

C#

1. Instale o pacote NuGet Microsoft.Azure.Management.Kusto.

2. Crie uma entidade de aplicativo do Azure AD para usar para autenticação. Você precisará da ID do diretório (locatário), da ID do aplicativo e do segredo do cliente.

3. Execute o código a seguir.

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

   Configuração	Valor sugerido	Descrição do campo
   tenantId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	ID do locatário. Também conhecida como ID do diretório.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	A ID da assinatura que você usa para a criação de recursos.
   clientId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	A ID do cliente do aplicativo que pode acessar recursos em seu locatário.
   clientSecret	PlaceholderClientSecret	O segredo do cliente do aplicativo que pode acessar recursos em seu locatário.
   resourceGroupName	testrg	O nome do grupo de recursos que contém o seu cluster.
   clusterName	mykustocluster	O nome do seu cluster.
   databaseName	mykustodatabase	O nome do banco de dados de destino no cluster.
   iotHubConnectionName	myiothubconnect	O nome desejado da conexão de dados.
   tableName	StormEvents	O nome da tabela de destino no banco de dados de destino.
   mappingRuleName	StormEvents_CSV_Mapping	O nome do mapeamento de coluna relacionado à tabela de destino.
   dataFormat	csv	O formato de dados da mensagem.
   iotHubResourceId	ID de Recurso	A ID do recurso do hub IoT que contém os dados para ingestão.
   sharedAccessPolicyName	iothubforread	O nome da política de acesso compartilhado que define as permissões para dispositivos e serviços para se conectar ao Hub IoT.
   consumerGroup	$Default	O grupo de consumidores do hub de eventos.
   local	Centro dos EUA	A localização do recurso de conexão de dados.
   databaseRouting	Multi ou Single	O roteamento de banco de dados para a conexão. Se você definir o valor para Single, a conexão de dados será direcionada para um único banco de dados no cluster conforme especificado na configuração databaseName. Se você definir o valor para Multi, poderá substituir o banco de dados de destino padrão usando a propriedade de ingestão Database. Para obter mais informações, confira Roteamento de evento.

Python

1. Instale as bibliotecas necessárias.

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

2. Crie uma entidade de aplicativo do Azure AD para usar para autenticação. Você precisará da ID do diretório (locatário), da ID do aplicativo e do segredo do cliente.

3. Execute o código a seguir.

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

   Configuração	Valor sugerido	Descrição do campo
   tenant_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	ID do locatário. Também conhecida como ID do diretório.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	A ID da assinatura que você usa para a criação de recursos.
   client_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	A ID do cliente do aplicativo que pode acessar recursos em seu locatário.
   client_secret	xxxxxxxxxxxxxx	O segredo do cliente do aplicativo que pode acessar recursos em seu locatário.
   resource_group_name	testrg	O nome do grupo de recursos que contém o seu cluster.
   cluster_name	mykustocluster	O nome do seu cluster.
   database_name	mykustodatabase	O nome do banco de dados de destino no cluster.
   data_connection_name	myeventhubconnect	O nome desejado da conexão de dados.
   table_name	StormEvents	O nome da tabela de destino no banco de dados de destino.
   mapping_rule_name	StormEvents_CSV_Mapping	O nome do mapeamento de coluna relacionado à tabela de destino.
   data_format	csv	O formato de dados da mensagem.
   iot_hub_resource_id	ID de Recurso	A ID do recurso do hub IoT que contém os dados para ingestão.
   shared_access_policy_name	iothubforread	O nome da política de acesso compartilhado que define as permissões para dispositivos e serviços para se conectar ao Hub IoT.
   consumer_group	$Default	O grupo de consumidores do hub de eventos.
   local	Centro dos EUA	A localização do recurso de conexão de dados.
   database_routing	Multi ou Single	O roteamento de banco de dados para a conexão. Se você definir o valor para Single, a conexão de dados será direcionada para um único banco de dados no cluster conforme especificado na configuração databaseName. Se você definir o valor para Multi, poderá substituir o banco de dados de destino padrão usando a propriedade de ingestão Database. Para obter mais informações, confira Roteamento de evento.

Modelo de ARM

O exemplo a seguir mostra um modelo do Azure Resource Manager para adicionar uma conexão de dados do Hub IoT. Você pode editar e implantar o modelo no portal do Azure usando o formulário.

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

Remover uma conexão de dados do Hub IoT

Portal

Para remover a conexão do Hub IoT do portal do Azure, faça o seguinte:

1. Vá para o seu cluster. No menu à esquerda, selecione Bancos de dados. Em seguida, selecione o banco de dados que contém a tabela de destino.
2. No menu à esquerda, selecione Conexões de dados. Em seguida, marque a caixa de seleção ao lado da conexão de dados relevante do Hub IoT.
3. Na barra de menu superior, selecione Excluir.

C#

Para remover a conexão do Hub IoT, execute o seguinte comando:

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

Python

Para remover a conexão do Hub IoT, execute o seguinte 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)

Próximas etapas

• Consultar dados no Azure Data Explorer