Desencadenador y enlaces de Azure Event Hubs para Azure Functions

  • Artículo

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 el mismo proceso que el host de Functions. Para más información, consulte Desarrollo de funciones de la biblioteca de clases de C# con Azure Functions.

En una variación de este modelo, Functions se puede ejecutar mediante el scripting de C#, que se admite principalmente para la edición del portal de C#. Para actualizar las extensiones de enlace existentes de las aplicaciones del script de C# que se ejecutan en el portal sin tener que volver a publicar la aplicación de funciones, consulte Actualización de las extensiones.

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

En esta sección se describe el uso de una biblioteca de clases. En el caso del scripting de C#, tendría que instalar en su lugar la agrupación de extensiones, versión 4.x.

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 usa el tipo de enlace de Event Hubs Azure.Messaging.EventHubs.EventData más reciente.

Esta versión de extensión está disponible instalando este 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 uno de los siguientes:

Un biblioteca de clases en proceso es una función de C# compilada que se ejecuta en el mismo proceso que Functions Runtime.

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

La extensión de Event Hubs admite tipos de parámetros según la tabla siguiente.

Escenario de enlace Tipos de parámetro
Desencadenador de Event Hubs (evento único) Azure.Messaging.EventHubs.EventData
Tipos serializables con JSON1
string
byte[]
[BinaryData]
Desencadenador de Event Hubs (lote de eventos) EventData[]
string[]
Salida de Event Hubs (evento único) Azure.Messaging.EventHubs.EventData
Tipos serializables con JSON1
string
byte[]
[BinaryData]
Salida de Event Hubs (varios eventos) ICollector<T> o IAsyncCollector<T> donde T es uno de los tipos de eventos únicos

1 Los eventos que contienen datos JSON se pueden deserializar en tipos conocidos de objetos CLR sin formato (POCO).

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
maxEventBatchSize 10 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 personalizada y se debe especificar 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 redondeará a 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 . 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.

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