Compartilhar 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. Em seguida, crie uma tabela de destino no Azure Data Explorer na qual os dados em um formato específico são ingeridos usando as propriedades de ingestão fornecidas. A conexão dos Hubs de Eventos precisa estar ciente do roteamento de eventos. 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.

Opções de autenticação de conexão de dados do Azure Data Explorer

  • 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. Ela fornece controle total sobre a capacidade de buscar dados de uma fonte de dados. A configuração de uma conexão de dados usando a identidade gerenciada requer as seguintes etapas:

    1. Adicionar uma identidade gerenciada ao seu cluster.
    2. Conceder permissões à identidade gerenciada na fonte de dados. Para buscar dados dos Hubs de Eventos do Azure, a identidade gerenciada deve ter permissões de Receptor de Dados dos Hubs de Eventos do Azure.
    3. Defina uma política de identidade gerenciada nos bancos de dados de destino.
    4. Crie uma conexão de dados usando a autenticação da identidade gerenciada para buscar os dados.

    Cuidado

    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 será possível obter os dados da fonte de dados.

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

    Cuidado

    Se a chave for girada, a conexão de dados não funcionará mais e não será possível obter os dados da fonte de dados. Para corrigir o problema, atualize ou recrie a conexão de dados.

Formato de dados

Observação

  • A ingestão dos Hubs de Eventos não dá suporte para o formato RAW.
  • Não há suporte para o registro de esquema dos Hubs de Eventos do Azure e para o Avro sem esquema.
  • Os dados podem ser compactados usando o algoritmo de compactação gzip. Você pode especificar o Compression dinamicamente usando as propriedades de ingestão ou nas configurações de Conexão de Dados estáticos.
  • Não há suporte para compactação de dados em formatos compactados (como Avro, ApacheAvro, Parquet, ORC e W3CLOGFILE).
  • Não há suporte para codificação personalizada e propriedades do sistema inseridas com formatos binários e dados compactados.
  • Ao usar formatos binários (Avro, ApacheAvro, Parquet, ORC e W3CLOGFILE) e mapeamentos de ingestão, a ordem dos campos na definição de mapeamento de ingestão deve corresponder à ordem das colunas correspondentes na tabela.

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
Backup de 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 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 é o Kafka e que o Azure Data Explorer deve usar a desserialização da matriz de bytes para fazer a leitura de 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, a menos que uma data de início de recuperação personalizada seja fornecida. Em qualquer caso, o período de lookback não pode exceder o período de retenção real do Hub de Eventos.

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 opções alternativas de roteamento e processamento para seus dados definindo uma ou mais propriedades de dados de evento mencionadas no parágrafo anterior.

Observação

A conexão de dados dos Hubs de Eventos tentará processar todos os eventos que lê do Hub de Eventos, e todos os eventos que não puderem processar por qualquer motivo serão relatados como uma falha de ingestão. Leia sobre como monitorar a ingestão do Azure Data Explorer aqui.

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. Esse recurso pode ser habilitado no portal do Azure Portal do Azure, com SDKs de gerenciamento C# ou Python ou com 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 Banco de dados ingestão.

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ão Table, 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 dos Hubs de Eventos

As propriedades do sistema são campos definidos pelo serviço de Hubs de Eventos, no momento em que o evento é enfileirado. A conexão de dados dos Hubs de Eventos do Azuer Data Explorer pode inserir um conjunto predefinido 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 o mapeamento CSV, 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 ela pode alterar no futuro.
  • Para mapeamento de JSON, as propriedades são adicionadas de acordo com os nomes de propriedade na tabela Propriedades do sistema.

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 (TimeStamp, MetricName 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, MetricName: 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" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "MetricName", "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" : "TimeStamp", "Properties":{"Path":"$.TimeStamp"}},'
    '    { "column" : "MetricName", "Properties":{"Path":"$.MetricName"}},'
    '    { "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 dos Hubs de Eventos

Uma forma de consumir dados dos Hubs 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 mais informações sobre o esquema de arquivo para dados de captura Avro dos Hubs de Eventos, consulte Explorando arquivos Avro capturados nos 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:

Criar Hubs 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.

Conexão de dados dos Hubs de Eventos entre regiões

Para obter o melhor desempenho, crie o hub de eventos na mesma região que o cluster. Se isso não for possível, considere usar as camadas Premium ou Hubs de Eventos Dedicados . Para obter uma comparação de camadas, consulte Comparar camadas dos Hubs de Eventos do Azure.

Enviar eventos

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

Observação

Para habilitar o processamento eficiente de eventos dos Hubs de Eventos para o Azure Data Explorer, evite uma distribuição desequilibrada de eventos entre partições. O mapeamento desigual pode causar uma alta latência de descoberta. Para obter mais informações, consulte Mapeamento de eventos para partições.

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 escuta ambas as conexões do hub de eventos.

Observação

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

Conteúdo relacionado