Compartir a través de

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, cree un centro de eventos en Azure Portal. A continuación, cree una tabla de destino en Azure Data Explorer en la que se ingieren los datos en un formato determinado mediante las propiedades de ingesta proporcionadas. La conexión de Event Hubs debe tener en cuenta 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.

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

  • Conexión de datos basada en identidad administrada (recomendada): el uso de una conexión de datos basada en identidad administrada es la manera más segura de conectarse a orígenes de datos. Proporciona control total sobre la capacidad de capturar datos de un origen de datos. La configuración de una conexión de datos mediante una identidad administrada requiere los siguientes pasos:

    1. Adición de una identidad administrada al clúster.
    2. Concesión de permisos a la identidad administrada en el origen de datos. Para capturar datos desde Azure Event Hubs, la identidad administrada debe tener permisos de Receptor de datos de Azure Event Hubs.
    3. Implantación de una directiva de identidad administrada en las bases de datos de destino.
    4. Creación de una conexión de datos mediante la autenticación de identidad administrada para capturar datos.

    Precaución

    Si se quitan los permisos de identidad administrada del origen de datos, la conexión de datos ya no funcionará y no podrá capturar datos del origen de datos.

  • Conexión de datos basada en claves: si no se especifica una autenticación de identidad administrada para la conexión de datos, la conexión establecerá automáticamente como forma predeterminada 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 obtiene la cadena de conexión de recursos para el recurso especificado y la guarda de forma segura. A continuación, la cadena de conexión se usa para capturar datos del origen de datos.

    Precaución

    Si se rota la clave, la conexión de datos ya no funcionará y no podrá capturar datos del origen de datos. Para corregir el problema, actualice o vuelva a crear la conexión de datos.

Formato de datos

Nota:

  • La ingesta desde Event Hubs no admite el formato RAW.
  • No se admiten el registro de esquema de Azure Event Hubs ni Avro sin esquemas.
  • 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.
  • No se admite la compresión de datos para formatos los binarios (Avro, ApacheAvro, Parquet, ORC y W3CLOGFILE).
  • No se admiten la codificación personalizada y las propiedades del sistema insertadas con formatos binarios y datos comprimidos.
  • Al usar formatos binarios (Avro, ApacheAvro, Parquet, ORC y W3CLOGFILE) y asignaciones de ingesta, el orden de los campos en la definición de la asignación de ingesta debe coincidir con el orden de las columnas correspondientes en la tabla.

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 (valor predeterminado) o 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 debe usar la deserialización de matrices de bytes para leer otras propiedades de enrutamiento. Se ignora el valor.

Nota:

Solo se ingieren los eventos puestos en cola después de crear la conexión de datos, a menos que se proporcione una fecha de inicio de recuperación personalizada. En cualquier caso, el período de búsqueda no puede superar el período de retención real del centro de eventos.

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. Puede especificar una opción alternativa de enrutamiento y procesamiento para los datos estableciendo una o varias propiedades de datos de eventos mencionadas en el párrafo anterior.

Nota:

La conexión de datos de Event Hubs intentará procesar todos los eventos que lee del centro de eventos y cada evento que no puede procesar por cualquier motivo se notificará como un error de ingesta. Lea cómo supervisar la ingesta de Azure Data Explorer aquí.

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. Esta característica se puede habilitar en Azure Portal de Azure Portal, con SDK de administración de C# o Python , o con 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 Event Hubs

Las propiedades del sistema son campos establecidos por el servicio Event Hubs, en el momento en que se puesta en cola el evento. La conexión de datos del Explorador de datos de Azuer Data Hubs puede insertar un conjunto predefinido 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.
  • En el caso de la asignación CSV, las propiedades se agregan al principio del registro en el orden que se muestra 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 (TimeStamp, MetricName 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, MetricName: 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" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "MetricName", "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" : "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"}}'
    ']'

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 a Event Hubs. 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 más información sobre el esquema de archivos para 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 de Event Hubs entre regiones

Para obtener el mejor rendimiento, cree todos los siguientes recursos en la misma región que el clúster. Si no hay otra opción, considere la posibilidad de usar los niveles Premium o Dedicado de Event Hubs. La comparación entre 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.

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