Partilhar via

Conexão de dados dos Hubs de Eventos do Azure

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 ingestão contínua de Hubs de Eventos gerenciados pelo cliente.

O pipeline de ingestão de 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 incorporados com propriedades selecionadas de acordo com as propriedades do sistema de eventos. Crie uma conexão com 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 C# ou Python ou com o modelo do Azure Resource Manager.

Para obter informações gerais sobre a ingestão de dados no Azure Data Explorer, consulte 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. Ele fornece controle total sobre a capacidade de buscar dados de uma fonte de dados. A configuração de uma conexão de dados usando identidade gerenciada requer as seguintes etapas:

    1. Adicione uma identidade gerenciada ao cluster.
    2. Conceda 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 Recetor 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 de identidade gerenciada para buscar dados.

    Atenção

    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 poderá buscar 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, a conexão assumirá automaticamente como padrão 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 recurso para o recurso especificado e a salva com segurança. A cadeia de conexão é usada para buscar dados da fonte de dados.

    Atenção

    Se a chave for girada, a conexão de dados não funcionará mais e não poderá buscar dados da fonte de dados. Para corrigir o problema, atualize ou recrie a conexão de dados.

Formato dos dados

Observação

  • A ingestão de Hubs de Eventos não suporta o formato RAW.
  • Não há suporte para o Registro de Esquema dos Hubs de Eventos do Azure e o Avro sem esquema.
  • Os dados podem ser compactados usando o algoritmo de gzip compressão. Você pode especificar Compression dinamicamente usando propriedades de ingestão ou nas configurações estáticas de Conexão de Dados.
  • A compactação de dados não é suportada para formatos binários (Avro, ApacheAvro, Parquet, ORC e W3CLOGFILE).
  • A codificação personalizada e as propriedades do sistema incorporado não são suportadas 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 de Hubs de Eventos:

Observação

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

Propriedades de ingestão

As propriedades de ingestão instruem o processo de ingestão, para onde encaminhar os dados e como processá-los. Você pode especificar as propriedades de ingestão dos eventos usando o EventData.Properties. Você pode definir as seguintes propriedades:

Observação

Os nomes de propriedade são sensíveis a maiúsculas e minúsculas.

Propriedade Descrição
Base de dados O nome do banco de dados de destino com distinção entre maiúsculas e minúsculas. Por padrão, os dados são ingeridos no banco de dados de destino associado à conexão de dados. Use essa propriedade para substituir o banco de dados padrão e enviar dados para um banco de dados diferente. Para fazer isso, você deve primeiro configurar a conexão como uma conexão de vários bancos de dados.
Tabela O nome que distingue maiúsculas de minúsculas da tabela de destino existente. Substitui o Table definido no painel Data Connection.
Formato Formato de dados. Substitui o Data format definido no painel Data Connection.
ReferênciaDeMapeamentoDeIngestão Nome do mapeamento de ingestão existente a ser usado. Substitui o Column mapping definido no painel Data Connection.
Compressã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 suportadas pelo .NET.
Etiquetas Uma lista de tags para associar aos dados ingeridos, formatada como uma string de matriz JSON. Há implicações de desempenho ao usar tags.
RawHeaders Indica que a fonte do evento é Kafka e o Azure Data Explorer deve usar a desserialização da matriz de bytes para ler outras propriedades de roteamento. O valor é ignorado.

Observação

Somente os eventos enfileirados após a criação da conexão de dados são ingeridos, a menos que seja fornecida uma data de início de obtenção personalizada. Em qualquer caso, o período de retrospetiva 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 onde enviar os dados ingeridos. O roteamento padrão é para a tabela de destino especificada na cadeia de conexão associada ao banco de dados de destino. O roteamento padrão para seus 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 das 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 lidos 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.

Encaminhar dados de eventos 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ê deve 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 ARM. O utilizador, grupo, principal de serviço ou identidade gerida usada para permitir o roteamento de base de dados deve ter, pelo menos, 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ãodo banco de dados.

Advertência

Especificar um banco de dados alternativo sem definir a conexão como uma conexão de dados de vários bancos de dados fará com que a ingestão falhe.

Encaminhar dados de eventos para uma tabela alternativa

Para especificar uma tabela alternativa para cada evento, defina as propriedades de ingestão, de tabela, formato e compactação e mapeamento. A conexão roteia dinamicamente os dados ingeridos conforme especificado em EventData.Properties, substituindo as propriedades estáticas desse evento.

O exemplo a seguir mostra como definir os detalhes do hub de eventos e enviar dados de métricas meteorológicas para banco de dados alternativo (MetricsDB) e tabela (WeatherMetrics). Os dados estão no formato JSON e o mapeamento1 é 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 Hubs de Eventos

As propriedades do sistema são campos definidos pelo serviço Event Hubs, no momento em que o evento é adicionado à fila. A conexão de dados dos Hubs de Eventos do Azure Data Explorer pode incorporar um conjunto predefinido de propriedades do sistema nos dados ingeridos em uma tabela com base em um determinado mapeamento.

Observação

  • A incorporação de propriedades do sistema é suportada para formatos json e tabular (ou seja, JSON, MultiJSON, CSV, TSV, PSV, SCsv, SOHsv, TSVE).
  • Ao usar um formato não suportado (i.e. TXT ou formatos compactados como Parquet, Avro etc.) os dados ainda serão ingeridos, mas as propriedades serão ignoradas.
  • Não há suporte para a incorporação de propriedades do sistema quando uma compactação de mensagens do Hub de Eventos é definida. Nesses cenários, um erro apropriado será emitido e os dados não serão ingeridos.
  • Para dados tabulares, as propriedades do sistema são suportadas apenas para mensagens de eventos com um único registo.
  • Para dados json, as propriedades do sistema também são suportadas para mensagens de eventos 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 isso pode mudar no futuro.
  • Para JSON mapeamento, as propriedades são adicionadas de acordo com os nomes das propriedades na tabela Propriedades do Sistema.

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

Propriedade Tipo de dados Descrição
x-opt-tempo-de-enfileiramento datetime Hora UTC em que foi enfileirado o evento
x-opt-seqüência-número long O número de sequência lógica do evento dentro do fluxo de partição do hub de eventos
x-opt-deslocamento string O deslocamento do evento do fluxo de partição do hub de eventos. O identificador de deslocamento é exclusivo dentro de uma partição do fluxo do hub de eventos
x-opt-publicador string O nome do editor, se a mensagem tiver sido enviada para um destino do editor
chave de partição x-opt string A chave de partição da partição correspondente que armazenou o evento

Ao trabalhar com hubs de eventos do IoT Central , você também pode incorporar as propriedades do sistema do Hub IoT na carga útil. Para obter a lista completa, consulte Propriedades do sistema do Hub IoT.

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

Exemplos de mapeamento de esquema

Exemplo de mapeamento de esquema de tabela

Se os dados incluírem três colunas (TimeStamp, , e MetricName) e as propriedades incluídas forem Value e x-opt-enqueued-time, crie ou altere o esquema da tabela x-opt-offsetusando este comando:

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

Exemplo de mapeamento CSV

Execute os seguintes comandos 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 do Event Hubs Capture

Uma maneira de consumir dados do Azure Event Hubs é capturar eventos através dos Hubs de Eventos da Azure no Azure Blob Storage ou no Azure Data Lake Storage. Em seguida, pode ingerir os arquivos de captura à medida que são gravados usando uma Conexão de Dados da Grelha de Eventos no Azure Data Explorer.

O esquema dos arquivos de captura é diferente do esquema do evento original enviado aos Hubs de Eventos. Você deve projetar o esquema da tabela de destino com essa diferença em mente. Especificamente, a carga útil do evento é representada como uma matriz de bytes no ficheiro de captura, e essa matriz não é automaticamente decodificada pela conexão de dados da Grade de Eventos do Azure Data Explorer. Para obter mais informações sobre o esquema de arquivo para dados de captura Avro de Hubs de Eventos, consulte Explorando arquivos Avro capturados nos Hubs de Eventos do Azure.

Para decodificar corretamente a carga útil do evento:

  1. Mapeie o Body campo do evento capturado para uma coluna do tipo dynamic na tabela de destino.
  2. Aplique uma política de atualização que converta 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 de Hubs de Eventos, os dados são extraídos da body seção do objeto de dados de evento. No entanto, as properties dos Hubs de Eventos são definidas na seção do objeto e não são ingeridas. Para ingerir propriedades do cliente, você deve incorporá-las aos dados na body seção do objeto.

O exemplo a seguir compara o objeto de dados eventos que contém a propriedade customProperty personalizada conforme definido pelo Event Hubs (esquerda) com a propriedade incorporada 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 incorporar propriedades personalizadas nos dados na body seção do objeto de dados de evento:

Criar Hubs de Eventos

Se você ainda não tiver um, crie um hub de eventos. A ligação ao hub de eventos pode ser gerida através do portal do Azure, programaticamente com C# ou Python ou com o modelo 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 os níveis Premium e Dedicado dos Hubs de Eventos. Considere a escala de longo prazo ao definir a contagem de partições.
  • O grupo de consumidores deve ser único por consumidor. Crie um grupo de consumidores dedicado para cada conexão de dados do Azure Data Explorer.

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

Para obter o melhor desempenho, crie o hub de eventos na mesma região do 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 de Hubs de Eventos do Azure.

Enviar eventos

Veja 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 irregular 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 desastres geográficos

O hub de eventos oferece uma solução de recuperação de desastres geográficos . O Azure Data Explorer não oferece suporte a Alias namespaces de hub de eventos. Para implementar a recuperação de desastres geográficos em sua solução, crie duas conexões de dados do 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