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

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

Para obter informações gerais sobre como ingerir no Azure Data Explorer a partir do Hub IoT, consulte Conectar-se ao Hub IoT.

Nota

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

Pré-requisitos

• Uma subscrição do Azure. Crie uma conta do Azure gratuita.
• Um cluster e um banco de dados do Azure Data Explorer. Crie um cluster e um banco de dados.
• Uma tabela de destino. Crie uma tabela ou use 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 sua tabela do Azure Data Explorer. Enquanto essa conexão estiver em vigor, os dados serão transmitidos do Hub IoT para sua tabela de destino.

Portal

1. No menu esquerdo do cluster do Azure Data Explorer, selecione Bancos de Dados e selecione o banco de dados que contém sua 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.

   Definição	Descrição do campo
   Nome da ligação de dados	O nome da conexão que você deseja criar no Azure Data Explorer
   Subscrição	A ID da assinatura onde o recurso Hubs de Eventos está localizado.
   Hub IoT	Nome do Hub IoT
   Política de acesso partilhado	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 e o mapeamento da tabela para incluir as propriedades selecionadas.

   

   Nota

   • As propriedades do sistema de eventos são suportadas para eventos de registro único.
   • Para o 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, convém ativar o roteamento de vários bancos de dados. Para obter mais informações sobre roteamento de banco de dados, consulte Roteamento de eventos.

   

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

   Definição	Valor sugerido	Descrição do campo
   Nome da tabela	TestTable	A tabela que você criou no testdb.
   Formato dos 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 que você criou no testdb, que mapeia os dados de entrada para os nomes de coluna e tipos de dados do testdb. Se não for especificado, um mapeamento de dados de identidade derivado do esquema da tabela será usado.

   

   Nota

   • 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

Em caso de 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á do ID do diretório (locatário), do 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);
   

   Definição	Valor sugerido	Descrição do campo
   tenantId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	O ID do inquilino. Também conhecido como ID de diretório.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	A ID de 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 cluster.
   clusterName	Mykustocluster	O nome do cluster.
   databaseName	mykustodatabase	O nome do banco de dados de destino no cluster.
   iotHubConnectionName	myiothubconnect	O nome desejado da sua 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 do recurso	O ID de recurso do seu 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 se conectarem ao Hub IoT.
   Grupo de consumidores	$Default	O grupo de consumidores do seu hub de eventos.
   localização	E.U.A. Central	O local 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 como Single, a conexão de dados será roteada para um único banco de dados no cluster, conforme especificado na configuração databaseName . Se você definir o valor como Multi, poderá substituir o banco de dados de destino padrão usando a propriedade Database ingestion. Para obter mais informações, consulte Roteamento de eventos.

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á do ID do diretório (locatário), do 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))
   

   Definição	Valor sugerido	Descrição do campo
   tenant_id	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	O ID do inquilino. Também conhecido como ID de diretório.
   subscriptionId	xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx	A ID de 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 cluster.
   cluster_name	Mykustocluster	O nome do cluster.
   database_name	mykustodatabase	O nome do banco de dados de destino no cluster.
   data_connection_name	MyEventHubConnect	O nome desejado da sua 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 do recurso	O ID de recurso do seu 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 se conectarem ao Hub IoT.
   consumer_group	$Default	O grupo de consumidores do seu hub de eventos.
   localização	E.U.A. Central	O local 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 como Single, a conexão de dados será roteada para um único banco de dados no cluster, conforme especificado na configuração databaseName . Se você definir o valor como Multi, poderá substituir o banco de dados de destino padrão usando a propriedade Database ingestion. Para obter mais informações, consulte Roteamento de eventos.

Modelo 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 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óximos passos

• Consultar dados no Azure Data Explorer