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

Artigo
02/29/2024

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.

Observação

A ingestão dá suporte para um tamanho do arquivo máximo de 6 GB. A recomendação é ingerir arquivos entre 100 MB e 1 GB.

Para saber como criar a conexão usando os SDKs do Kusto, confira Criar uma conexão de dados da Grade de Eventos com SDKs.

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.
Registre o provedor de recursos da Grade de Eventos.

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 de Data Explorer do Azure.

Navegue até o cluster de Data Explorer do Azure no portal do Azure.
Em Dados, selecione Bancos> de DadosTestDatabase.
Em Configurações, selecione Conexões de dados e, em seguida, selecione Adicionar grade de eventos de conexão> de dados(armazenamento de blobs).

Preencha o formulário de conexão de dados da Grade de Eventos 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. Os nomes de conexão de dados podem conter apenas caracteres alfanuméricos, traços e pontos e ter até 40 caracteres de comprimento.
Assinatura da conta de armazenamento	Sua ID de assinatura	A ID da assinatura em que sua conta de armazenamento está.
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.
Conta de armazenamento	gridteststorage1	O nome da conta de armazenamento que você criou anteriormente.
Criação de recursos	Automática	Ativar a criação automática de recursos significa que o Azure Data Explorer cria uma Assinatura da Grade de Eventos, um namespace dos Hubs de Eventos e um Hubs de Eventos para você. Caso contrário, você precisará criar esses recursos manualmente para garantir a criação da conexão de dados. Confira Criar recursos manualmente para ingestão da Grade de Eventos

Opcionalmente, você pode acompanhar assuntos específicos da Grade de Eventos. Defina os filtros das notificações da seguinte maneira:
- O campo Prefixo é o prefixo literal do assunto. Como o padrão aplicado começa com, ele 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 como filtrar eventos, consulte Eventos de armazenamento de blobs.

Opcionalmente, você pode especificar as configurações de roteamento de dados de acordo com as informações a seguir. Você não precisa especificar todas as Configurações de roteamento de dados. Configurações parciais também são aceitas.

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	Alterne 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 APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT e W3CLOG. As opções de compactação com suporte são Zip e GZip.
Nome do mapeamento	TestTable_mapping	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á gerado automaticamente.
Ignorar erros de formato	Ignorar	Alterne essa opção se você quiser ignorar erros de formato para o formato de dados JSON.

Observação

Nomes de tabela e mapeamento diferenciam maiúsculas de minúsculas.

Opcionalmente, em Configurações avançadas, você pode especificar o tipo de identidade gerenciada que é usado pela conexão de dados. Por padrão, Atribuído pelo sistema está selecionado.

Se você selecionar Atribuído pelo usuário, precisará atribuir manualmente uma identidade gerenciada. Se você selecionar um usuário que ainda não esteja atribuído ao cluster, ele será atribuído automaticamente. Para obter mais informações, consulte Configurar identidades gerenciadas para o cluster Data Explorer do Azure.

Se você selecionar Nenhum, a conta de armazenamento e o Hub de Eventos serão autenticados por meio de cadeias de conexão. Esse método não é recomendado.

Escolha Criar

Navegue até sua conta de armazenamento no portal do Azure.
Selecione Eventos.
Na guia Introdução, selecione a guia Data Explorer do Azure.
No bloco Criar ingestão contínua de dados , selecione Criar.

Escolher o destino para rotear eventos para

Selecione um cluster no qual você deseja ingerir dados.
Selecione um banco de dados de destino.
Selecione Selecionar.

Criar conexão de dados

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á.
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.
Conta de armazenamento	gridteststorage1	A conta de armazenamento da qual você acessou esse assistente é preenchida automaticamente.
Criação de recursos	Automática	Ativar a criação automática de recursos significa que o Azure Data Explorer cria uma Assinatura da Grade de Eventos, um namespace dos Hubs de Eventos e um Hubs de Eventos para você. Caso contrário, você precisará criar esses recursos manualmente para garantir a criação da conexão de dados. Confira Criar recursos manualmente para ingestão da Grade de Eventos

Opcionalmente, você pode acompanhar assuntos específicos da Grade de Eventos. Defina os filtros das notificações da seguinte maneira:
- O campo Prefixo é o prefixo literal do assunto. À medida que o padrão aplicado é iniciado com, ele 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 como filtrar eventos, consulte Eventos de armazenamento de blobs.

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	Alterne 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 APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT e W3CLOG. As opções de compactação com suporte são Zip e GZip.
Nome do mapeamento	TestTable_mapping	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á gerado automaticamente.
Ignorar erros de formato	Ignorar	Alterne essa opção se você quiser ignorar erros de formato para o formato de dados JSON.

Observação

Nomes de tabela e mapeamento diferenciam maiúsculas de minúsculas.

Opcionalmente, em Configurações avançadas, você pode especificar o tipo de identidade gerenciada usado pela conexão de dados. Por padrão, atribuído pelo sistema é selecionado.

Se você selecionar Atribuído pelo usuário, precisará atribuir manualmente uma identidade gerenciada. Se você selecionar um usuário que ainda não esteja atribuído ao cluster, ele será atribuído automaticamente. Para obter mais informações, consulte Configurar identidades gerenciadas para o cluster Data Explorer do Azure.

Se você selecionar Nenhum, a conta de armazenamento e o Hub de Eventos serão autenticados por meio de cadeias de conexão. Esse método não é recomendado.

Selecione Criar.

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

Usar a conexão de dados da Grade de Eventos

Esta seção mostra como disparar a ingestão do Armazenamento de Blobs do Azure ou do Azure Data Lake Gen 2 para o cluster após a criação de blobs ou a renomeação de blob.

Selecione a guia relevante com base no tipo de SDK de armazenamento usado para carregar blobs.

Armazenamento de Blobs do Azure
Azure Data Lake

O exemplo de código a seguir usa o SDK do Armazenamento de Blobs do Azure para carregar um arquivo para Armazenamento de Blobs do Azure. O upload dispara a conexão de dados da Grade de Eventos, que ingere os dados no Azure Data Explorer.

var azureStorageAccountConnectionString = <storage_account_connection_string>;
var containerName = <container_name>;
var blobName = <blob_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
// Create a new container if it not already exists.
var azureStorageAccount = new BlobServiceClient(azureStorageAccountConnectionString);
var container = azureStorageAccount.GetBlobContainerClient(containerName);
container.CreateIfNotExists();
// Define blob metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new BlobUploadOptions
{
    Metadata = metadata,
};
// Upload the file.
var blob = container.GetBlobClient(blobName);
blob.Upload(localFileName, uploadOptions);

Observação

O Azure Data Explorer não excluirá os blobs após a ingestão. Mantenha os blobs por três a cinco dias usando o ciclo de vida do Armazenamento de Blobs do Azure para gerenciar a exclusão de blobs.

O exemplo de código a seguir usa o SDK do Azure Data Lake para carregar um arquivo para Data Lake Storage Gen2. O upload dispara a conexão de dados da Grade de Eventos, que ingere os dados no Azure Data Explorer.

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var fileName = <file_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Create the filesystem.
var dataLakeFileSystemClient = dataLakeServiceClient.CreateFileSystem(fileSystemName).Value;
// Define file metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new DataLakeFileUploadOptions
{
    Metadata = metadata,
    Close = true // Note: The close option triggers the event being processed by the data connection.
};
// Upload the file.
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(fileName);
dataLakeFileClient.Upload(localFileName, uploadOptions);

Observação

Ao carregar um arquivo com o SDK do Azure Data Lake, o evento de criação de arquivo inicial tem um tamanho de 0, que é ignorado pelo Azure Data Explorer durante a ingestão de dados. Para garantir a ingestão adequada, defina o Close parâmetro como true. Esse parâmetro faz com que o método de upload dispare um evento FlushAndClose , indicando que a atualização final foi feita e o fluxo de arquivos está fechado.
Para reduzir o tráfego proveniente da Grade de Eventos e otimizar a ingestão de eventos no Azure Data Explorer, recomendamos filtrar a chave data.api para excluir eventos CreateFile. Isso garante que os eventos de criação de arquivo com tamanho 0 sejam filtrados, impedindo erros de ingestão de arquivo vazio. Para obter mais informações sobre a liberação, confira Método de liberação do Azure Data Lake.

Renomear blobs

No ADLSv2, é possível renomear diretórios. No entanto, é importante observar que renomear um diretório não dispara eventos renomeados por blob nem inicia a ingestão de blobs contidos no diretório. Se você quiser garantir a ingestão de blobs depois de renomear um diretório, renomeie diretamente os blobs individuais dentro do diretório.

O exemplo de código a seguir mostra como renomear um blob em uma conta de armazenamento ADLSv2.

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var sourceFilePath = <source_file_path>;
var destinationFilePath = <destination_file_path>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Get a client to the the filesystem

var dataLakeFileSystemClient = dataLakeServiceClient.GetFileSystemClient(fileSystemName);
// Rename a file in the file system
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(sourceFilePath);
dataLakeFileClient.Rename(destinationFilePath);

Observação

Se você definiu filtros para acompanhar assuntos específicos ao criar a conexão de dados ou ao criar os recursos da Grade de Eventos manualmente, esses filtros serão aplicados no caminho do arquivo de destino.

Observação

Não há suporte para disparar a ingestão após uma CopyBlob operação para contas de armazenamento que têm o recurso de namespace hierárquico habilitado.

Remover uma conexão de dados da Grade de Eventos

Para remover a conexão da Grade de Eventos do portal do Azure, execute as seguintes etapas:

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.
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.
Na barra de menus superior, selecione Excluir.

Processar dados do hub de eventos usando o Azure Stream Analytics

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

Pré-requisitos

Criar uma conexão de dados da Grade de Eventos

Escolher o destino para rotear eventos para

Criar conexão de dados

Usar a conexão de dados da Grade de Eventos

Renomear blobs

Remover uma conexão de dados da Grade de Eventos

Comentários

Comentários

Recursos adicionais

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

Pré-requisitos

Criar uma conexão de dados da Grade de Eventos

Usar a conexão de dados da Grade de Eventos

Remover uma conexão de dados da Grade de Eventos

Conteúdo relacionado

Comentários

Comentários

Recursos adicionais