Partilhar via

Ligação de dados dos Hubs de Eventos do Azure

  • Artigo

Hubs de Eventos do Azure é uma plataforma de transmissão em fluxo de macrodados e um serviço de ingestão de eventos. O Azure Data Explorer oferece ingestão contínua de Hubs de Eventos geridos pelo cliente.

O pipeline de ingestão de Hubs de Eventos transfere eventos para o Azure Data Explorer em vários passos. Primeiro, vai criar um hub de eventos no portal do Azure. Em seguida, irá criar uma tabela de destino no Azure Data Explorer em que os dados num formato específico serão ingeridos com as propriedades de ingestão especificadas. A ligação dos Hubs de Eventos tem de conhecer o encaminhamento de eventos. Os dados podem ser incorporados com propriedades selecionadas de acordo com as propriedades do sistema de eventos. Crie uma ligação aos Hubs de Eventos para criar um hub de eventos e enviar eventos. Este processo pode ser gerido através do portal do Azure, programaticamente com C# ou Python, ou com o modelo Resource Manager do Azure.

Para obter informações gerais sobre a ingestão de dados no Azure Data Explorer, veja Descrição geral da ingestão de dados do Azure Data Explorer.

Mecanismos de autenticação de ligação de dados do Azure Data Explorer

Atenção

Se as permissões de identidade gerida forem removidas da origem de dados, a ligação de dados será desativada e não conseguirá obter dados da origem de dados.

  • Ligação de dados baseada em chave: se uma identidade gerida não for especificada na ligação de dados, a ligação será automaticamente predefinida para autenticação baseada em chaves. As ligações baseadas em chaves obtêm dados com um recurso cadeia de ligação, como o Hubs de Eventos do Azure cadeia de ligação. O Azure Data Explorer gera o recurso cadeia de ligação para o recurso especificado e guarda-o em segurança na ligação de dados. O cadeia de ligação é utilizado para obter dados da origem de dados.

Atenção

Se a chave for rodada, a ligação de dados será desativada e não conseguirá obter dados da origem de dados. Para corrigir o problema, atualize ou recrie a ligação de dados.

Formato de dados

  • Os dados são lidos a partir do hub de eventos na forma de objetos EventData .

  • Veja os formatos suportados.

    Nota

  • Os dados podem ser comprimidos com o GZip algoritmo de compressão. Pode especificar dinamicamente Compressionatravés de propriedades de ingestão ou nas definições estáticas da Ligação de Dados.

    Nota

    A compressão de dados não é suportada para formatos comprimidos (Avro, Parquet, ORC, ApacheAvro e W3CLOGFILE). A codificação personalizada e as propriedades do sistema incorporadas não são suportadas em dados comprimidos.

Propriedades dos Hubs de Eventos

O Azure Data Explorer suporta as seguintes propriedades dos Hubs de Eventos:

Nota

A ingestão de propriedades personalizadas dos Hubs de Eventos, utilizadas para associar metadados a eventos, não é suportada. Se precisar de ingerir propriedades personalizadas, envie-as no corpo dos dados do evento. Para obter mais informações, veja Ingerir propriedades personalizadas.

Propriedades de ingestão

As propriedades de ingestão instruem o processo de ingestão, onde encaminhar os dados e como processá-lo. Pode especificar as propriedades de ingestão da ingestão de eventos com EventData.Properties. Pode definir as seguintes propriedades:

Nota

Os nomes das propriedades são sensíveis às maiúsculas e minúsculas.

Propriedade Descrição
Base de Dados O nome sensível às maiúsculas e minúsculas da base de dados de destino. Por predefinição, os dados são ingeridos na base de dados de destino associada à ligação de dados. Utilize esta propriedade para substituir a base de dados predefinida e enviar dados para uma base de dados diferente. Para tal, primeiro tem de configurar a ligação como uma ligação de várias bases de dados.
Tabela O nome sensível às maiúsculas e minúsculas da tabela de destino existente. Substitui o Table conjunto no Data Connection painel.
Formato Formato de dados. Substitui o Data format conjunto no Data Connection painel.
IngestionMappingReference Nome do mapeamento de ingestão existente a utilizar. Substitui o Column mapping conjunto no Data Connection painel.
Compressão Compressão de dados, None (predefinição) ou GZip compressão.
Encoding Codificação de dados, a predefinição é UTF8. Pode ser qualquer uma das codificações suportadas pelo .NET.
Etiquetas Uma lista de etiquetas a associar aos dados ingeridos, formatadas como uma cadeia de matriz JSON. Existem implicações de desempenho ao utilizar etiquetas.
RawHeaders Indica que a origem de eventos é o Kafka e o Azure Data Explorer tem de utilizar a desserialização da matriz de bytes para ler outras propriedades de encaminhamento. O valor é ignorado.

Nota

Apenas os eventos colocados em fila após criar a ligação de dados são ingeridos.

Encaminhamento de eventos

Quando cria uma ligação de dados ao cluster, pode especificar o encaminhamento para onde enviar dados ingeridos. O encaminhamento predefinido é para a tabela de destino especificada na cadeia de ligação que está associada à base de dados de destino. O encaminhamento predefinido para os seus dados também é referido como encaminhamento estático. Pode especificar um encaminhamento alternativo para os seus dados ao definir as propriedades de dados do evento mencionadas acima.

Encaminhar dados de eventos para uma base de dados alternativa

Por predefinição, o encaminhamento de dados para uma base de dados alternativa está desativado. Para enviar os dados para uma base de dados diferente, primeiro tem de definir a ligação como uma ligação de várias bases de dados. Pode fazê-lo no portal do Azure portal do Azure, C#, Python ou um modelo do ARM. O utilizador, grupo, principal de serviço ou identidade gerida utilizada para permitir o encaminhamento de bases de dados tem, pelo menos, de ter a função de contribuidor e as permissões de escrita no cluster.

Para especificar uma base de dados alternativa, defina a propriedade Ingestão debases de dados.

Aviso

Especificar uma base de dados alternativa sem definir a ligação como uma ligação de dados de várias bases 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 tabela, Formatação, Compressão e ingestão de mapeamento. A ligação encaminha dinamicamente os dados ingeridos conforme especificado em EventData.Properties, substituindo as propriedades estáticas deste evento.

O exemplo seguinte mostra-lhe como definir os detalhes do hub de eventos e enviar dados de métricas meteorológicas para uma base de dados alternativa (MetricsDB) e uma tabela (WeatherMetrics). Os dados estão no formato JSON e o mapeamento1 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 serviço Hubs de Eventos, no momento em que o evento é colocado em fila. A ligação de dados ao hub de eventos pode incorporar um conjunto selecionado de propriedades do sistema nos dados ingeridos numa tabela com base num determinado mapeamento.

Nota

  • A incorporação de propriedades do sistema é suportada para formatos json e tabulares (ou sejaJSON, , MultiJSON, CSV, TSV, PSV, SCsv, SOHsv). TSVE
  • Ao utilizar um formato não suportado (i.e. TXT ou formatos comprimidos como Parquet, Avro etc.), os dados continuarão a ser ingeridos, mas as propriedades serão ignoradas.
  • A incorporação de propriedades do sistema não é suportada quando é definida uma compressão de mensagens do Hub de Eventos. Nestes cenários, será emitido um erro adequado e os dados não serão ingeridos.
  • Para dados tabulares, as propriedades do sistema são suportadas apenas para mensagens de evento de registo único.
  • Para dados json, as propriedades do sistema também são suportadas para mensagens de eventos de vários registos. Nestes casos, as propriedades do sistema são adicionadas apenas ao primeiro registo da mensagem de evento.
  • Para CSV mapeamento, as propriedades são adicionadas no início do registo pela ordem indicada na criação da ligação de dados. Não dependa da ordem destas propriedades, uma vez que poderá mudar no futuro.
  • Para JSON mapeamento, as propriedades são adicionadas de acordo com os nomes de propriedades na tabela De propriedades do sistema .

O serviço 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 em fila
x-opt-sequence-number long O número de sequência lógica do evento no fluxo de partições do hub de eventos
x-opt-offset string O desvio do evento do fluxo de partições do hub de eventos. O identificador de deslocamento é exclusivo numa partição do fluxo do hub de eventos
x opt-publisher string O nome do publicador, se a mensagem tiver sido enviada para um ponto final do publicador
x-opt-partition-key string A chave de partição da partição correspondente que armazenou o evento

Quando trabalha com os hubs de eventos do IoT Central, também pode incorporar Hub IoT propriedades do sistema no payload. Para obter a lista completa, veja Hub IoT propriedades do sistema.

Se tiver selecionado propriedades do sistema de eventos na secção Origem de Dados da tabela, tem de incluir as propriedades no esquema e mapeamento da tabela.

Exemplos de mapeamento de esquemas

Exemplo de mapeamento de esquema de tabela

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

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

Exemplo de mapeamento CSV

Execute os seguintes comandos para adicionar dados ao início do registo. Anote 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 através do 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 esquemas para ficheiros Avro de Captura do Hub de Eventos

Uma forma de consumir dados do Hub de Eventos é capturar eventos através de Hubs de Eventos do Azure em Armazenamento de Blobs do Azure ou Azure Data Lake Storage. Em seguida, pode ingerir os ficheiros de captura à medida que são escritos com uma Ligação de Dados do Event Grid no Azure Data Explorer.

O esquema dos ficheiros de captura é diferente do esquema do evento original enviado para o Hub de Eventos. Deve estruturar o esquema da tabela de destino tendo esta diferença em mente. Especificamente, o payload de eventos é representado no ficheiro de captura como uma matriz de bytes e esta matriz não é automaticamente descodificada pela ligação de dados Data Explorer do Azure do Event Grid. Para obter informações mais específicas sobre o esquema de ficheiros para dados de captura avro do Hub de Eventos, veja Explorar ficheiros Avro capturados no Hubs de Eventos do Azure.

Para descodificar corretamente o payload 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 numa cadeia legível com a função unicode_codepoints_to_string( ).

Ingerir propriedades personalizadas

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

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

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

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

Pode utilizar um dos seguintes métodos para incorporar propriedades personalizadas nos dados na body secção do objeto de dados do evento:

Ligação de dados do Hub de Eventos entre regiões

Para um melhor desempenho, crie todos os seguintes recursos na mesma região que o cluster. Se não existir outra alternativa, considere utilizar os escalões Premium ou Dedicated Event Hub. A comparação dos escalões do Hub de Eventos pode ser encontrada aqui.

Criar um hub de eventos

Se 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, através de programação com C# ou Python, ou com o modelo Resource Manager do Azure.

Nota

  • A capacidade de adicionar partições dinamicamente após a criação de um hub de eventos só está disponível com os Hubs de Eventos Premium e os Escalões Dedicados. Considere a escala a longo prazo ao definir a contagem de partições.
  • O grupo de consumidores tem de ser exclusivo por consumidor. Crie um grupo de consumidores dedicado ao Azure Data Explorer ligação.

Enviar eventos

Veja a aplicação de exemplo que gera dados e os envia para um hub de eventos.

Para obter um exemplo de como gerar dados de exemplo, veja Ingerir dados do hub de eventos para o Azure Data Explorer

Configurar a solução de recuperação após desastre geográfica

O hub de eventos oferece uma solução de recuperação após desastre geográfica. O Azure Data Explorer não suporta espaços Alias de nomes do hub de eventos. Para implementar a Recuperação após desastre geográfica na sua solução, crie duas ligações de dados do hub de eventos: uma para o espaço de nomes principal e outra para o espaço de nomes secundário. O Azure Data Explorer irá escutar ambas as ligações do hub de eventos.

Nota

É da responsabilidade do utilizador implementar uma ativação pós-falha do espaço de nomes primário para o espaço de nomes secundário.

Conteúdo relacionado