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

O Azure Data Explorer oferece ingestão de Hubs de Eventos, uma plataforma de streaming de Big Data e serviços de ingestão de eventos. Os Hubs de Eventos podem processar milhões de eventos por segundo quase em tempo real.

Neste artigo, você se conectará a um hub de eventos e fará ingestão de dados no Azure Data Explorer. Para obter uma visão geral sobre a ingestão dos Hubs de Eventos, consulte Conexão de dados dos Hubs de Eventos do Azure.

Para saber como criar a conexão usando os SDKs do Kusto, consulte Criar uma conexão de dados dos Hubs de Eventos com SDKs.

Para exemplos de código baseados em versões anteriores do SDK, consulte o artigo arquivado.

Criar uma conexão de dados do hub de eventos

Nesta seção, você estabelecerá uma conexão entre o hub de eventos e a tabela do Azure Data Explorer. Enquanto essa conexão estiver em vigor, os dados serão transmitidos do hub de eventos para a tabela de destino. Se o hub de eventos for movido para um recurso ou assinatura diferente, será necessário atualizar ou recriar a conexão.

Obter dados

Pré-requisitos

• Uma conta Microsoft ou uma identidade de usuário do Microsoft Entra. Uma assinatura do Azure não é necessária.
• Um cluster e um banco de dados do Azure Data Explorer. Criar um cluster e um banco de dados.
• A ingestão de streaming deve ser configurada no cluster do Azure Data Explorer.

Obter dados

1. No menu à esquerda, selecione Consulta.

2. Clique com o botão direito do mouse no banco de dados em que deseja ingerir os dados. Selecione Obter dados.

   

Origem

Na janela Obter dados, a guia Origem será selecionada.

Selecione a fonte de dados na lista disponível. Neste exemplo, você está ingerindo dados dos Hubs de Eventos.

Configurar

1. Selecione um banco de dados e uma tabela de destino. Se você quiser ingerir dados em uma nova tabela, selecione + Nova tabela e insira o nome de uma tabela.

   Observação

   Os nomes de tabelas podem ter até 1024 caracteres, incluindo espaços, caracteres alfanuméricos, hifens e sublinhados. Não há suporte para caracteres especiais.

   

2. Preencha os campos a seguir:

   Configuração	Descrição do campo
   Assinatura	A ID da assinatura em que o recurso do hub de eventos está localizado.
   Namespace do Hub de Eventos	O nome que identifica o namespace.
   Hub de eventos	O hub de eventos que você deseja
   Grupo de consumidores	O grupo de consumidores definido em seu evento
   Nome da conexão de dados	O nome que identifica a conexão de dados.
   Filtros avançados
   Compactação	O tipo de compactação do conteúdo das mensagens do hub de eventos.
   Propriedades do sistema de eventos	As propriedades do sistema do hub de eventos. Se houver vários registros por mensagem de evento, as propriedades do sistema serão adicionadas ao primeiro. Ao adicionar propriedades do sistema, crie ou atualize o esquema de tabela e o mapeamento de maneira a incluir as propriedades selecionadas.
   Data de início da recuperação do evento	A conexão de dados recupera eventos existentes dos Hubs de Eventos criados após a data de início da recuperação do evento. Somente eventos retidos pelo período de retenção dos Hubs de Eventos podem ser recuperados. Se a data de início da recuperação do evento não for especificada, a hora padrão será a hora em que a conexão de dados é criada.

3. Selecione Avançar.

Inspecionar

A guia Inspecionar será aberta com uma visualização dos dados.

Para concluir o processo de ingestão, selecione Concluir.

Se desejar:

• Se os dados exibidos na janela de pré-visualização não estiverem completos, talvez você precise de mais dados para criar uma tabela com todos os campos de dados necessários. Use os seguintes comandos para buscar novos dados do hub de eventos:

  • Descartar e buscar novos dados: descarta os dados apresentados e procura novos eventos.

  • Buscar mais dados: procura mais eventos além dos eventos já encontrados.

    Observação

    Para ver uma pré-visualização dos dados, o hub de eventos precisa enviar os eventos.

• Selecione Visualizador de comando para ver e copiar os comandos automáticos gerados com base nas entradas.

• Use a lista suspensa Arquivo de definição de esquema para alterar o arquivo do qual o esquema foi inferido.

• Altere o formato de dados inferido automaticamente selecionando o formato desejado na lista suspensa. Consulte Formatos de dados compatíveis com o Azure Data Explorer para ingestão.

• Editar colunas.

• Explore Opções avançadas com base no tipo de dados.

Editar colunas

Observação

• Para formatos tabulares (CSV, TSV, PSV), você não pode mapear uma coluna duas vezes. Para mapear para uma coluna existente, primeiro exclua a nova coluna.
• Não é possível alterar um tipo de coluna existente. Se você tentar mapear para uma coluna com um formato diferente, poderá ficar com colunas vazias.

As alterações que você pode fazer em uma tabela dependem dos seguintes parâmetros:

• O tipo de tabela é novo ou existente
• O tipo de mapeamento é novo ou existente

Tipo de tabela	Tipo de mapeamento	Ajustes disponíveis
Nova tabela	Novo mapeamento	Renomear coluna, alterar tipo de dados, alterar fonte de dados, transformação de mapeamento, adicionar coluna, excluir coluna
Tabela existente	Novo mapeamento	Adicionar coluna (na qual você pode alterar o tipo de dados, renomear e atualizar)
Tabela existente	Mapeamento existente	nenhum

Transformações de mapeamento

Alguns mapeamentos de formato de dados (Parquet, JSON e Avro) dão suporte a transformações de tempo de ingestão simples. Para aplicar transformações de mapeamento, crie ou atualize uma coluna na janela Editar colunas.

As transformações de mapeamento podem ser executadas em uma coluna de cadeia de caracteres de tipo ou de datetime, com o tipo de dados int ou long selecionado em Origem. As transformações de mapeamento com suporte são:

• DateTimeFromUnixSeconds
• DateTimeFromUnixMilliseconds
• DateTimeFromUnixMicroseconds
• DateTimeFromUnixNanoseconds

Opções avançadas com base no tipo de dados

Tabular (CSV, TSV, PSV):

• Se você estiver assimilando formatos tabulares em uma tabela existente, poderá selecionar Manter esquema de tabela atual avançado>. Os dados tabulares não incluem necessariamente os nomes de coluna usados para mapear os dados de origem para as colunas existentes. Quando essa opção é marcada, o mapeamento é feito por ordem, e o esquema da tabela permanece o mesmo. Se essa opção estiver desmarcada, novas colunas serão criadas para os dados de entrada, independentemente da estrutura de dados.

• Para usar a primeira linha como nomes de coluna, selecione Avançado>A primeira linha é o cabeçalho da coluna.

  

JSON:

• Para determinar a divisão de coluna dos dados JSON, selecione Avançado>Níveis aninhados, de 1 a 100.

• Se você selecionar Ignorar erros de formato de dados avançados>, os dados serão assimilados no formato JSON. Se você deixar essa caixa de seleção desmarcada, os dados serão ingeridos no formato multijson.

  

Resumo

Na janela Preparação de dados, todas as três etapas serão assinaladas com marcas de seleção verdes quando a ingestão de dados for concluída com sucesso. Você pode exibir os comandos que foram usados para cada etapa ou selecionar um cartão para consultar, visualizar ou descartar os dados ingeridos.

Portal – página do Azure Data Explorer

Pré-requisitos

• Uma assinatura do Azure. Criar uma conta gratuita do Azure.
• Um cluster e um banco de dados do Azure Data Explorer. Criar um cluster e um banco de dados.
• Uma tabela de destino. Criar uma tabela ou usar uma tabela existente.
• Um mapeamento de ingestão para a tabela.
• Um hub de eventos com dados para ingestão.

Obter dados

1. No portal do Azure, acesse o cluster e selecione Bancos de dados. Em seguida, selecione o banco de dados que contém sua tabela de destino.

   

2. No menu à esquerda, selecione Assimilação de dados. Em seguida, na barra superior, selecione Adicionar conexão de dados.

3. Preencha o formulário com as seguintes informações e, em seguida, selecione Criar.

   Configuração	Valor sugerido	Descrição do campo
   Nome da conexão de dados	teste de hub de conexão	O nome da conexão que você deseja criar no Azure Data Explorer.
   Assinatura		A ID da assinatura em que o recurso do hub de eventos está localizado.
   Namespace do Hub de Eventos	Um nome de namespace exclusivo	O nome escolhido anteriormente que identifica seu namespace.
   Hub de eventos	test-hub	O hub de eventos que você criou.
   Grupo de consumidores	test-group	O grupo de consumidores definido no hub de eventos que você criou.
   Propriedades do sistema de eventos	Selecionar propriedades relevantes	As propriedades do sistema do hub de eventos. Se houver vários registros por mensagem de evento, as propriedades do sistema serão adicionadas ao primeiro registro. Ao adicionar propriedades do sistema, crie ou atualize o esquema de tabela e o mapeamento de maneira a incluir as propriedades selecionadas.
   Compactação	Nenhum	O tipo de compactação do conteúdo das mensagens do hub de eventos. Tipos de compactação suportados: Nenhum, gzip.
   Identidade gerenciada (recomendável)	Atribuída pelo sistema	A identidade gerenciada usada pelo cluster do Data Explorer para acesso de leitura do hub de eventos. É recomendável usar identidades gerenciadas para controlar o acesso ao seu hub de eventos. Observação: Quando a conexão de dados é criada: * As identidades atribuídas pelo sistema serão criadas automaticamente se ainda não existirem * A identidade gerenciada é atribuída automaticamente à função receptor de dados dos Hubs de Eventos do Azure e adicionada ao cluster do Data Explorer. É recomendável verificar se a função foi atribuída e se a identidade foi adicionada ao cluster.

   Observação

   Se você tiver uma conexão de dados existente que não esteja usando identidades gerenciadas, é recomendável atualizá-la para usar identidades gerenciadas.

Portal – Página Hubs de Eventos do Azure

Pré-requisitos

• Uma assinatura do Azure. Criar uma conta gratuita do Azure.
• Um cluster e um banco de dados do Azure Data Explorer. Criar um cluster e um banco de dados.
• Uma tabela de destino. Criar uma tabela ou usar uma tabela existente.
• Um mapeamento de ingestão para a tabela.
• Um hub de eventos com dados para ingestão.

Obter dados

1. No portal do Azure, navegue até a Instância dos Hubs de Eventos.

2. No menu lateral Recursos, selecione Analisar dados com Kusto.

3. Selecione Iniciar para abrir o assistente de ingestão no Azure Data Explorer.

   

   Observação

   • Você deve ter pelo menos permissões de usuário do banco de dados.
   • Para habilitar o acesso entre um cluster e uma conta de armazenamento sem acesso público, consulte Criar um ponto de extremidade privado gerenciado.
   • O cluster e o hub de eventos devem ser associados aos mesmos locatários. Caso contrário, use uma das opções do SDK, como C# ou Python.

4. O painel lateral Ingestão de dados é aberto com a guia Destino selecionada. Selecione os campos Cluster e Banco de Dados nos menus suspensos. Certifique-se de selecionar um cluster que esteja em execução. Caso contrário, você não poderá selecionar Banco de Dados e prosseguir com o processo de ingestão.

5. Em Tabela, selecione Nova tabela e insira um nome para a nova tabela. Como alternativa, use uma tabela Existente.

6. Selecione Avançar: origem.

7. Em Tipo de origem, o tipo e os detalhes do Hub de Eventos são preenchidos automaticamente com base na Instância dos Hubs de Eventos da qual você começou.

8. Em Conexão de Dados, preencha os seguintes campos e selecione Avançar: Esquema.

   Configuração	Valor sugerido	Descrição do campo
   Assinatura		A ID da assinatura em que o recurso do hub de eventos está localizado.
   Namespace do Hub de Eventos		O nome que identifica o namespace.
   Hub de eventos		O hub de eventos que você deseja usar.
   Nome da conexão de dados	TestDataConnection	O nome que identifica a conexão de dados.
   Grupo de consumidores		O grupo de consumidores definido no hub de eventos.
   Compactação		O tipo de compactação do conteúdo das mensagens do hub de eventos.
   Propriedades do sistema de eventos	Selecionar propriedades relevantes	As propriedades do sistema do hub de eventos. Se houver vários registros por mensagem de evento, as propriedades do sistema serão adicionadas ao primeiro. Ao adicionar propriedades do sistema, crie ou atualize o esquema de tabela e o mapeamento de maneira a incluir as propriedades selecionadas.
   Data de início da recuperação do evento	Tempo Universal Coordenado (UTC)	A conexão de dados recupera eventos existentes dos Hubs de Eventos criados após a data de início da recuperação do evento. Somente eventos retidos pelo período de retenção dos Hubs de Eventos podem ser recuperados. Se a data de início da recuperação do evento não for especificada, a hora padrão será a hora em que a conexão de dados é criada.

9. Se o streaming estiver habilitado para o cluster, você poderá selecionar Ingestão de streaming. Se o streaming não estiver habilitado para o cluster, defina a latência de envio em lote de dados. Para Hubs de Eventos, o tempo de envio em lote recomendado é de 30 segundos.

   

10. Selecione o Formato de dados. Para dados formatados em CSV, ignore o primeiro registro para ignorar a linha de cabeçalho do arquivo. Para dados formatados em JSON, selecione Ignorar erros de formato de dados para ingerir os dados no formato JSON ou deixe desmarcado para ingerir os dados no formato multijson. Selecione os níveis aninhados para determinar a divisão de dados da coluna da tabela.

11. Se os dados exibidos na janela de pré-visualização não estiverem completos, talvez você precise de mais dados para criar uma tabela com todos os campos de dados necessários. Use os seguintes comandos para buscar novos dados do hub de eventos:

    • Descartar e buscar novos dados: descarta os dados apresentados e procura novos eventos.
    • Buscar mais dados: procura mais eventos além dos eventos já encontrados.

    Observação

    Para ver uma pré-visualização dos dados, o hub de eventos precisa enviar os eventos.

12. Selecione Avançar: Resumo.

13. Na janela Ingestão contínua do Hub de Eventos estabelecida, todas as etapas são marcadas com marcas de seleção verdes quando o estabelecimento é concluído com êxito.

Modelo de ARM

Pré-requisitos

• Uma assinatura do Azure. Criar uma conta gratuita do Azure.
• Um cluster e um banco de dados do Azure Data Explorer. Criar um cluster e um banco de dados.
• Uma tabela de destino. Criar uma tabela ou usar uma tabela existente.
• Um mapeamento de ingestão para a tabela.
• Um hub de eventos com dados para ingestão.

Modelo de ARM

O exemplo a seguir mostra um modelo do Azure Resource Manager para adicionar uma conexão de dados dos Hubs 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 Hubs 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."
            }
        },
        "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 event hub"
            }
        },
        "resourceGroup": {
            "type": "string",
            "defaultValue": "[resourceGroup().name]",
            "metadata": {
                "description": "Specifies the resourceGroup of the event hub"
            }
        },
        "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": "EventHub",
            "properties": {
                "managedIdentityResourceId": "[resourceId('Microsoft.Kusto/clusters', parameters('clusters_kustocluster_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')]"
            }
        }
    ]
}

Remover uma conexão de dados do hub de eventos

Obter dados

Remova a conexão de dados por meio do portal do Azure, conforme explicado na guia do portal.

Portal

Para remover a conexão do hub de eventos do portal do Azure, faça o seguinte:

1. Vá para o seu cluster. No menu à esquerda, selecione Bancos de dados. Em seguida, selecione o banco de dados que contém a tabela de destino.
2. No menu à esquerda, selecione Conexões de dados. Em seguida, marque a caixa de seleção ao lado da conexão de dados do hub de eventos relevante.
3. Na barra de menu superior, selecione Excluir.

Conteúdo relacionado

• Verifique a conexão com o aplicativo de mensagem de amostra do hub de eventos
• Consulta de dados na interface do usuário da Web