Criar uma ligação de dados do Event Grid para o Azure Data Explorer

Neste artigo, vai aprender a ingerir blobs da sua conta de armazenamento no Azure Data Explorer através de uma ligação de dados do Event Grid. Irá criar uma ligação de dados do Event Grid que define uma subscrição Azure Event Grid. A subscrição do Event Grid encaminha eventos da sua conta de armazenamento para o Azure Data Explorer através de um Hubs de Eventos do Azure.

Nota

A ingestão suporta um tamanho máximo de ficheiros de 6 GB. A recomendação é ingerir ficheiros entre 100 MB e 1 GB.

Para saber como criar a ligação com os SDKs do Kusto, veja Criar uma ligação de dados do Event Grid com SDKs.

Para obter informações gerais sobre como ingerir no Azure Data Explorer do Event Grid, veja Ligar ao Event Grid.

Nota

Para obter o melhor desempenho com a ligação do Event Grid, defina a rawSizeBytes propriedade ingestão através dos metadados do blob. Para obter mais informações, veja Propriedades de ingestão.

Pré-requisitos

• Uma subscrição do Azure. Crie uma conta gratuita do Azure.
• Um cluster e uma base de dados do Azure Data Explorer. Criar um cluster e uma base de dados.
• Uma tabela de destino. Crie uma tabela ou utilize uma tabela existente.
• Um mapeamento de ingestão para a tabela.
• Uma conta de armazenamento. Uma subscrição de notificação do Event Grid pode ser definida em contas de Armazenamento do Azure para BlobStorage, StorageV2ou Data Lake Storage Gen2.
• Registe o fornecedor de recursos do Event Grid.

Criar uma ligação de dados do Event Grid

Nesta secção, vai estabelecer uma ligação entre o Event Grid e a sua tabela de Data Explorer do Azure.

Portal - Data Explorer do Azure

1. Navegue para o cluster do Azure Data Explorer no portal do Azure.

2. Em Dados, selecione Bases de Dados>TestDatabase.

   

3. Em Definições, selecione Ligações de dados e, em seguida, selecione Adicionar ligação> de dadosEvent Grid (Armazenamento de blobs).

   

4. Preencha o formulário de ligação de dados do Event Grid com as seguintes informações:

   

   Definição	Valor sugerido	Descrição do campo
   Nome da ligação de dados	test-grid-connection	O nome da ligação que pretende criar no Azure Data Explorer. Os nomes de ligação de dados só podem conter carateres alfanuméricos, traços e pontos e ter até 40 carateres de comprimento.
   Subscrição da conta de armazenamento	O ID da subscrição	O ID da subscrição onde se encontra a sua conta de armazenamento.
   Tipo de evento	Blob criado ou Blob mudado	O tipo de evento que aciona a ingestão. O nome do blob mudado é suportado apenas para o armazenamento do ADLSv2. Para mudar o nome de um blob, navegue para o blob em portal do Azure, clique com o botão direito do rato no blob e selecione Mudar o nome. Os tipos suportados são: Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed.
   Conta de armazenamento	gridteststorage1	O nome da conta de armazenamento que criou anteriormente.
   Criação de recursos	Automático	Ativar a criação automática de recursos significa que o Azure Data Explorer cria uma Subscrição do Event Grid, um espaço de nomes dos Hubs de Eventos e um Hubs de Eventos para si. Caso contrário, tem de criar estes recursos manualmente para garantir a criação da ligação de dados. Veja Criar manualmente recursos para a ingestão do Event Grid

   1. Opcionalmente, pode controlar assuntos específicos do Event Grid. Defina os filtros para as notificações da seguinte forma:

      • O campo prefixo é o prefixo literal do assunto. À medida que o padrão aplicado é iniciado, pode abranger vários contentores, pastas ou blobs. Não são permitidos carateres universais.
        • Para definir um filtro no contentor de blobs, o campo tem de ser definido da seguinte forma: /blobServices/default/containers/[container prefix].
        • Para definir um filtro num prefixo de blobs (ou numa pasta no Azure Data Lake Gen2), o campo tem de ser definido da seguinte forma: /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
      • O campo Sufixo é o sufixo literal do blob. Não são permitidos carateres universais.
      • O campo Sensível a Maiúsculas e Minúsculas indica se os filtros de prefixo e sufixo são sensíveis a maiúsculas e minúsculas

      Para obter mais informações sobre a filtragem de eventos, veja Eventos de armazenamento de blobs.

   2. Opcionalmente, pode especificar as definições de encaminhamento de dados de acordo com as seguintes informações. Não tem de especificar todas as definições de encaminhamento de dados. As definições parciais também são aceites.

      Definição	Valor sugerido	Descrição do campo
      Permitir o encaminhamento dos dados para outras bases de dados (ligação de dados de várias bases de dados)	Não permitir	Alterne esta opção se quiser substituir a base de dados de destino predefinida associada à ligação de dados. Para obter mais informações sobre o encaminhamento de bases de dados, veja Encaminhamento de eventos.
      Nome da tabela	TestTable	A tabela que criou em TestDatabase.
      Formato de dados	JSON	Os formatos suportados são APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT e W3CLOG. As opções de compressão suportadas são Zip e Gzip.
      Nome do mapeamento	TestTable_mapping	O mapeamento que criou no TestDatabase, que mapeia os dados recebidos para os nomes de colunas e tipos de dados da TestTable. Se não for especificado, é gerado automaticamente um mapeamento de dados de identidade derivado do esquema da tabela.
      Ignorar erros de formato	Ignorar	Alterne esta opção se quiser ignorar erros de formato para o formato de dados JSON.

      Nota

      Os nomes de tabelas e mapeamentos são sensíveis às maiúsculas e minúsculas.

   3. Opcionalmente, em Definições avançadas, pode especificar o tipo de identidade gerida que é utilizado pela sua ligação de dados. Por predefinição, a opção Atribuída pelo sistema está selecionada.

      Se selecionar Atribuído pelo utilizador, terá de atribuir manualmente uma identidade gerida. Se selecionar um utilizador que ainda não esteja atribuído ao cluster, este será atribuído automaticamente. Para obter mais informações, veja Configurar identidades geridas para o cluster do Azure Data Explorer.

      Se selecionar Nenhum, a conta de armazenamento e o Hub de Eventos são autenticados através de cadeias de ligação. Este método não é recomendado.

      

5. Selecione Criar

Portal - Armazenamento do Azure

1. Navegue para a sua conta de armazenamento no portal do Azure.
2. Selecione Eventos.
3. No separador Introdução, selecione o separador Azure Data Explorer.
4. No mosaico Criar ingestão de dados contínua , selecione Criar.

Escolher o destino para encaminhar eventos para

1. Selecione um cluster no qual pretenda ingerir dados.
2. Selecione uma base de dados de destino.
3. Selecione Selecionar.

Criar ligação de dados

1. Preencha o formulário com as informações seguintes:

   

   Definição	Valor sugerido	Descrição do campo
   Nome da ligação de dados	test-grid-connection	O nome da ligação que pretende criar no Azure Data Explorer.
   Subscrição da conta de armazenamento	O seu ID de subscrição	O ID da subscrição onde se encontra a sua conta de armazenamento.
   Tipo de evento	Blob criado ou o nome do Blob foi mudado	O tipo de evento que aciona a ingestão. O nome do blob mudado é suportado apenas para o armazenamento do ADLSv2. Para mudar o nome de um blob, navegue para o blob no portal do Azure, clique com o botão direito do rato no blob e selecione Mudar o Nome. Os tipos suportados são: Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed.
   Conta de armazenamento	gridteststorage1	A conta de armazenamento a partir da qual acedeu a este assistente é preenchida automaticamente.
   Criação de recursos	Automático	Ativar a criação automática de recursos significa que o Azure Data Explorer cria uma Subscrição do Event Grid, um espaço de nomes dos Hubs de Eventos e um Hub de Eventos para si. Caso contrário, terá de criar estes recursos manualmente para garantir a criação da ligação de dados. Veja Criar manualmente recursos para a ingestão do Event Grid

   1. Opcionalmente, pode controlar assuntos específicos do Event Grid. Defina os filtros para as notificações da seguinte forma:

      • O campo prefixo é o prefixo literal do assunto. À medida que o padrão aplicado é iniciado, pode abranger vários contentores, pastas ou blobs. Não são permitidos carateres universais.
        • Para definir um filtro no contentor de blobs, o campo tem de ser definido da seguinte forma: /blobServices/default/containers/[container prefix].
        • Para definir um filtro num prefixo de blob (ou numa pasta no Azure Data Lake Gen2), o campo tem de ser definido da seguinte forma: /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
      • O campo Sufixo é o sufixo literal do blob. Não são permitidos carateres universais.
      • O campo Sensível a Maiúsculas e Minúsculas indica se os filtros de prefixo e sufixo são sensíveis a maiúsculas e minúsculas

      Para obter mais informações sobre a filtragem de eventos, veja Eventos de armazenamento de blobs.

   2. Opcionalmente, pode especificar as definições de Encaminhamento de dados de acordo com as seguintes informações. Não tem de especificar todas as definições de Encaminhamento de dados. As definições parciais também são aceites.

      Definição	Valor sugerido	Descrição do campo
      Permitir o encaminhamento dos dados para outras bases de dados (ligação a dados de várias bases de dados)	Não permitir	Ative esta opção se quiser substituir a base de dados de destino predefinida associada à ligação de dados. Para obter mais informações sobre o encaminhamento de bases de dados, veja Encaminhamento de eventos.
      Nome da tabela	TestTable	A tabela que criou em TestDatabase.
      Formato de dados	JSON	Os formatos suportados são APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT e W3CLOG. As opções de compressão suportadas são Zip e Gzip.
      Nome do mapeamento	TestTable_mapping	O mapeamento que criou em TestDatabase, que mapeia os dados recebidos para os nomes de colunas e tipos de dados de TestTable. Se não for especificado, é gerado automaticamente um mapeamento de dados de identidade derivado do esquema da tabela.
      Ignorar erros de formato	Ignorar	Ative esta opção se quiser ignorar erros de formato para o formato de dados JSON.

      Nota

      Os nomes de tabelas e mapeamentos são sensíveis às maiúsculas e minúsculas.

   3. Opcionalmente, em Definições avançadas, pode especificar o tipo de identidade gerida que é utilizado pela sua ligação de dados. Por predefinição, a opção Atribuída pelo sistema está selecionada.

      Se selecionar Atribuído pelo utilizador, terá de atribuir manualmente uma identidade gerida. Se selecionar um utilizador que ainda não esteja atribuído ao cluster, este será atribuído automaticamente. Para obter mais informações, veja Configurar identidades geridas para o cluster do Azure Data Explorer.

      Se selecionar Nenhum, a conta de armazenamento e o Hub de Eventos são autenticados através de cadeias de ligação. Este método não é recomendado.

      

2. Selecione Criar.

Modelo ARM

O exemplo seguinte mostra um modelo do Azure Resource Manager para adicionar uma ligação de dados do Event Grid. Pode editar e implementar o modelo no portal do Azure com 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')]"
            }
        }
    ]
}

Utilizar a ligação de dados do Event Grid

Esta secção mostra como acionar a ingestão do Armazenamento de Blobs do Azure ou do Azure Data Lake Gen2 para o cluster após a criação de blobs ou o nome do blob.

Selecione o separador relevante com base no tipo de SDK de armazenamento utilizado para carregar blobs.

Armazenamento de Blobs do Azure

O seguinte exemplo de código utiliza o SDK Armazenamento de Blobs do Azure para carregar um ficheiro para Armazenamento de Blobs do Azure. O carregamento aciona a ligação de dados do Event Grid, 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);

Nota

O Azure Data Explorer não elimina os blobs após a ingestão. Mantenha os blobs durante três a cinco dias com o ciclo de vida do armazenamento de Blobs do Azure para gerir a eliminação de blobs.

Azure Data Lake

O seguinte exemplo de código utiliza o SDK do Azure Data Lake para carregar um ficheiro para Data Lake Storage Gen2. O carregamento aciona a ligação de dados do Event Grid, 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);

Nota

• Ao carregar um ficheiro com o SDK do Azure Data Lake, o evento inicial de criação de ficheiros tem um tamanho de 0, o 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. Este parâmetro faz com que o método de carregamento acione um evento FlushAndClose , indicando que a atualização final foi efetuada e que o fluxo de ficheiros está fechado.
• Para reduzir o tráfego proveniente do Event Grid e otimizar a ingestão de eventos no Azure Data Explorer, recomendamos que filtre a chave data.api para excluir eventos CreateFile. Isto garante que os eventos de criação de ficheiros com o tamanho 0 são filtrados, impedindo erros de ingestão de ficheiro vazio. Para obter mais informações sobre a descarga, veja Método de descarga do Azure Data Lake.

Mudar o nome dos blobs

No ADLSv2, é possível mudar o nome dos diretórios. No entanto, é importante ter em atenção que mudar o nome de um diretório não aciona eventos com o nome do blob nem inicia a ingestão de blobs contidos no diretório. Se quiser garantir a ingestão de blobs após mudar o nome de um diretório, deve mudar diretamente o nome dos blobs individuais no diretório.

O seguinte exemplo de código mostra como mudar o nome de um blob numa conta de armazenamento do 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);

Nota

Se definiu filtros para controlar assuntos específicos ao criar a ligação de dados ou ao criar recursos do Event Grid manualmente, estes filtros são aplicados no caminho do ficheiro de destino.

Nota

Acionar a ingestão após uma CopyBlob operação não é suportada para contas de armazenamento que tenham a funcionalidade de espaço de nomes hierárquico ativada.

Remover uma ligação de dados do Event Grid

Para remover a ligação do Event Grid da portal do Azure, siga os seguintes passos:

1. Aceda ao cluster. No menu esquerdo, selecione Bases de Dados. Em seguida, selecione a base de dados que contém a tabela de destino.
2. No menu esquerdo, selecione Ligações de dados. Em seguida, selecione a caixa de verificação junto à ligação de dados relevante do Event Grid.
3. Na barra de menus superior, selecione Eliminar.

---

Conteúdo relacionado

• Processar dados do hub de eventos com o Azure Stream Analytics