Conexão de dados da Grade de Eventos

A ingestão do Event Grid é um pipeline que monitoriza o armazenamento do Azure e atualiza o Azure Data Explorer para extrair informações quando ocorrem eventos inscritos. O Azure Data Explorer oferece ingestão contínua do Armazenamento do Azure (armazenamento de Blob e ADLSv2) com a assinatura da Grade de Eventos do Azure para notificações de blobs criados ou renomeados e transmissão dessas notificações para o Azure Data Explorer por meio de Azure Event Hubs.

O pipeline de ingestão do Event Grid 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. Em seguida, crie uma conexão de dados da Grade de Eventos no Azure Data Explorer. A conexão de dados da Grade de Eventos precisa saber informações de roteamento de eventos , como para qual tabela enviar os dados e o mapeamento da 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 sua conexão. Elimine as bolhas após a ingestão.

A ingestão de Grade de Eventos pode ser gerenciada por meio do portal do Azure, usando o assistente de ingestão, programaticamente com C# ou Python ou com o modelo do Azure Resource Manager.

Para obter informações gerais sobre a ingestão de dados no Azure Data Explorer, consulte 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. Ele fornece controle total sobre a capacidade de buscar dados de uma fonte de dados.

A configuração de uma conexão de dados de Grade de Eventos usando identidade gerenciada requer as seguintes etapas e permissões:
1. Verifique se você tem a atribuição da função de Colaborador do EventGrid na assinatura do Azure da conta de armazenamento de dados de origem.
2. Adicione uma identidade gerenciada ao cluster.
3. Conceda permissões à identidade gerenciada na fonte de dados. Para buscar dados do Armazenamento do Azure, a identidade gerida deve ter, pelo menos, permissões de Leitor de Dados de Blob de Armazenamento na conta de Armazenamento do Azure.
4. Conceda permissões à identidade gerenciada no hub de eventos. Para buscar notificações de blob do hub de eventos, a identidade gerida deve possuir permissões de Recetor de Dados dos Hubs de Eventos do Azure nos Hubs de Eventos do Azure.
5. Defina uma política de identidade gerenciada nos bancos de dados de destino.
6. Crie uma conexão de dados usando a autenticação de identidade gerenciada para buscar dados.
Observação
- O grupo de consumidores do hub de eventos deve ser exclusivo por consumidor. Crie um grupo de consumidores dedicado para cada conexão de dados do Azure Data Explorer.
Atenção
- 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 poderá buscar dados da fonte de dados.
- Se a autenticação local estiver desabilitada em um namespace de Hubs de Eventos existente onde as notificações de blob são transmitidas, você deverá usar a autenticação de identidade gerenciada para a conexão de dados e configurar corretamente os recursos. Para obter mais informações, consulte 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 assumirá automaticamente como padrão a autenticação baseada em chave. 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 recurso para o recurso especificado e a salva com segurança. A cadeia de conexão é usada para buscar dados da fonte de dados.

Atenção

Se a chave for girada, a conexão de dados não funcionará mais e não poderá buscar dados da fonte de dados. Para corrigir o problema, atualize ou recrie a conexão de dados.

Formato dos dados

Consulte os formatos suportados.
Consulte as compressões suportadas.
- O tamanho original dos dados não compactados deve fazer parte dos metadados de blob, caso contrário, o Azure Data Explorer o estimará. O limite de tamanho não comprimido de ingestão por ficheiro é de 6 GB.
  
  Observação
  
  A subscrição de notificações do Event Grid pode ser configurada em contas de Armazenamento do Azure para BlobStorage, StorageV2 ou Data Lake Storage Gen2.

Propriedades de ingestão

Você pode especificar as propriedades de ingestão do blob por meio dos metadados do blob. Você pode definir as seguintes propriedades:

Propriedade	Descrição
`rawSizeBytes`	Tamanho dos dados brutos (não compactados). Para Avro/ORC/Parquet, esse é o tamanho antes da compactação específica do formato ser aplicada. Forneça o tamanho dos dados originais definindo essa propriedade como o tamanho dos dados não compactados em bytes.
`kustoDatabase`	O nome do banco de dados de destino com distinção entre maiúsculas e minúsculas. Por padrão, os dados são ingeridos no banco de dados de destino associado à conexão de dados. Use essa propriedade para substituir o banco de dados padrão e enviar dados para um banco de dados diferente. Para fazer isso, você deve primeiro configurar a conexão como uma conexão de vários bancos de dados.
`kustoTable`	O nome que distingue maiúsculas de minúsculas da tabela de destino existente. Substitui o `Table` definido no painel `Data Connection`.
`kustoDataFormat`	Formato de dados. Substitui o `Data format` definido no painel `Data Connection`.
`kustoIngestionMappingReference`	Nome do mapeamento de ingestão existente a ser usado. Substitui o `Column mapping` definido no painel `Data Connection`.
`kustoIgnoreFirstRecord`	Se definido como `true`, Kusto ignora a primeira linha do blob. Use dados em formato tabular (CSV, TSV ou similar) para ignorar cabeçalhos.
`kustoExtentTags`	String que representa as tags que serão anexadas na 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 enchimento de retaguarda.

Roteamento de eventos

Ao criar uma conexão de dados com o cluster, você especifica o roteamento para onde enviar os dados ingeridos. O roteamento padrão é para a tabela de destino especificada na cadeia de conexão associada ao banco de dados de destino. O roteamento padrão para seus dados também é conhecido como roteamento estático. Você pode especificar um roteamento alternativo para seus dados usando as propriedades de dados de evento.

Encaminhar dados de eventos 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ê deve primeiro definir a conexão como uma conexão de vários bancos de dados. Você pode fazer isso no portal do Azure, C#, Python ou um modelo ARM. O utilizador, grupo, principal de serviço ou identidade gerida usada para permitir o roteamento de base de dados deve ter, pelo menos, a função de colaborador e permissões de gravação no cluster. Para obter mais informações, consulte Criar uma conexão de dados de grade de eventos para o Azure Data Explorer.

Para especificar um banco de dados alternativo, defina a propriedade de ingestãodo banco de dados.

Advertência

Especificar um banco de dados alternativo sem definir a conexão como uma conexão de dados de vários bancos de dados faz com que a ingestão falhe.

Encaminhar dados de eventos para uma tabela alternativa

Ao configurar uma conexão de armazenamento de blob para o cluster do Azure Data Explorer, especifique as propriedades da tabela de destino:

nome da tabela
formato dos dados
mapeamento

Você também pode especificar propriedades da tabela de destino para cada blob, usando metadados de blob. Os dados serão encaminhados dinamicamente, conforme as especificações das configurações de ingestão.

O exemplo abaixo mostra como configurar as propriedades de ingestão nos metadados do blob antes de fazer o upload. Os blobs são roteados para tabelas diferentes.

Além disso, você pode especificar o banco de dados de destino. Uma conexão de dados da Grade de Eventos é criada dentro do contexto de um banco de dados específico. Portanto, 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 a conexão de dados como uma conexão de dados de banco de dados múltiplo. 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 (definindo a conexão como uma conexão de dados de banco de dados múltiplo), fará com que a ingestão falhe.

Para obter mais informações, veja 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 blocos de dados

Você pode criar um blob a partir de um arquivo local, definir propriedades de ingestão para os metadados do blob e carregá-lo. Para obter exemplos, consulte Usar a conexão de dados da Grade de Eventos.

Observação

É altamente recomendável usar BlockBlob para gerar dados, pois o uso AppendBlob pode resultar em um comportamento inesperado.
Usar o SDK de armazenamento do Azure Data Lake Gen2 requer o uso CreateFile para carregar arquivos e Flush , no final, com o parâmetro close definido como true. Para obter um exemplo detalhado do uso correto do SDK do Data Lake Gen2, consulte Usar a conexão de dados da Grade de Eventos.
Para contas de armazenamento que tenham o recurso de namespace hierárquico ativado, não há suporte para desencadear o processo de ingestão após uma CopyBlob operação.
Quando o ponto de extremidade do hub de eventos não confirma o recebimento de um evento, a Grade de Eventos do Azure ativa um mecanismo de repetição. Se essa nova tentativa de entrega falhar, a Grade de Eventos poderá entregar os eventos não entregues a uma conta de armazenamento usando um processo de dead-lettering. Para obter mais informações, consulte Entrega e repetição de mensagens da Grade de Eventos.
Usar a API "OpenWrite" para gravar em um blob não é recomendado, pois ele dispara uma notificação para um blob vazio e causa um erro de blob vazio. Além disso, limpe o fluxo apenas uma vez para evitar notificações duplicadas e várias ingestões do mesmo blob.
O Azure Data Explorer tenta filtrar as notificações duplicadas para o mesmo blob enviadas por serviços de origem, como o Grade de Eventos ou o Armazenamento. Quando deteta um evento duplicado, ignora a ingestão e regista o erro BlobAlreadyReceived_DuplicateEventGridNotification, o que significa que o blob já está processado.

Renomear objetos blob

Ao usar o ADLSv2, poderá renomear um blob para ativar a ingestão de blob no Azure Data Explorer. Por exemplo, consulte Renomear blobs.

Observação

A renomeação de diretórios é possível no ADLSv2, mas não aciona eventos de renomeação de blob e a ingestão de blobs dentro do diretório. Para ingerir blobs após a renomeação, renomeie diretamente os blobs desejados.
Se você definiu filtros para rastrear assuntos específicos ao criar a conexão de dados ou ao criar recursos da Grade de Eventos manualmente, esses filtros serão aplicados no caminho do arquivo de destino.

Excluir blobs usando ciclo de vida de armazenamento

A lógica incorporada no Azure Data Explorer não excluirá os blobs após a ingestão. Utilize o ciclo de vida do armazenamento de blobs do Azure para gerir a eliminação de blobs. Recomenda-se manter as bolhas por três a cinco dias.

Problemas conhecidos da grade de eventos

Trabalhar sem autenticação local

Se a autenticação local estiver desabilitada no namespace 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:

Passos
Script do PowerShell

Atribua uma identidade gerenciada atribuída pelo sistema ao tópico Sistema de grade de eventos da conta de armazenamento. Para obter mais informações, consulte Habilitar identidade gerenciada para tópicos do sistema.
Conceda permissões de remetente de identidade gerenciada atribuindo-lhe a função de Remetente de Dados dos Hubs de Eventos do Azure no hub de eventos. Para obter mais informações, consulte Adicionar identidade a funções do Azure em destinos.
Certifique-se de que a subscrição da Grade de Eventos utiliza uma identidade gerida para a entrega dos eventos. Para obter mais informações, consulte Criar assinaturas de eventos que usam uma identidade.

$eventGridSubscriptionId = "<AZURE SUBSCRIPTION ID OF EVENTGRID SYSTEM TOPIC>"
$eventGridResourceGroupName = "<RESOURCE GROUP NAME CONTAINING THE EVENTGRID SYSTEM TOPIC>"
$eventGridSystemTopicName = "<EVENTGRID SYSTEM TOPIC NAME>"
$eventGridSubscriptionName = "<EVENTGRID SUBSCRIPTION NAME>"

$eventhubSubscriptionId = "<AZURE SUBSCRIPTION ID OF EVENTHUB NAMESPACE>"
$eventhubResourceGroupName = "<RESOURCE GROUP NAME CONTAINING THE EVENTHUB NAMESPACE>"
$eventhubNamespaceName = "<THE EVENTHUB NAMESPACE NAME>"
$eventhubName = "<THE EVENTHUB NAME>"

Set-AzContext -SubscriptionId $eventGridSubscriptionId

Write-Host "Checking if Event Grid Topic exists"
$eg = Get-AzEventGridSystemTopic -ResourceGroupName $eventGridResourceGroupName -Name $eventGridSystemTopicName
$hasSystemAssignedIdentity = $eg.IdentityType -match "SystemAssigned"

if ($hasSystemAssignedIdentity) {
    Write-Host -ForegroundColor Green "Event Grid Topic $eventGridSystemTopicName already has a system-assigned identity"
}
else {
    Write-Host "Event Grid Topic $eventGridSystemTopicName doesn't have a system-assigned identity. Assigning one..."
    Update-AzEventGridSystemTopic -ResourceGroupName $eventGridResourceGroupName -Name $eventGridSystemTopicName -EnableSystemAssignedIdentity $true
    Write-Host -ForegroundColor Green "System-assigned identity has been assigned to Event Grid Topic $eventGridSystemTopicName"
}

$eg = Get-AzEventGridSystemTopic -ResourceGroupName $eventGridResourceGroupName -Name $eventGridSystemTopicName
$identityPrincipalId = $eg.IdentityPrincipalId

Set-AzContext -SubscriptionId $eventhubSubscriptionId

$eventhubResourceId = "/subscriptions/$eventhubSubscriptionId/resourceGroups/$eventhubResourceGroupName/providers/Microsoft.EventHub/namespaces/$eventhubNamespaceName/eventhubs/$eventhubName"

Write-Host "Checking if Azure Event Hubs Data Sender role is assigned to Event Grid Topic's system-assigned identity $identityPrincipalId for Event Hub $eventhubName"
$roleAssignment = Get-AzRoleAssignment -ObjectId $identityPrincipalId -RoleDefinitionName "Azure Event Hubs Data Sender" -Scope $eventhubResourceId
$hasRoleAssignment = $null -ne $roleAssignment

if ($hasRoleAssignment) {
    Write-Host -ForegroundColor Yellow "Azure Event Hubs Data Sender role is already assigned to Event Grid Topic's system-assigned identity $identityPrincipalId for Event Hub $eventhubName"
}
else {
    Write-Host "Going to assign Azure Event Hubs Data Sender role to Event Grid Topic's system-assigned identity $identityPrincipalId for Event Hub $eventhubResourceId"
    New-AzRoleAssignment -ObjectId $identityPrincipalId -RoleDefinitionName "Azure Event Hubs Data Sender" -Scope "/subscriptions/$eventhubSubscriptionId/resourceGroups/$eventhubResourceGroupName/providers/Microsoft.EventHub/namespaces/$eventhubNamespaceName/eventhubs/$eventhubName"
    Write-Host -ForegroundColor Green "Azure Event Hubs Data Sender role has been assigned to Event Grid Topic's system-assigned identity $identityPrincipalId for Event Hub $eventhubName"
}

Write-Host "Checking if Event Subscription $eventSubscriptionName is using Systeam assigned identity"
$eventGridSubscribtion = Get-AzEventGridSystemTopicEventSubscription -ResourceGroupName $eventGridResourceGroupName -SystemTopicName $eventGridSystemTopicName -EventSubscriptionName $eventGridSubscriptionName
$deliveryIdentityType = $eventGridSubscribtion.DeliveryWithResourceIdentityType
$destination = $eventGridSubscribtion.Destination

if ($deliveryIdentityType -eq "SystemAssigned") {
    Write-Host -ForegroundColor Yellow "Event Subscription $eventGridSubscriptionName is allready using System Assigned Identity"
}
else {
    Write-Host "Event Subscription $eventGridSubscriptionName is not using System Assigned Identity. Updating..."
    Update-AzEventGridSystemTopicEventSubscription -ResourceGroupName $eventGridResourceGroupName -SystemTopicName $eventGridSystemTopicName -EventSubscriptionName $eventGridSubscriptionName -DeliveryWithResourceIdentityType "SystemAssigned" -DeliveryWithResourceIdentityDestination $destination
    Write-Host -ForegroundColor Green "Event Subscription $eventGridSubscriptionName is now using System Assigned Identity"
}

Write-Host -ForegroundColor Green "%%%%%%%% Script has been executed successfully %%%%%%%%"

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 de Grade de Eventos em arquivos exportados do Azure Data Explorer

Ao usar o Azure Data Explorer para exportar os arquivos usados para ingestão de Grade de Eventos, observe:

As notificações de Grade de Eventos não serão acionadas se a cadeia de conexão fornecida ao comando export ou a cadeia de conexão fornecida a uma tabela externa for 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 estiver habilitada para namespace hierárquico.
Se a conta não estiver habilitada para namespace hierárquico, a cadeia de conexão deverá usar o formato de Armazenamento de Blob (por exemplo, https://accountname.blob.core.windows.net). A exportação funciona como esperado mesmo ao usar a cadeia de conexão ADLS Gen2, mas as notificações não serão acionadas 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.

Feedback

Esta página foi útil?

Last updated on 2025-08-11