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 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

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

Propriedades dos Hubs de Eventos

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

• Um conjunto fechado de propriedades de ingestão, que ajuda a rotear o evento para a tabela relevante.
• Um conjunto fechado de propriedades do sistema de eventos, que pode ser inserido nos dados com base em um determinado mapeamento.

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:

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.

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.

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.

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

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:

• Nos Hubs de Eventos, ao criar o objeto de dados de evento, insira as propriedades personalizadas como parte dos dados na seção body do objeto.
• Use o Azure Stream Analytics para processar eventos do hub de eventos e inserir as propriedades personalizadas nos dados do evento. No Azure Stream Analytics, você pode ingerir os dados nativamente usando o conector de saída do Azure Data Explorer ou roteá-los para outro hub de eventos e de lá para o cluster.
• Use o Azure Functions para adicionar as propriedades personalizadas e ingerir os dados.

Conexão de dados dos Hubs 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 Dedicado dos Hubs de Eventos. A comparação das camadas dos Hubs de Eventos pode ser encontrada aqui.

Criar um Hub de Evento

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.

Enviar eventos

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

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.

Conteúdo relacionado

• Ingerir dados do hub de eventos no Azure Data Explorer
• Criar uma conexão de dados de hub de eventos com o Azure Data Explorer usando C#
• Criar uma conexão de dados de hub de eventos com o Azure Data Explorer usando Python
• Criar uma conexão de dados de hub de eventos com o Azure Data Explorer usando um modelo do Azure Resource Manager
• Gerenciar as conexões de dados dos Hubs de Eventos em seu cluster gratuito
• Ingerir e consultar logs do Azure Monitor com o Azure Data Explorer