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

1. Navegue até o cluster do Azure Data Explorer no portal do Azure.

2. Em Dados, selecione Databases>TestDatabase.

   

3. Em Configurações, selecione Conexões de dados e então selecione Adicionar conexão de dados>Grade de Eventos do Azure (armazenamento de blobs).

   

4. Preencha o formulário de conexão de dados do Grade de Eventos do Azure com as informações a seguir:

   

   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 somente caracteres alfanuméricos, traço e ponto e conter até 40 caracteres.
   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. Blob renomeado tem suporte somente para armazenamento ADLSv2. Para renomear um blob, acesse-o no portal do Azure, clique com o botão direito do mouse nele 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ático	Ativar a criação automática de recursos significa que o Azure Data Explorer cria uma Assinatura de Grade de Eventos, um namespace de 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. Consulte Criar recursos manualmente para ingestão da Grade de Eventos

   1. Como alternativa, é possível rastrear assuntos específicos da Grade de Eventos do Azure. 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, abranger vários contêineres, pastas ou blobs. Não são permitidos caracteres curinga.
        • Para definir um filtro no contêiner de blob, o campo precisa ser definido da seguinte maneira: /blobServices/default/containers/[container prefix].
        • 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: /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
      • O campo Sufixo é o sufixo literal do blob. Não são permitidos caracteres curinga.
      • 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 eventos de filtragem, consulte Eventos de armazenamento de blobs.

   2. Como alternativa, é possível 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	Ative essa opção caso você queira 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 os erros de formato	Ignorar	Ative esta opção se quiser ignorar erros de formato de dados JSON.

      Observação

      Os nomes de tabela e mapeamento diferenciam maiúsculas de minúsculas.

   3. Como alternativa, em Configurações avançadas, é possível especificar o Tipo de identidade gerenciada que é usado pela sua conexão de dados. Por padrão, Atribuído pelo sistema é selecionado.

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

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

      

5. Escolha Criar

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

Escolha o destino para rotear os eventos

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

Criar conexão de dados

1. 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. Blob renomeado tem suporte somente para armazenamento ADLSv2. Para renomear um blob, acesse-o no portal do Azure, clique com o botão direito do mouse nele 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 o 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 Assinatura de Grade de Eventos, um namespace de 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. Consulte Criar recursos manualmente para ingestão da Grade de Eventos

   1. Como alternativa, é possível rastrear assuntos específicos da Grade de Eventos do Azure. 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, abranger vários contêineres, pastas ou blobs. Não são permitidos caracteres curinga.
        • Para definir um filtro no contêiner de blob, o campo precisa ser definido da seguinte maneira: /blobServices/default/containers/[container prefix].
        • 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: /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
      • O campo Sufixo é o sufixo literal do blob. Não são permitidos caracteres curinga.
      • 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 eventos de filtragem, consulte Eventos de armazenamento de blobs.

   2. Como alternativa, é possível 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	Ative essa opção caso você queira 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 os erros de formato	Ignorar	Ative esta opção se quiser ignorar erros de formato de dados JSON.

      Observação

      Os nomes de tabela e mapeamento diferenciam maiúsculas de minúsculas.

   3. Como alternativa, em Configurações avançadas, é possível especificar o Tipo de identidade gerenciada que é usado pela sua conexão de dados. Por padrão, Atribuído pelo sistema é selecionado.

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

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

      

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

O exemplo de código a seguir usa o Armazenamento de Blobs do Azure do SDK para carregar um arquivo no 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);

O exemplo de código a seguir usa o Azure Data Lake SDK para fazer upload de um arquivo para o 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);

Renomear blobs

No ADLSv2, é possível renomear diretórios. No entanto, é importante observar que renomear um diretório não dispara eventos de renomeação de 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, deverá renomear 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);