Criar uma conexão de dados da Grade de Eventos para o Azure Data Explorer

Neste artigo, você aprende a incluir blobs de sua conta de armazenamento no Azure Data Explorer usando uma conexão de dados de grade de eventos. Você criará uma conexão de dados de grade de eventos que define uma assinatura da Grade de Eventos do Azure. A assinatura da Grade de Eventos roteia eventos de sua conta de armazenamento para o Azure Data Explorer por meio dos Hubs de Eventos do Azure.

Para obter informações gerais sobre a ingestão no Azure Data Explorer da Grade de Eventos, confira Conectar-se à Grade de Eventos.

Observação

Para obter o melhor desempenho com a conexão da Grade de Eventos, defina a rawSizeBytes propriedade de ingestão por meio dos metadados de blob. Para obter mais informações, consulte propriedades de ingestão.

Pré-requisitos

• Uma assinatura do Azure. Criar uma conta gratuita do Azure.
• 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.
• Uma conta de armazenamento. Uma assinatura de notificação da Grade de Eventos pode ser definida em contas de Armazenamento do Azure para BlobStorage, StorageV2ou Data Lake Storage Gen2.

Criar uma conexão de dados da Grade de Eventos

Nesta seção, você estabelecerá uma conexão entre a Grade de Eventos e a tabela Data Explorer do Azure.

Portal – Data Explorer do Azure

1. No cluster que você criou, selecione bancos de dadosTestDatabase.

   

2. Selecione Ingestão de dadosAdicionar conexão de dados.

   

3. Em Básico, selecione o tipo de conexão: armazenamento de blobs e preencha o formulário com as seguintes informações:

   

   Configuração	Valor sugerido	Descrição do campo
   Nome da conexão de dados	test-grid-connection	O nome da conexão que você deseja criar no Azure Data Explorer.
   Assinatura da conta de armazenamento	Sua ID de assinatura	A ID da assinatura em que sua conta de armazenamento está.
   Conta de armazenamento	gridteststorage1	O nome da conta de armazenamento que você criou anteriormente.
   Tipo de evento	Blob criado ou blob renomeado	O tipo de evento que aciona a ingestão. Há suporte para renomear blobs somente no armazenamento de ADLSv2. Para renomear um blob, navegue até o blob em portal do Azure, clique com o botão direito do mouse no blob e selecione Renomear. Os eventos com suporte são: Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed.
   Criação de recursos	Automática	Defina se você deseja que o Azure Data Explorer crie uma assinatura da Grade de Eventos, um namespace dos Hubs de Eventos e um Hub de Eventos para você. Para criar recursos manualmente, consulte Criar manualmente recursos para a ingestão da Grade de Eventos

4. Selecione a Configurações de filtro, se desejar acompanhar assuntos específicos. Defina os filtros das notificações da seguinte maneira:

   • O campo Prefixo é o prefixo literal do assunto. Como é o padrão aplicado é startswith, pode abranger vários contêineres, pastas ou blobs. Não são permitidos curingas.
     • Para definir um filtro no contêiner de blob, o campo precisa ser definido da seguinte maneira: .
     • Para especificar um filtro em um prefixo de blob (ou uma pasta no Azure Data Lake Gen2), o campo precisa ser definido da seguinte maneira: .
   • O campo Sufixo é o sufixo literal do blob. Não são permitidos curingas.
   • O campo diferenciar maiúsculas de minúsculas indica se os filtros de prefixo e sufixo diferenciam maiúsculas de minúsculas.
   • Para obter mais informações sobre os eventos de filtragem, confira Eventos de armazenamento de blobs.

   

5. Selecione Avançar: propriedades de ingestão.

6. Preencha o formulário com as seguintes informações. Os nomes de tabela e mapeamento diferenciam maiúsculas de minúsculas:

   

   Propriedades de ingestão:

   Configuração	Valor sugerido	Descrição do campo
   Permitir o roteamento dos dados para outros bancos de dados (conexão de dados de vários bancos de dados)	Não permitir	Ative essa opção se você quiser substituir o banco de dados de destino padrão associado à conexão de dados. Para obter mais informações sobre o roteamento do banco de dados, confira Roteamento de eventos.
   Nome da tabela	TestTable	A tabela criada na TestDatabase.
   Formato de dados	JSON	Os formatos com suporte são Avro, CSV, JSON, MULTILINE JSON, ORC, PARQUET, PSV, SCSV, SOHSV, TSV, TXT, TSVE, APACHEAVRO, RAW e W3CLOG. As opções de compactação com suporte são Zip e GZip.
   Mapeamento	TestMapping	O mapeamento que você criou em TestDatabase, que mapeia os dados de entrada para os tipos de dados e nomes de coluna de TestTable. Se não for especificado, um mapeamento de dados de identidade derivado do esquema da tabela será usado.
   Configurações avançadas	Meus dados contêm cabeçalhos	Ignore cabeçalhos. Com suporte para arquivos do tipo *SV.

   Observação

   Você não precisa especificar todas as Configurações de roteamento padrão. Configurações parciais também são aceitas.

7. Selecione Avançar: Examinar + Criar

8. Em *Revisão + criação.

9. Examine os recursos que foram criados automaticamente para você e selecione Criar.

   

10. Aguarde até a conclusão da implantação. Se sua implantação falhou, selecione Detalhes da operação ao lado da fase com falha para obter mais informações sobre o motivo da falha. Selecione Reimplantar para tentar implantar os recursos novamente. Você pode alterar os parâmetros antes da implantação.

    

Portal – Armazenamento do Azure

1. Acesse a conta de armazenamento no portal do Azure. No menu à esquerda, selecione Eventos.

2. No painel principal, selecione a guia Azure Data Explorer.

   

O painel Conexão de dados é aberto com a guia Noções básicas selecionada.

1. Em Básico, preencha o formulário com as seguintes informações:

   

   Configuração	Valor sugerido	Descrição do campo
   Nome da conexão de dados	test-grid-connection	O nome da conexão que você deseja criar no Azure Data Explorer.
   Conta de armazenamento	gridteststorage1	A conta de armazenamento da qual você acessou o assistente. Preenchido automaticamente.
   Tipo de evento	Blob criado ou blob renomeado	O tipo de evento que aciona a ingestão. Há suporte para renomear blobs somente no armazenamento de ADLSv2. Para renomear um blob, navegue até o blob em portal do Azure, clique com o botão direito do mouse no blob e selecione Renomear. Os eventos com suporte são: Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed.
   Criação de recursos	Automática	Defina se você deseja que o Azure Data Explorer crie uma assinatura da Grade de Eventos, um namespace dos Hubs de Eventos e um Hub de Eventos para você. Para criar recursos manualmente, consulte Criar manualmente recursos para a ingestão da Grade de Eventos

2. Selecione Próximo> Propriedades de ingestão.

3. Em Propriedades de ingestão.

4. Preencha o formulário com as seguintes informações. Os nomes de tabela e mapeamento diferenciam maiúsculas de minúsculas:

   

   Configuração	Valor sugerido	Descrição do campo
   Subscription		Sua assinatura do Azure Data Explorer.
   Nome do cluster	TestCluster	O nome do cluster no qual você deseja ingerir dados.
   Nome do Banco de Dados	TestDatabase	O banco de dados de destino que você criou no TestCluster.
   Permitir o roteamento dos dados para outros bancos de dados (conexão de dados de vários bancos de dados)	Não permitir	Ative essa opção se você quiser substituir o banco de dados de destino padrão associado à conexão de dados. Para obter mais informações sobre o roteamento do banco de dados, confira Roteamento de eventos.
   Nome da tabela	TestTable	A tabela de destino criada no TestDatabase.
   Formato de dados	JSON	Os formatos com suporte são Avro, CSV, JSON, MULTILINE JSON, ORC, PARQUET, PSV, SCSV, SOHSV, TSV, TXT, TSVE, APACHEAVRO, RAW e W3CLOG. As opções de compactação com suporte são Zip e GZip.
   Mapeamento	TestMapping	O mapeamento que você criou em TestDatabase, que mapeia os dados de entrada para os tipos de dados e nomes de coluna de TestTable. Se não for especificado, um mapeamento de dados de identidade derivado do esquema da tabela será usado.
   Configurações avançadas	Meus dados contêm cabeçalhos	Ignore cabeçalhos. Com suporte para arquivos do tipo *SV.

   Observação

   Você não precisa especificar todas as Configurações de roteamento de dados. Configurações parciais também são aceitas.

5. Selecione Avançar: Examinar + Criar

6. Em Revisão + criação.

7. Examine os recursos que foram criados automaticamente para você e selecione Criar.

   

8. Aguarde até a conclusão da implantação. Se sua implantação falhou, selecione Detalhes da operação ao lado da fase com falha para obter mais informações sobre o motivo da falha. Selecione Reimplantar para tentar implantar os recursos novamente. Você pode alterar os parâmetros antes da implantação.

   

C#

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

2. Crie um Azure AD entidade de aplicativo a ser usada 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 eventGridConnectionName = "myeventgridconnect";
   //The event hub and storage account that are created as part of the Prerequisites
   var eventHubResourceId = "/subscriptions/<storageAccountSubscriptionId>/resourceGroups/<storageAccountResourceGroupName>/providers/Microsoft.Storage/storageAccounts/<storageAccountName>";
   var storageAccountResourceId = "/subscriptions/<eventHubSubscriptionId>/resourceGroups/<eventHubResourceGroupName>/providers/Microsoft.EventHub/namespaces/<eventHubNamespaceName>/eventhubs/<eventHubName>";
   var consumerGroup = "$Default";
   var location = "Central US";
   //The table and column mapping are created as part of the Prerequisites
   var mappingRuleName = "StormEvents_CSV_Mapping";
   var dataFormat = DataFormat.CSV;
   var blobStorageEventType = "Microsoft.Storage.BlobCreated";
   var databaseRouting = "Multi";
   var eventGridConnectionData = new EventGridDataConnection(
       storageAccountResourceId, eventHubResourceId, consumerGroup,
       tableName: tableName, location: location, mappingRuleName: mappingRuleName,
       dataFormat: dataFormat, blobStorageEventType: blobStorageEventType, databaseRouting: databaseRouting
   );
   await kustoManagementClient.DataConnections.CreateOrUpdateAsync(
       resourceGroupName, clusterName, databaseName, eventGridConnectionName, eventGridConnectionData
   );
   

   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.
   eventGridConnectionName	myeventgridconnect	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.
   eventHubResourceId	ID de Recurso	A ID do recurso do hub de eventos em que a Grade de Eventos foi configurada para enviar eventos.
   storageAccountResourceId	ID de Recurso	A ID do recurso da conta de armazenamento que contém os dados para ingestão.
   consumerGroup	$Default	O grupo de consumidores do hub de eventos.
   local	Centro dos EUA	A localização do recurso de conexão de dados.
   blobStorageEventType	Microsoft.Storage.BlobCreated	O tipo de evento que dispara a ingestão. Os eventos com suporte são: Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed. Há suporte para renomear blobs somente no armazenamento de ADLSv2.
   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 banco de dados individual 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 de ingestãoDatabase. 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 um Azure AD entidade de aplicativo a ser usada 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 EventGridDataConnection
   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 event hub and storage account that are created as part of the Prerequisites
   event_hub_resource_id = "/subscriptions/xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx/resourceGroups/xxxxxx/providers/Microsoft.EventHub/namespaces/xxxxxx/eventhubs/xxxxxx"
   storage_account_resource_id = "/subscriptions/xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx/resourceGroups/xxxxxx/providers/Microsoft.Storage/storageAccounts/xxxxxx"
   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"
   blob_storage_event_type = "Microsoft.Storage.BlobCreated"
   
   #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.begin_create_or_update(resource_group_name=resource_group_name, cluster_name=cluster_name, database_name=database_name, data_connection_name=data_connection_name,
                                               parameters=EventGridDataConnection(storage_account_resource_id=storage_account_resource_id, event_hub_resource_id=event_hub_resource_id, 
                                                                                   consumer_group=consumer_group, table_name=table_name, location=location, mapping_rule_name=mapping_rule_name, data_format=data_format, database_routing=database_routing,
                                                                                   blob_storage_event_type=blob_storage_event_type))
   # The creation of the connection is async. Validation errors are only visible if you wait for the results.
   poller.wait()
   print(poller.result())
   

   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.
   subscription_id	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.
   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 banco de dados individual 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 de ingestãoDatabase. Para obter mais informações, confira Roteamento de evento.
   data_format	csv	O formato de dados da mensagem.
   event_hub_resource_id	ID de Recurso	A ID do recurso do hub de eventos em que a Grade de Eventos foi configurada para enviar eventos.
   storage_account_resource_id	ID de Recurso	A ID do recurso da conta de armazenamento que contém os dados para ingestão.
   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.
   blob_storage_event_type	Microsoft.Storage.BlobCreated	O tipo de evento que dispara a ingestão. Os eventos com suporte são: Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed. Há suporte para renomear blobs somente no armazenamento de ADLSv2.

Modelo de ARM

O exemplo a seguir mostra um modelo do Azure Resource Manager para adicionar uma conexão de dados da Grade de Eventos. 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": {
        "namespaces_eventhubns_name": {
            "type": "string",
            "defaultValue": "eventhubns",
            "metadata": {
                "description": "Specifies the event hub namespace name."
            }
        },
        "EventHubs_eventhubdemo_name": {
            "type": "string",
            "defaultValue": "eventhubdemo",
            "metadata": {
                "description": "Specifies the event hub name."
            }
        },
        "consumergroup_default_name": {
            "type": "string",
            "defaultValue": "$Default",
            "metadata": {
                "description": "Specifies the consumer group of the event hub."
            }
        },
        "StorageAccounts_storagedemo_name": {
            "type": "string",
            "defaultValue": "storagedemo",
            "metadata": {
                "description": "Specifies the storage account name"
            }
        },
        "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 resources"
            }
        },
        "resourceGroup": {
            "type": "string",
            "defaultValue": "[resourceGroup().name]",
            "metadata": {
                "description": "Specifies the resourceGroup of the resources"
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
                "description": "Location for all resources."
            }
        }
    },
    "variables": {
    },
    "resources": [{
            "type": "Microsoft.Kusto/Clusters/Databases/DataConnections",
            "apiVersion": "2022-02-01",
            "name": "[concat(parameters('Clusters_kustocluster_name'), '/', parameters('databases_kustodb_name'), '/', parameters('dataconnections_kustodc_name'))]",
            "location": "[parameters('location')]",
            "kind": "EventGrid",
            "properties": {
                "managedIdentityResourceId": "[resourceId('Microsoft.Kusto/clusters', parameters('clusters_kustocluster_name'))]",
                "storageAccountResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('StorageAccounts_storagedemo_name'))]",
                "eventHubResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.EventHub/namespaces/eventhubs', parameters('namespaces_eventhubns_name'), parameters('EventHubs_eventhubdemo_name'))]",
                "consumerGroup": "[parameters('consumergroup_default_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 da Grade de Eventos

Portal

Para remover a conexão da Grade de Eventos 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 da Grade de Eventos.
3. Na barra de menus superior, selecione Excluir.

C#

Para remover a conexão da Grade de Eventos, execute o seguinte comando:

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

Python

Para remover a conexão da Grade de Eventos, 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

• Processar dados do seu hub de eventos usando Azure Stream Analytics