Conexão de dados da Grade de Eventos
A ingestão da Grade de Eventos é um pipeline que escuta o Armazenamento do Azure e atualiza o Azure Data Explorer para efetuar pull de informações quando ocorrem eventos assinados. O Azure Data Explorer oferece a ingestão contínua de notificações de criação ou de renomeação de blob do Armazenamento do Azure (Armazenamento de Blobs e ADLSv2) com a assinatura da Grade de Eventos do Azure e a transmissão dessas notificações ao Azure Data Explorer por meio dos Hubs de Eventos do Azure.
O pipeline de ingestão da Grade de Eventos passa por várias etapas. Você cria uma tabela de destino no Azure Data Explorer na qual os dados em um formato específico serão ingeridos. Depois você cria uma conexão de dados da Grade de Eventos no Azure Data Explorer. A conexão de dados da Grade de Eventos precisa de informações sobre o roteamento de evento, como a tabela para a qual os dados devem ser enviados e o mapeamento de tabela. Você também especifica as propriedades de ingestão, que descrevem os dados a serem ingeridos, a tabela de destino e o mapeamento. Você pode gerar dados de exemplo e carregar blobs ou renomear blobs para testar a conexão. Exclua os blobs após a ingestão.
A ingestão da Grade de Eventos pode ser gerenciada por meio do portal do Azure usando o assistente de ingestão, programaticamente com C# ou Python, ou por meio do modelo do Azure Resource Manager.
Para obter informações gerais sobre a ingestão de dados no Azure Data Explorer, confira Visão geral da ingestão de dados do Azure Data Explorer.
Mecanismos de autenticação de conexão de dados da Grade de Eventos
Conexão de dados baseada em identidade gerenciada (recomendado): usar uma conexão de dados baseada em identidade gerenciada é a maneira mais segura de se conectar a fontes de dados. Ela fornece controle total sobre a capacidade de buscar dados de uma fonte de dados. A configuração de uma conexão de dados da Grade de Eventos com a identidade gerenciada exige as seguintes etapas:
- Adicionar uma identidade gerenciada ao seu cluster.
- Conceder permissões à identidade gerenciada na fonte de dados. Para buscar dados do Armazenamento do Azure, a identidade gerenciada precisa ter, pelo menos, permissões de Leitor de Dados do Blob de Armazenamento na conta do Armazenamento do Azure.
- Conceder permissões à identidade gerenciada no hub de eventos. Para buscar notificações de blob do hub de eventos, a identidade gerenciada precisa ter permissões de Receptor de Dados dos Hubs de Eventos do Azure nos Hubs de Eventos do Azure.
- Defina uma política de identidade gerenciada nos bancos de dados de destino.
- Crie uma conexão de dados usando a autenticação da identidade gerenciada para buscar os dados.
Cuidado
- Se as permissões de identidade gerenciada forem removidas da fonte de dados, a conexão de dados não funcionará mais e não será possível obter os dados da fonte de dados.
- Se a autenticação local estiver desabilitada em um namespace existente dos Hubs de Eventos em que as notificações de blob são transmitidas, você precisará usar a autenticação de identidade gerenciada para a conexão de dados e configurar corretamente os recursos. Para obter mais informações, confira Problemas conhecidos da Grade de Eventos.
Conexão de dados baseada em chave: se uma autenticação de identidade gerenciada não for especificada para a conexão de dados, a conexão usará automaticamente a autenticação baseada em chave como padrão. As conexões baseadas em chave buscam dados usando uma cadeia de conexão de recurso, como a cadeia de conexão dos Hubs de Eventos do Azure. O Azure Data Explorer obtém a cadeia de conexão de recursos para o recurso especificado e a salva com segurança. A cadeia de conexão é usada para buscar dados da fonte de dados.
Cuidado
Se a chave for girada, a conexão de dados não funcionará mais e não será possível obter os dados da fonte de dados. Para corrigir o problema, atualize ou recrie a conexão de dados.
Formato de dados
- Confira Formatos com suporte.
- Confira Compactações com suporte.
O volume original de dados descompactados deve fazer parte dos metadados de blob ou então o Azure Data Explorer fará uma estimativa. O limite de tamanho descompactado de ingestão por arquivo é 6 GB.
Observação
A assinatura de notificação da Grade de Eventos pode ser definida nas contas do Armazenamento do Azure para o
BlobStorage, oStorageV2ou oBlobStorage.
Propriedades da ingestão
Você pode especificar as propriedades de ingestão da ingestão de blob por meio dos metadados do blob. Defina as seguintes propriedades:
| Propriedade | Descrição |
|---|---|
rawSizeBytes |
Tamanho dos dados brutos (descompactados). Para Avro/ORC/Parquet, esse é o tamanho antes que a compactação específica do formato seja aplicada. Forneça o tamanho dos dados originais definindo essa propriedade como o tamanho de dados descompactado em bytes. |
kustoDatabase |
O nome que diferencia maiúsculas de minúsculas do banco de dados de destino. Por padrão, os dados são ingeridos no banco de dados de destino associado à conexão de dados. Use esta propriedade para substituir o banco de dados padrão e enviar os dados para outro banco de dados. Para fazer isso, primeiro você precisa configurar a conexão como uma conexão de vários bancos de dados. |
kustoTable |
O nome que diferencia maiúsculas de minúsculas da tabela de destino existente. Substitui o conjunto Table no painel Data Connection. |
kustoDataFormat |
Formato dos dados. Substitui o conjunto Data format no painel Data Connection. |
kustoIngestionMappingReference |
Nome do mapeamento de ingestão existente a ser usado. Substitui o conjunto Column mapping no painel Data Connection. |
kustoIgnoreFirstRecord |
Se definido como true, o Kusto ignorará a primeira linha do blob. Use em dados de formato tabular (CSV, TSV ou semelhantes) para ignorar os cabeçalhos. |
kustoExtentTags |
Cadeia de caracteres que representa marcas que serão anexadas à extensão resultante. |
kustoCreationTime |
Substitui o Tempo de criação de extensão para o blob, formatado como uma cadeia de caracteres ISO 8601. Use para o provisionamento. |
Roteamento de eventos
Ao criar uma conexão de dados com o cluster, você especifica o roteamento para o qual enviar os dados ingeridos. O roteamento padrão é definido para a tabela de destino especificada na cadeia de conexão associada ao banco de dados de destino. O roteamento padrão dos dados também é conhecido como roteamento estático. Você pode especificar um roteamento alternativo para seus dados usando as propriedades de dados de evento.
Rotear dados de evento para um banco de dados alternativo
O roteamento de dados para um banco de dados alternativo está desativado por padrão. Para enviar os dados para um banco de dados diferente, você precisa primeiro definir a conexão como uma conexão de vários bancos de dados. Faça isso no portal do Azure, no C#, no Python ou em um modelo do ARM. O usuário, o grupo, a entidade de serviço ou a identidade gerenciada usada para permitir o roteamento de banco de dados precisa, pelo menos, ter a função de colaborador e permissões de gravação no cluster. Para obter mais informações, confira Criar uma conexão de dados da Grade de Eventos para o Azure Data Explorer.
Para especificar um banco de dados alternativo, defina Banco de dados propriedade de ingestão.
Aviso
Especificar um banco de dados alternativo sem definir uma conexão de dados de vários bancos de dados causará uma falha na ingestão.
Rotear dados de evento para uma tabela alternativa
Ao configurar uma conexão de armazenamento de blobs com o cluster do Azure Data Explorer, especifique as propriedades da tabela de destino:
- nome da tabela
- data format
- mapping
Você também pode especificar as propriedades da tabela de destino de cada blob usando os metadados do blob. Os dados serão encaminhados dinamicamente, conforme a especificação nas propriedades de ingestão.
O exemplo abaixo mostra como definir as propriedades de ingestão nos metadados do blob antes de carregá-lo. Os blobs são encaminhados para tabelas diferentes.
Além disso, você pode especificar o banco de dados de destino. Uma conexão de dados de Grade de Eventos é criada dentro do contexto de um banco de dados específico. Desse modo, esse banco de dados é o roteamento de banco de dados padrão da conexão de dados. Para enviar os dados para um banco de dados diferente, defina a propriedade de ingestão "KustoDatabase" e defina uma conexão de dados de vários bancos de dados. O roteamento de dados para outro banco de dados é desabilitado por padrão (não permitido). Definir uma propriedade de ingestão de banco de dados diferente do banco de dados da conexão de dados sem permitir o roteamento de dados para vários bancos de dados (definir uma conexão de dados de vários bancos de dados), causará falha na ingestão.
Para obter mais informações, confira Carregar blobs.
var container = new BlobContainerClient("<storageAccountConnectionString>", "<containerName>");
await container.CreateIfNotExistsAsync();
var blob = container.GetBlobClient("<blobName>");
// Blob is dynamically routed to table `Events`, ingested using `EventsMapping` data mapping
await blob.SetMetadataAsync(
new Dictionary<string, string>
{
{ "rawSizeBytes", "4096" }, // the uncompressed size is 4096 bytes
{ "kustoTable", "Events" },
{ "kustoDataFormat", "json" },
{ "kustoIngestionMappingReference", "EventsMapping" },
{ "kustoDatabase", "AnotherDB" }
}
);
await blob.UploadAsync(BinaryData.FromString(File.ReadAllText("<filePath>")));
Carregar blobs
Você pode criar um blob usando um arquivo local, definir as propriedades de ingestão nos metadados do blob e carregá-lo. Para ver exemplos, confira Usar a conexão de dados da Grade de Eventos.
Observação
- É altamente recomendável usar
BlockBlobpara gerar dados, pois usarAppendBlobpode resultar em um comportamento inesperado. - O uso do SDK do Azure Data Lake Storage Gen2 exige o uso de
CreateFilepara carregar arquivos e deFlushno final com o parâmetro de fechamento definido comotrue. Para ver um exemplo detalhado do uso correto do SDK do Data Lake Gen2, confira Usar a conexão de dados da Grade de Eventos. - Não há suporte para o disparo da ingestão após uma operação
CopyBlobem contas de armazenamento que têm o recurso de namespace hierárquico habilitado. - Quando o ponto de extremidade do hub de eventos não reconhece o recebimento de um evento, a Grade de Eventos do Azure ativa um mecanismo de repetição. Se a repetição da entrega falhar, a Grade de Eventos poderá entregar os eventos não entregues a uma conta de armazenamento usando um processo de mensagens mortas. Para saber mais, confira Event Grid message delivery and retry (Entrega e repetição de mensagens da Grade de Eventos).
Renomear blobs
Ao usar o ADLSv2, você pode renomear um blob para disparar a ingestão do blob no Azure Data Explorer. Por exemplo, confira Renomear blobs.
Observação
- É possível renomear o diretório no ADLSv2, mas isso não dispara eventos renomeados de blobs e a ingestão de blobs no diretório. Para ingerir blobs após renomear, renomeie diretamente os blobs desejados.
- 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.
Excluir blobs usando o ciclo de vida do armazenamento
O Azure Data Explorer não exclui os blobs após a ingestão. Use o ciclo de vida do Armazenamento de Blobs do Azure para gerenciar a exclusão de blobs. É recomendado manter os blobs por três a cinco dias.
Problemas conhecidos da Grade de Eventos
Trabalhando sem autenticação local
Se a autenticação local estiver desabilitada no namespace dos Hubs de Eventos que contém o hub de eventos usado para notificações de streaming, use as seguintes etapas para garantir que os dados fluam corretamente do armazenamento para o hub de eventos usando identidades gerenciadas:
- Atribua uma identidade gerenciada atribuída pelo sistema ao tópico do sistema da Grade de Eventos da conta de armazenamento. Para obter mais informações, confira Habilitar identidade gerenciada para tópicos do sistema.
- Conceda permissões de remetente à identidade gerenciada atribuindo a ela a função Remetente de Dados dos Hubs de Eventos do Azure no hub de eventos. Para obter mais informações, confira Adicionar a identidade às funções do Azure em destinos.
- Verifique se a assinatura da Grade de Eventos usa a identidade gerenciada para a entrega de eventos. Para obter mais informações, confira Criar assinaturas de evento que usam uma identidade.
Além disso, configure a conexão de dados da Grade de Eventos para usar a autenticação de identidade gerenciada para que o Azure Data Explorer possa receber notificações do hub de eventos.
Configurar a ingestão da Grade de Eventos em arquivos exportados do Azure Data Explorer
Ao usar o Azure Data Explorer para exportar os arquivos usados na ingestão da Grade de Eventos, observe:
- As notificações da Grade de Eventos não são disparadas quando a cadeia de conexão fornecida ao comando de exportação ou a uma tabela externa é uma cadeia de conexão no formato ADLS Gen2 (por exemplo,
abfss://filesystem@accountname.dfs.core.windows.net), mas a conta de armazenamento não está habilitada para o namespace hierárquico. - Se a conta não está habilitada para o namespace hierárquico, a cadeia de conexão precisa usar o formato do Armazenamento de Blobs (por exemplo,
https://accountname.blob.core.windows.net). A exportação funcionará conforme o esperado mesmo quando a cadeia de conexão do ADLS Gen2 for usada, mas as notificações não serão disparadas e a ingestão da Grade de Eventos não funcionará.
Emulando eventos de armazenamento de componentes personalizados
Ao usar componentes personalizados para emular eventos do Armazenamento do Azure, os eventos emulados devem estar estritamente em conformidade com o esquema de eventos do Armazenamento de Blobs do Azure, pois o Azure Data Explorer descartará eventos que não podem ser analisados pelo SDK da Grade de Eventos.