Share via

Conexão de dados dos Hubs de Eventos do Azure

  • Artigo

Os Hubs de Eventos do Azure são uma plataforma de streaming de Big Data e um serviço de ingestão de eventos. O Azure Data Explorer oferece a ingestão contínua dos hubs de eventos gerenciados pelo cliente.

O pipeline de ingestão dos Hubs de Eventos transfere eventos para o Azure Data Explorer em várias etapas. Primeiro você cria um hub de eventos no portal do Azure. Depois, você cria uma tabela de destino no Azure Data Explorer na qual os dados em um formato específico serão ingeridos usando as propriedades de ingestãoespecificadas. A conexão dos Hubs de Eventos precisa saber qual é o roteamento de evento. Os dados podem ser inseridos com as propriedades selecionadas de acordo com as propriedades do sistema de eventos. Crie uma conexão com os Hubs de Eventos para criar um hub de eventos e enviar eventos. Esse processo pode ser gerenciado por meio do portal do Azure, programaticamente com o C#, o Python ou o 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 do Azure Data Explorer

Cuidado

Se as permissões de identidade gerenciada forem removidas da fonte de dados, a conexão de dados será desabilitada e não poderá buscar dados da fonte de dados.

  • Conexão de dados baseada em chave: se uma identidade gerenciada não for especificada na conexão de dados, a conexão assumirá automaticamente o padrão de 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 gera a cadeia de conexão de recurso para o recurso especificado e a salva com segurança na conexão de dados. A cadeia de conexão é usada para buscar dados da fonte de dados.

Cuidado

Se houver rotação de chave, a conexão de dados será desabilitada e não poderá buscar dados da fonte de dados. Para corrigir o problema, atualize ou recrie a conexão de dados.

Formato de dados

  • Os dados são lidos no hub de eventos na forma de objetos EventData.

  • Confira Formatos com suporte.

    Observação

  • Os dados podem ser compactados usando o algoritmo de compactação GZip. Você pode especificar o Compression dinamicamente usando as Compression ou nas configurações de Conexão de Dados estáticos.

    Observação

    Não há suporte para compactação de dados em formatos compactados (como Avro, Parquet, ORC, ApacheAvro e W3CLOGFILE). Não há suporte para codificação personalizada e propriedades do sistema inseridas em dados compactados.

Propriedades dos Hubs de Eventos

O Azure Data Explorer dá suporte às seguintes propriedades dos Hubs de Eventos:

Observação

Não há suporte para a ingestão de propriedades personalizadas dos Hubs de Eventos, usadas para associar metadados a eventos. Se você precisar ingerir as propriedades personalizadas, envie-as no corpo dos dados do evento. Para obter mais informações, confira Ingerir propriedades personalizadas.

Propriedades da ingestão

As propriedades de ingestão informam ao processo de ingestão para onde os dados devem ser encaminhados e como eles devem ser processados. Você pode especificar as propriedades de ingestão da ingestão de eventos usando EventData.Properties. Defina as seguintes propriedades:

Observação

Os nomes de propriedade diferenciam maiúsculas de minúsculas.

Propriedade Descrição
Banco de dados 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.
Tabela O nome que diferencia maiúsculas de minúsculas da tabela de destino existente. Substitui o conjunto Table no painel Data Connection.
Formatar Formato dos dados. Substitui o conjunto Data format no painel Data Connection.
IngestionMappingReference Nome do mapeamento de ingestão existente a ser usado. Substitui o conjunto Column mapping no painel Data Connection.
Compactação Compactação de dados None (padrão) ou compactação GZip.
Codificação Codificação de dados, o padrão é UTF8. Pode ser qualquer uma das codificações com suporte do .NET.
Marcações Uma lista de marcas a serem associadas aos dados ingeridos, formatadas como uma cadeia de caracteres JSON. Há implicações de desempenho ao usar marcas.
RawHeaders Indica que a origem do evento é Kafka e Data Explorer do Azure deve usar a desserialização de matriz de bytes para ler outras propriedades de roteamento. Seu valor é ignorado.

Observação

Somente os eventos enfileirados após a criação da conexão de dados são ingeridos.

Roteamento de eventos

Ao criar uma conexão de dados com o cluster, você pode especificar 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 definindo as propriedades de dados de evento mencionadas acima.

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. Você pode fazer 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 especificar um banco de dados alternativo, defina a propriedade de ingestãoDatabase.

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

Para especificar uma tabela alternativa para cada evento, defina as propriedades de ingestãoTable, Format, Compression e de mapeamento. A conexão roteará os dados ingeridos dinamicamente conforme especificado em EventData.Properties, substituindo as propriedades estáticas para esse evento.

O exemplo a seguir mostra como definir os detalhes do hub de eventos e enviar dados de métrica de clima para o banco de dados alternativo (MetricsDB) e a tabela (WeatherMetrics). Os dados estão no formato JSON e mapping1 está predefinido na tabela WeatherMetrics.

// This sample uses Azure.Messaging.EventHubs which is a .Net Framework library.
await using var producerClient = new EventHubProducerClient("<eventHubConnectionString>");
// Create the event and add optional "dynamic routing" properties
var eventData = new EventData(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(
    new { Timestamp = DateTime.UtcNow, MetricName = "Temperature", Value = 32 }
)));
eventData.Properties.Add("Database", "MetricsDB");
eventData.Properties.Add("Table", "WeatherMetrics");
eventData.Properties.Add("Format", "json");
eventData.Properties.Add("IngestionMappingReference", "mapping1");
eventData.Properties.Add("Tags", "['myDataTag']");
var events = new[] { eventData };
// Send events
await producerClient.SendAsync(events);

Mapeamento de propriedades do sistema de eventos

As propriedades do sistema armazenam propriedades que são definidas pelo Hubs de Eventos, no momento em que o evento é colocado na fila. A conexão de dados com o hub de eventos pode inserir um conjunto selecionado de propriedades do sistema nos dados ingeridos em uma tabela com base em um determinado mapeamento.

Observação

  • Há suporte para a inserção de propriedades do sistema para formatos JSON e tabular (ou seja, JSON, MultiJSON, CSV, TSV, PSV, SCsv, SOHsv, TSVE).
  • Ainda que você use um formato sem suporte (ou seja, TXT ou formatos compactados como Parquet, Avro etc.), os dados serão ingeridos, mas as propriedades serão ignoradas.
  • Não há suporte para a inserção de propriedades do sistema quando uma compactação das mensagens do Hub de Eventos está definida. Nesses cenários, um erro apropriado será emitido e os dados não serão ingeridos.
  • Para dados tabulares, as propriedades do sistema têm suporte apenas para mensagens de evento de registro único.
  • Para dados JSON, as propriedades do sistema também são compatíveis com mensagens de evento de vários registros. Nesses casos, as propriedades do sistema são adicionadas somente ao primeiro registro da mensagem de evento.
  • Para CSV mapeamento, as propriedades são adicionadas no início do registro na ordem listada na criação da conexão de dados. Não confie na ordem dessas propriedades, pois elas podem ser alteradas no futuro.
  • Para mapeamento de JSON, as propriedades são adicionadas de acordo com os nomes de propriedade na tabela JSON.

O serviço dos Hubs de Eventos expõe as seguintes propriedades do sistema:

Propriedade Tipo de Dados Descrição
x-opt-enqueued-time datetime Hora UTC em que o evento foi colocado na fila
x-opt-sequence-number long O número de sequência lógica do evento no fluxo de partição do hub de eventos
x-opt-offset string O deslocamento do evento em relação ao fluxo da partição do hub de eventos. O identificador de deslocamento é exclusivo em uma partição do fluxo do hub de eventos
x-opt-publisher string O nome do editor, se a mensagem foi enviada a um ponto de extremidade de editor
x-opt-partition-key string A chave da partição correspondente que armazenou o evento

Ao trabalhar com hubs de eventos do IoT Central, você também pode inserir as propriedades do sistema do Hub IoT no conteúdo. Para ver a lista completa, confira Propriedades do sistema do Hub IoT.

Se você selecionou Propriedades do sistema de eventos na seção Fonte de dados da tabela, inclua as propriedades no esquema e no mapeamento da tabela.

Exemplos de mapeamento de esquema

Exemplo de mapeamento de esquema

Se os dados incluírem três colunas (Timespan, Metric e Value) e as propriedades que você incluir forem x-opt-enqueued-time e x-opt-offset, crie ou altere o esquema de tabela usando este comando:

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, EventHubEnqueuedTime:datetime, EventHubOffset:string)

Exemplo de mapeamento de CSV

Execute os comandos a seguir para adicionar dados ao início do registro. Observe os valores ordinais.

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "Timespan", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "EventHubEnqueuedTime", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "EventHubOffset", "Properties":{"Ordinal":"1"}}'
    ']'

Exemplo de mapeamento JSON

Os dados são adicionados usando o mapeamento de propriedades do sistema. Execute estes comandos:

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "Timespan", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.value"}},'
    '    { "column" : "EventHubEnqueuedTime", "Properties":{"Path":"$.x-opt-enqueued-time"}},'
    '    { "column" : "EventHubOffset", "Properties":{"Path":"$.x-opt-offset"}}'
    ']'

Mapeamento de esquema para arquivos Avro de Captura do Hub de Eventos

Uma forma de consumir dados do Hub de Eventos é capturar eventos por meio de Hubs de Eventos do Azure no Armazenamento de Blobs do Azure ou no Azure Data Lake Storage. Você pode então ingerir os arquivos de captura conforme eles são gravados usando uma Conexão de Dados da Grade de Eventos no Azure Data Explorer.

O esquema dos arquivos de captura é diferente do esquema do evento original enviado ao Hub de Eventos. Você deve projetar o esquema da tabela de destino com essa diferença em mente. Especificamente, o conteúdo do evento é representado no arquivo de captura como uma matriz de bytes, e essa matriz não é decodificada automaticamente pela conexão de dados do Azure Data Explorer da Grade de Eventos. Para obter informações mais específicas sobre o esquema de arquivos para dados de captura do Avro do Hub de Eventos, confira Explorar arquivos Avro capturados em Hubs de Eventos do Azure.

Para decodificar corretamente o conteúdo do evento:

  1. Mapeie o campo Body do evento capturado em uma coluna de tipo dynamic na tabela de destino.
  2. Aplique uma política de atualização que converte a matriz de bytes em uma cadeia de caracteres legível usando a função unicode_codepoints_to_string( ).

Ingerir propriedades personalizadas

Ao ingerir eventos dos Hubs de Eventos, os dados são retirados da seção body do objeto de dados do evento. No entanto, as propriedades personalizadas dos Hubs de Eventos são definidas na seção properties do objeto e não são ingeridas. Para ingerir as propriedades do cliente, você precisa inseri-las nos dados na seção body do objeto.

O exemplo a seguir compara o objeto de dados de eventos que contém a propriedade personalizada customProperty, conforme definido pelos Hubs de Eventos (à esquerda), com a propriedade inserida necessária para ingestão (direita).

{
"body":{
"value": 42
},
"properties":{
"customProperty": "123456789"
}
}

{
"body":{
"value": 42,
"customProperty": "123456789"
}
}

Você pode usar um dos seguintes métodos para inserir propriedades personalizadas nos dados na seção body do objeto de dados de evento:

Conexão de dados do Hub de Eventos entre regiões

Para obter o melhor desempenho, crie todos os recursos a seguir na mesma região que o cluster. Se não houver outra alternativa, considere usar as camadas Premium ou Hub de Eventos Dedicado . A comparação de camadas do Hub de Eventos pode ser encontrada aqui.

Criar um hub de eventos

Crie um hub de eventos, caso você ainda não tenha nenhum. A conexão com o hub de eventos pode ser gerenciada usando o portal do Azure, programaticamente com C# ou Python ou por meio do modelo do Azure Resource Manager.

Observação

  • A capacidade de adicionar partições dinamicamente após a criação de um hub de eventos só está disponível com as camadas Premium e Dedicado dos Hubs de Eventos. Considere a escala de longo prazo ao definir a contagem de partições.
  • O grupo de consumidores precisa ser exclusivo por consumidor. Crie um grupo de consumidores dedicado para a conexão do Azure Data Explorer.

Enviar eventos

Confira o aplicativo de exemplo que gera dados e os envia para um hub de eventos.

Para ver um exemplo de como gerar dados de exemplo, confira Ingestão de dados do hub de eventos no Azure Data Explorer

Configurar a solução de recuperação de desastre geográfico

O hub de eventos oferece uma solução de Recuperação de desastre geográfico. O Azure Data Explorer não dá suporte a namespaces Alias de hub de eventos. Para implementar a recuperação de desastre geográfico em sua solução, crie duas conexões de dados de hub de eventos: uma para o namespace primário e outra para o namespace secundário. O Azure Data Explorer escutará as duas conexões de hub de eventos.

Observação

É responsabilidade do usuário implementar um failover do namespace primário para o namespace secundário.

Conteúdo relacionado