Conexión de datos de Azure Event Hubs

  • Artículo

Azure Event Hubs es una plataforma de streaming de macrodatos y un servicio de ingesta de eventos. Azure Data Explorer ofrece ingesta de datos continua desde centros de eventos administrados por el cliente.

La canalización de ingesta de Event Hubs transfiere los eventos a Azure Data Explorer en varios pasos. En primer lugar, se crea un centro de eventos en Azure Portal. A continuación, se crea una tabla de destino de Azure Data Explorer en la que se realizará la ingesta de datos en un formato determinado mediante el uso de las propiedades de la ingesta especificadas. La conexión de Event Hubs debe conocer el enrutamiento de eventos. Los datos se insertan con las propiedades seleccionadas según las propiedades del sistema de eventos. Cree una conexión a Event Hubs para crear un centro de eventos y enviar eventos. Este proceso se puede administrar desde Azure Portal, mediante programación con C# o Python o con una plantilla de Azure Resource Manager.

Para obtener información general sobre la ingesta de datos en Azure Data Explorer, consulte Introducción a la ingesta de datos de Azure Data Explorer.

Mecanismos de autenticación de conexión de datos de Azure Data Explorer

Precaución

Si los permisos de identidad administrada se quitan del origen de datos, la conexión de datos se deshabilita y no puede capturar datos del origen de datos.

  • Conexión de datos basada en claves: si no se especifica una identidad administrada en la conexión de datos, la conexión establecerá automáticamente como valor predeterminado la autenticación basada en claves. Las conexiones basadas en claves capturan datos mediante una cadena de conexión de recursos, como la cadena de conexión Azure Event Hubs. Azure Data Explorer genera la cadena de conexión de recursos para el recurso especificado y la guarda de forma segura en la conexión de datos. A continuación, la cadena de conexión se usa para capturar datos del origen de datos.

Precaución

Si la clave se gira, la conexión de datos se deshabilita y no puede capturar datos del origen de datos. Para corregir el problema, actualice o vuelva a crear la conexión de datos.

Formato de datos

  • Los datos se leen desde el centro de eventos en forma de objetos EventData.

  • Consulte los formatos admitidos.

    Nota

  • Los datos se pueden comprimir mediante el algoritmo de compresión GZip. Puede especificar Compression dinámicamente mediante propiedades de ingesta o en la opción Conexión de datos estática.

    Nota

    No se admite la compresión de datos para los formatos comprimidos (Avro, Parquet, ORC, ApacheAvro y W3CLOGFILE). No se admiten la codificación personalizada ni las propiedades del sistema insertadas para los datos comprimidos.

Propiedades de Event Hubs

Azure Data Explorer admite las siguientes propiedades de Event Hubs:

Nota

La ingesta de propiedades personalizadas de Event Hubs, que se usaba para asociar metadatos a eventos, no se admite. Si necesita ingerir propiedades personalizadas, envíelas en el cuerpo de los datos del evento. Para más información, consulte Ingesta de propiedades personalizadas.

Propiedades de la ingesta

Las propiedades de la ingesta indican el proceso de ingesta, dónde enrutar los datos y cómo procesarlos. Puede especificar las propiedades de la ingesta de eventos mediante EventData.Properties. Puede establecer las siguientes propiedades:

Nota:

Los nombres de propiedad distinguen entre mayúsculas y minúsculas.

Propiedad Descripción
Base de datos Nombre de la base de datos de destino en el que se distinguen mayúsculas de minúsculas. De forma predeterminada, los datos se ingieren en la base de datos de destino asociada a la conexión de datos. Use esta propiedad para invalidar la base de datos predeterminada y enviar datos a otra base de datos. Para ello, primero debe configurar la conexión como una conexión de varias bases de datos.
Tabla Nombre de la tabla de destino existente en el que se distinguen mayúsculas de minúsculas. Invalida el valor de Table establecido en el panel Data Connection.
Formato Formato de datos. Invalida el valor de Data format establecido en el panel Data Connection.
IngestionMappingReference Nombre de la asignación de ingesta existente que se va a usar. Invalida el valor de Column mapping establecido en el panel Data Connection.
Compresión Compresión de datos, None (predeterminado) o compresión GZip.
Encoding Codificación de datos, el valor predeterminado es UTF8. Puede ser cualquiera de las codificaciones compatibles con .NET.
Etiquetas Una lista de etiquetas que se asocian a los datos ingeridos, cuyo formato es una cadena de matriz JSON. Hay implicaciones de rendimiento al usar etiquetas.
RawHeaders Indica que el origen del evento es Kafka y Azure Data Explorer deben usar la deserialización de matrices de bytes para leer otras propiedades de enrutamiento. Se ignora el valor.

Nota

Solamente se ingieren los eventos en cola después de crear la conexión de datos.

Enrutamiento de eventos

Al crear una conexión de datos al clúster, puede especificar el enrutamiento a dónde enviar los datos ingeridos. El enrutamiento predeterminado es a la tabla de destino especificada en la cadena de conexión asociada a la base de datos de destino. Al enrutamiento predeterminado de los datos, también se le conoce como enrutamiento estático. Para especificar un enrutamiento alternativo para los datos, establezca las propiedades de los datos de evento que se mencionaron anteriormente.

Enrutamiento de datos de eventos a una base de datos alternativa

El enrutamiento de datos a una base de datos alternativa está desactivado de forma predeterminada. Para enviar los datos a otra base de datos, primero debe establecer la conexión como una conexión de varias bases de datos. Puede hacer esto mediante Azure Portal, C#, Python o una plantilla de ARM. El usuario, grupo, entidad de servicio o identidad administrada que se usa para permitir el enrutamiento de la base de datos debe tener al menos el rol de colaborador y permisos de escritura en el clúster.

Para especificar una base de datos alternativa, establezca la propiedad de ingesta de la base de datos.

Advertencia

Si se especifica una base de datos alternativa sin establecer la conexión como una conexión de datos de varias bases de datos, se producirá un error en la ingesta.

Enrutamiento de datos de eventos a una tabla alternativa

Para especificar una tabla alternativa para cada evento, configure las opciones Tabla, Formato, Compresión y asigne las propiedades de ingesta. La conexión enruta dinámicamente los datos ingeridos tal y como se especifica en EventData.Properties, lo que invalida las propiedades estáticas de este evento.

En el ejemplo siguiente se muestra cómo establecer los detalles de Event Hubs y enviar datos de métricas meteorológicas a una base de datos alternativa (MetricsDB) y a una tabla (WeatherMetrics). Los datos están en formato JSON y mapping1 está predefinido en la tabla 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);

Asignación de propiedades del sistema de eventos

Las propiedades del sistema almacenan las propiedades establecidas por el servicio Event Hubs en el momento en el que se pone en cola el evento. La conexión de datos al centro de eventos puede insertar un conjunto seleccionado de propiedades del sistema en los datos ingeridos en una tabla basada en una asignación determinada.

Nota

  • La inserción de propiedades del sistema es compatible con los formatos json y tabulares (por ejemplo, JSON, MultiJSON, CSV, TSV, PSV, SCsv, SOHsv, TSVE).
  • Si se usa un formato no compatible (es decir, TXT o formatos comprimidos como Parquet, Avro, etc.) la ingesta de datos continuará, pero se omitirán las propiedades.
  • No se admite la inserción de propiedades del sistema cuando se establece una compresión de los mensajes del centro de eventos. En estos escenarios, se emitirá un error adecuado y no se ingerirán los datos.
  • En el caso de los datos tabulares, las propiedades del sistema solo se admiten para los mensajes de eventos de un solo registro.
  • En el caso de los datos JSON, también se admiten las propiedades del sistema para los mensajes de eventos de varios registros. En tales casos, las propiedades del sistema solo se agregan al primer registro del mensaje de evento.
  • Para CSV la asignación, las propiedades se agregan al principio del registro en el orden indicado en la creación de la conexión de datos. No confíe en el orden de estas propiedades, ya que puede cambiar en el futuro.
  • Para la asignación JSON, las propiedades se agregan según los nombres de propiedad de la tabla Propiedades del sistema.

El servicio Event Hubs expone las siguientes propiedades del sistema:

Propiedad Tipo de datos Descripción
x-opt-enqueued-time datetime Hora UTC en la que se puso en cola el evento
x-opt-sequence-number long Número de secuencia lógica del evento en el flujo de partición del centro de eventos
x-opt-offset string Desplazamiento del evento en relación con el flujo de partición del centro de eventos. El identificador de desplazamiento es único dentro de una partición del flujo del centro de eventos.
x-opt-publisher string Nombre del publicador, si el mensaje se envió a un punto de conexión del publicador
x-opt-partition-key string Clave de partición de la partición correspondiente que almacenó el evento

Al trabajar con centros de eventos de IoT Central, también puede insertar las propiedades del sistema de IoT Hub en la carga. Para obtener la lista completa, consulte Propiedades del sistema de IoT Hub.

Si ha seleccionado Propiedades del sistema de eventos en la sección Origen de datos de la tabla, debe incluir las propiedades en el esquema de la tabla y la asignación.

Ejemplos de asignación de esquemas

Ejemplo de asignación de esquema de tabla

Si los datos incluyen tres columnas (Timespan, Metric y Value) y las propiedades que incluye son x-opt-enqueued-time y x-opt-offset, cree o modifique el esquema de tabla mediante este comando:

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

Ejemplo de asignación CSV

Ejecute los siguientes comandos para agregar datos al principio del registro. Observe los valores ordinales.

    .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"}}'
    ']'

Ejemplo de asignación JSON

Los datos se agregan mediante la asignación de propiedades del sistema. Ejecute estos 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"}}'
    ']'

Asignación de esquemas para archivos Avro de Event Hubs Capture

Una manera de consumir datos del centro de eventos es capturar eventos a través de Azure Event Hubs en Azure Blob Storage o Azure Data Lake Storage. A continuación, puede ingerir los archivos de captura a medida que se escriben mediante una conexión de datos de Event Grid en Azure Data Explorer.

El esquema de los archivos de captura es diferente del esquema del evento original enviado al centro de eventos. Debe diseñar el esquema de la tabla de destino con esta diferencia en mente. En concreto, la carga del evento se representa en el archivo de captura como una matriz de bytes y esta matriz no se descodifica automáticamente mediante la conexión de datos entre Event Grid y Azure Data Explorer. Para obtener información más específica sobre el esquema de archivo de los datos de captura de Avro de Event Hubs, consulte Exploración de archivos Avro capturados en Azure Event Hubs.

Para descodificar correctamente la carga del evento:

  1. Asigne el campo Body del evento capturado a una columna de tipo dynamic en la tabla de destino.
  2. Aplique una directiva de actualización que convierta la matriz de bytes en una cadena legible mediante la función unicode_codepoints_to_string().

Ingesta de propiedades personalizadas

Al ingerir eventos de Event Hubs, los datos se toman de la sección body del objeto de datos de evento. Sin embargo, las propiedades personalizadas de Event Hubs se definen en la sección properties del objeto y no se ingieren. Para ingerir propiedades personalizadas, debe insertarlas en los datos de la sección body del objeto.

En el ejemplo siguiente se compara el objeto de datos de eventos que contiene la propiedad personalizada customProperty tal como se define en Event Hubs (izquierda) con la propiedad insertada necesaria para la ingesta (derecha).

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

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

Puede usar uno de los métodos siguientes para insertar propiedades personalizadas en los datos de la sección body del objeto de datos de evento:

Conexión de datos del centro de eventos entre regiones

Para obtener el mejor rendimiento, cree todos los siguientes recursos en la misma región que el clúster. Si no hay ninguna otra alternativa, considere la posibilidad de usar los niveles Premium o Dedicated Event Hubs. La comparación de niveles de Event Hubs se puede encontrar aquí.

Creación de un centro de eventos

Si aún no lo tiene, cree un centro de eventos. La conexión al centro de eventos se puede administrar desde Azure Portal, mediante programación con C# o Python o con una plantilla de Azure Resource Manager.

Nota

  • La posibilidad de agregar particiones dinámicamente después de crear un centro de eventos solo está disponible en los niveles Premium y Dedicado de Event Hubs. Considere la posibilidad de escalar a largo plazo al establecer el número de particiones.
  • El grupo de consumidores debe ser único por consumidor. Cree un grupo de consumidores dedicado para la conexión de Azure Data Explorer.

Envío de eventos

Examine la aplicación de ejemplo que genera los datos y los envía a un centro de eventos.

Para obtener un ejemplo de cómo generar datos de ejemplo, consulte Ingesta de datos de Event Hubs a Azure Data Explorer.

Configuración de una solución de recuperación ante desastres geográfica

Event Hubs ofrece una solución de recuperación ante desastres geográfica. Azure Data Explorer no admite los espacios de nombres del centro de eventos con Alias. Para implementar la recuperación ante desastres geográfica en la solución, cree dos conexiones de datos del centro de eventos: una para el espacio de nombres principal y otra para el espacio de nombres secundario. Azure Data Explorer escuchará en ambas conexiones del centro de eventos.

Nota

Es responsabilidad del usuario implementar una conmutación por error del espacio de nombres principal en el espacio de nombres secundario.

Contenido relacionado