Comparteix a través de

Desencadenador y enlaces de Azure Event Hubs para Azure Functions

  • Article

En este artículo se explica cómo usar enlaces de Azure Event Hubs para Azure Functions. Azure Functions admite enlaces de desencadenador y salida para Event Hubs.

Acción Tipo
Responder a los eventos enviados a una secuencia de eventos del centro de eventos. Desencadenador
Escribir eventos en una secuencia de eventos. Enlace de salida

Instalación de la extensión

El paquete NuGet de la extensión que instale depende del modo de C# que esté usando en la aplicación de funciones:

Las funciones se ejecutan en un proceso de trabajo de C# aislado. Para más información, consulte Guía para ejecutar C# Azure Functions en un proceso de trabajo aislado.

La funcionalidad de la extensión varía en función de la versión de la extensión:

Esta versión presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Esta versión admite la configuración de desencadenadores y enlaces a través de la integración de .NET Aspire.

Para agregar la extensión al proyecto, instale el paquete NuGet, versión 5.x.

Instalación del conjunto

La extensión de Event Hubs forma parte de un conjunto de extensiones, que se especifica en el archivo de proyecto host.json. Es posible que tenga que modificar este conjunto para cambiar la versión de los enlaces o en caso de que los conjuntos aún no estén instalados. Para obtener más información, consulte Conjuntos de extensiones.

Esta versión presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Para agregar esta versión de la extensión desde el conjunto de extensiones v3, puede agregar o reemplazar el código siguiente en el archivo host.json:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Para obtener más información, consulte Actualización de las extensiones.

Tipos de enlaces

Los tipos de enlace admitidos para .NET dependen de la versión de extensión y del modo de ejecución de C#, que puede ser una de las siguientes opciones:

Una función de C# compilada de la biblioteca de clases de procesos de trabajo aislados se ejecuta en un proceso aislado del entorno de ejecución.

Seleccione una versión para ver los detalles del tipo de enlace para el modo y la versión.

El proceso de trabajo aislado admite tipos de parámetros según las tablas siguientes. El soporte para enlazar a tipos desde Azure.Messaging.EventHubs está en versión preliminar.

Desencadenador de Event Hubs

Cuando quiera que la función procese un único evento, el desencadenador de Event Hubs puede enlazarse a los siguientes tipos:

Tipo Descripción
string El evento como una cadena. Se usa cuando el evento es de texto simple.
byte[] Bytes del evento.
Tipos serializables con JSON Cuando un evento contenga datos JSON, Functions intentará deserializar los datos JSON en un tipo de objeto CLR sin formato (POCO).
Azure.Messaging.EventHubs.EventData1 El objeto de evento.
Si va a migrar desde cualquier versión anterior de los SDK de Event Hubs, tenga en cuenta que esta versión quitará la compatibilidad con el tipo Body heredado en favor de EventBody.

Cuando quiera que la función procese un lote de eventos, podrá enlazarse el desencadenador de Event Hubs a los siguientes tipos:

Tipo Descripción
string[] Una matriz de eventos del lote, como cadenas. Cada entrada representa un evento.
EventData[] 1 Matriz de eventos del lote, como instancias de Azure.Messaging.EventHubs.EventData. Cada entrada representa un evento.
T[] donde T es un tipo JSON serializable1 Matriz de eventos del lote, como instancias de un tipo POCO personalizado. Cada entrada representa un evento.

1 Para utilizar estos tipos, debe hacer referencia a Microsoft.Azure.Functions.Worker.Extensions.EventGrid 5.5.0 o posterior y a las dependencias comunes para los enlaces de tipo SDK.

Enlace de salida de Event Hubs

Cuando quiera que la función escriba un único evento, el enlace de salida de Event Hubs puede enlazarse a los siguientes tipos:

Tipo Descripción
string El evento como una cadena. Se usa cuando el evento es de texto simple.
byte[] Bytes del evento.
Tipos serializables con JSON Un objeto que representa el evento. Functions intenta serializar un tipo de objeto CLR convencional (POCO) en datos JSON.

Cuando quiera que la función escriba varios eventos, el enlace de salida de Event Hubs puede enlazarse a los siguientes tipos:

Tipo Descripción
T[] donde T es uno de los tipos de eventos únicos Matriz que contiene varios eventos. Cada entrada representa un evento.

Para otros escenarios de salida, cree y use eventHubProducerClient con otros tipos de Azure.Messaging.EventHubs directamente. Consulte Registro de clientes de Azure para obtener un ejemplo de uso de la inserción de dependencias para crear un tipo de cliente a partir del SDK de Azure.

configuración de host.json

El archivo host.json contiene opciones de configuración que controlan el comportamiento del desencadenador de Event Hubs. La configuración varía en función de la versión de las extensiones.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Propiedad Valor predeterminado Descripción
maxEventBatchSize2 100 Número máximo de eventos que se incluirán en un lote para una sola invocación. Debe ser 1 como mínimo.
minEventBatchSize1 1 Número mínimo de eventos deseados en un lote. El número mínimo solo se aplica cuando la función recibe varios eventos y debe ser menor que maxEventBatchSize.
El tamaño mínimo no está garantizado estrictamente. Se envía un lote parcial cuando no se puede preparar un lote completo antes de que maxWaitTime haya transcurrido. Los lotes parciales también son probables para la primera invocación de la función después de que se produzca el escalado.
maxWaitTime1 00:01:00 Intervalo máximo que el desencadenador debe esperar para rellenar un lote antes de invocar la función. El tiempo de espera solo se considera cuando minEventBatchSize es mayor que 1 y, de lo contrario, se omite. Si hay menos de minEventBatchSize eventos disponibles antes de que transcurra el tiempo de espera, se invoca la función con un lote parcial. El tiempo de espera permitido más largo es de 10 minutos.

NOTA: Este intervalo no es una garantía estricta para el tiempo exacto en el que se invoca la función. Hay un pequeño margen de error debido a la precisión del temporizador. Cuando se realiza el escalado, la primera invocación con un lote parcial puede producirse más rápidamente o puede tardar hasta dos veces el tiempo de espera configurado.
batchCheckpointFrequency 1 Número de lotes que se procesarán antes de crear un punto de control para el centro de eventos.
prefetchCount 300 Número de eventos que se solicitan diligentemente desde Event Hubs y que se mantienen en una caché local para permitir que las lecturas eviten esperar en una operación de red.
transportType amqpTcp El protocolo y el transporte que se usan para comunicarse con Event Hubs. Opciones disponibles: amqpTcp, amqpWebSockets.
webProxy null Proxy que se usará para comunicarse con Event Hubs a través de sockets web. Recuerde que no se puede usar un proxy con el transporte amqpTcp.
customEndpointAddress null Dirección que se va a usar al establecer una conexión a Event Hubs, lo que permite enrutar las solicitudes de red a través de una puerta de enlace de aplicaciones u otra ruta de acceso necesaria para el entorno de host. El espacio de nombres completo para el centro de eventos sigue siendo necesario cuando se usa una dirección de punto de conexión personalizado y debe especificarse explícitamente o a través de la cadena de conexión.
targetUnprocessedEventThreshold1 null Número deseado de eventos no procesados por instancia de función. El umbral se usa en el escalado basado en el destino para invalidar el umbral de escalado predeterminado inferido de la opción maxEventBatchSize. Cuando se establezca, el recuento total de eventos no procesados se dividirá por este valor para determinar el número de instancias de función necesarias. El recuento de instancias se redondea hasta un número que crea una distribución de partición equilibrada.
initialOffsetOptions/type fromStart Ubicación en el flujo de eventos desde la que se inicia el procesamiento cuando no existe un punto de control en el almacenamiento. Se aplica a todas las particiones. Para obtener más información, consulte la documentación de OffsetType. Opciones disponibles: fromStart, fromEnd, fromEnqueuedTime.
initialOffsetOptions/enqueuedTimeUtc null Especifica la hora de puesta en cola del evento en la secuencia a partir de la que se va a iniciar el procesamiento. Cuando initialOffsetOptions/type se configura como fromEnqueuedTime, este valor es obligatorio. Admite la hora en cualquier formato admitido por DateTime.Parse(), como 2020-10-26T20:31Z. Para mayor claridad, también debe especificar una zona horaria. Cuando no se especifica una zona horaria, Functions asume la zona horaria local del equipo que ejecuta la aplicación de funciones, que es la hora UTC cuando se ejecuta en Azure.
clientRetryOptions/mode exponential Enfoque que se debe usar para calcular los retrasos de reintento. El modo exponencial aplica un retraso a los reintentos en función de una estrategia de interrupción, en la que cada intento aumentará la duración que espera antes de volver a intentarlo. El modo fijo reintenta la operación a intervalos fijos, donde cada retraso tiene una duración uniforme. Opciones disponibles: exponential, fixed.
clientRetryOptions/tryTimeout 00:01:00 Duración máxima para esperar a que se complete la operación de Event Hubs por intento.
clientRetryOptions/delay 00:00:00.80 Factor de retraso o de interrupción que se aplicará entre reintentos.
clientRetryOptions/maximumDelay 00:00:01 Retraso máximo que se permite entre los reintentos.
clientRetryOptions/maximumRetries 3 Número máximo de reintentos antes de considerar que hay un error en la operación asociada.

1 El uso de minEventBatchSize y maxWaitTime requiere la versión v5.3.0 del paquete Microsoft.Azure.WebJobs.Extensions.EventHubs o una versión posterior.

2 El valor predeterminado maxEventBatchSize cambiado en la versión 6.0.0 del Microsoft.Azure.WebJobs.Extensions.EventHubs paquete. En versiones anteriores, era 10.

clientRetryOptions se usan para reintentar las operaciones entre el host de Functions y Event Hubs (como capturar eventos y enviar eventos). Consulte las instrucciones sobre el Control de errores y reintentos de Azure Functions para obtener información sobre cómo aplicar directivas de reintento a funciones individuales.

Para una referencia de host.json en Azure Functions 2.x y versiones posteriores, consulte Referencia de host.json para Azure Functions.

Pasos siguientes