Desencadenador de Azure Event Hubs para Azure FunctionsAzure Event Hubs trigger for Azure Functions

En este artículo se explica cómo usar el desencadenador de Azure Event Hubs para Azure Functions.This article explains how to work with Azure Event Hubs trigger for Azure Functions. Azure Functions admite los enlaces de salida y desencadenador para Event Hubs.Azure Functions supports trigger and output bindings for Event Hubs.

Para obtener información sobre los detalles de instalación y configuración, vea la información general.For information on setup and configuration details, see the overview.

Use el desencadenador de funciones para responder a un evento enviado a una secuencia de eventos del centro de eventos.Use the function trigger to respond to an event sent to an event hub event stream. Debe tener acceso de lectura al centro de eventos subyacente para configurar el desencadenador.You must have read access to the underlying event hub to set up the trigger. Cuando esta función se desencadena, el mensaje que se pasa a la función se escribe como una cadena.When the function is triggered, the message passed to the function is typed as a string.

AmpliaciónScaling

Cada instancia de una función de desencadenador de eventos está respaldada por una única instancia de EventProcessorHost.Each instance of an event triggered function is backed by a single EventProcessorHost instance. El desencadenador (con tecnología de Event Hubs) garantiza que solo una instancia de EventProcessorHost puede obtener una concesión en una partición determinada.The trigger (powered by Event Hubs) ensures that only one EventProcessorHost instance can get a lease on a given partition.

Por ejemplo, considere una instancia de Event Hubs con las siguientes características:For example, consider an Event Hub as follows:

  • 10 particiones.10 partitions
  • 1000 eventos distribuidos uniformemente en todas las particiones, con 100 mensajes en cada partición.1,000 events distributed evenly across all partitions, with 100 messages in each partition

Cuando se habilita la función por primera vez, solo hay una instancia de la función.When your function is first enabled, there is only one instance of the function. Vamos a llamar a esta instancia de función Function_0.Let's call the first function instance Function_0. Laq función Function_0 tiene una sola instancia de EventProcessorHost que contiene una concesión en las diez particiones.The Function_0 function has a single instance of EventProcessorHost that holds a lease on all ten partitions. Esta instancia lee eventos de las particiones 0-9.This instance is reading events from partitions 0-9. A partir de este punto, se producirá una de las siguientes acciones:From this point forward, one of the following happens:

  • No se necesitan nuevas instancias de función: Function_0 puede procesar los 1000 eventos antes de que la lógica de escalado de Azure Functions surta efecto.New function instances are not needed: Function_0 is able to process all 1,000 events before the Functions scaling logic take effect. En este caso, Function_0 procesa los 1000 mensajes.In this case, all 1,000 messages are processed by Function_0.

  • Se agrega una instancia de función adicional: Si la lógica de escalado de Azure Functions determina que Function_0 tiene más mensajes de los que puede procesar, se crea una nueva instancia de la aplicación de función (Function_1).An additional function instance is added: If the Functions scaling logic determines that Function_0 has more messages than it can process, a new function app instance (Function_1) is created. Esta nueva función también tiene asociada una instancia de EventProcessorHost.This new function also has an associated instance of EventProcessorHost. Como la instancia de Event Hubs subyacente detecta que una nueva instancia de host está tratando de leer mensajes, efectúa un equilibrio de carga de las particiones entre las instancias de host.As the underlying Event Hubs detect that a new host instance is trying read messages, it load balances the partitions across the host instances. Por ejemplo, las particiones 0-4 pueden asignarse a Function_0 y las particiones 5-9, a Function_1.For example, partitions 0-4 may be assigned to Function_0 and partitions 5-9 to Function_1.

  • Se agregan N instancias de función más: Si la lógica de escalado de Azure Functions determina que tanto Function_0 como Function_1 tienen más mensajes de los que pueden procesar, se crean más instancias de aplicaciones de función de Functions_N.N more function instances are added: If the Functions scaling logic determines that both Function_0 and Function_1 have more messages than they can process, new Functions_N function app instances are created. Se van creando aplicaciones hasta llegar a un punto en el que N es mayor que el número de particiones de centro de eventos.Apps are created to the point where N is greater than the number of event hub partitions. En nuestro ejemplo, Event Hubs vuelve a equilibrar la carga de las particiones, en este caso, entre las instancias Function_0...Functions_9.In our example, Event Hubs again load balances the partitions, in this case across the instances Function_0...Functions_9.

Cuando se produce el escalado, N instancias es un número mayor que el número de particiones del centro de eventos.As scaling occurs, N instances is a number greater than the number of event hub partitions. Este patrón se usa para garantizar que va a haber instancias de EventProcessorHost disponibles para obtener bloqueos de las particiones a medida que estén disponibles en otras instancias.This pattern is used to ensure EventProcessorHost instances are available to obtain locks on partitions as they become available from other instances. Solo se le cobra por los recursos usados cuando se ejecuta la instancia de la función.You are only charged for the resources used when the function instance executes. En otras palabras, no se le cobrará por este aprovisionamiento en exceso.In other words, you are not charged for this over-provisioning.

Cuando se completa la ejecución de todas las funciones con o sin errores, se agregan puntos de comprobación a la cuenta de almacenamiento asociada.When all function execution completes (with or without errors), checkpoints are added to the associated storage account. Cuando estos puntos de conexión se agregan correctamente, los 1000 mensajes ya no se vuelven a recuperar.When check-pointing succeeds, all 1,000 messages are never retrieved again.

En el ejemplo siguiente se muestra una función de C# que registra el cuerpo del mensaje del desencadenador del centro de eventos.The following example shows a C# function that logs the message body of the event hub trigger.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

Para acceder a los metadatos del evento en el código de función, cree un enlace a un objeto EventData (requiere el uso de una instrucción para Microsoft.Azure.EventHubs).To get access to event metadata in function code, bind to an EventData object (requires a using statement for Microsoft.Azure.EventHubs). También puede acceder a las mismas propiedades mediante el uso de expresiones de enlace en la firma del método.You can also access the same properties by using binding expressions in the method signature. El ejemplo siguiente se muestran las dos maneras de obtener los mismos datos:The following example shows both ways to get the same data:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Para recibir eventos en un lote, convierta string o EventData en una matriz.To receive events in a batch, make string or EventData an array.

Nota

Cuando se reciben en un lote, no se puede establecer un enlace a parámetros de método como en el ejemplo anterior con DateTime enqueuedTimeUtc y debe recibirlos desde cada objeto EventData.When receiving in a batch you cannot bind to method parameters like in the above example with DateTime enqueuedTimeUtc and must receive these from each EventData object

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Atributos y anotacionesAttributes and annotations

En las bibliotecas de clases de C#, use el atributo EventHubTriggerAttribute.In C# class libraries, use the EventHubTriggerAttribute attribute.

El constructor del atributo toma el nombre del centro de eventos, el nombre del grupo de consumidores y el nombre de una configuración de aplicación que contenga la cadena de conexión.The attribute's constructor takes the name of the event hub, the name of the consumer group, and the name of an app setting that contains the connection string. Para obtener más información sobre estas configuraciones, vea la sección Configuración de desencadenador.For more information about these settings, see the trigger configuration section. Este es un ejemplo de atributo EventHubTriggerAttribute:Here's an EventHubTriggerAttribute attribute example:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

Para un ejemplo completo, consulte Desencadenador: ejemplo de C#.For a complete example, see Trigger - C# example.

ConfiguraciónConfiguration

En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json y el atributo EventHubTrigger.The following table explains the binding configuration properties that you set in the function.json file and the EventHubTrigger attribute.

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DescripciónDescription
typetype N/Dn/a Se debe establecer en eventHubTrigger.Must be set to eventHubTrigger. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
directiondirection N/Dn/a Se debe establecer en in.Must be set to in. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
namename N/Dn/a Nombre de la variable que representa el elemento de evento en el código de la función.The name of the variable that represents the event item in function code.
pathpath EventHubNameEventHubName Solo Functions 1.x.Functions 1.x only. El nombre del centro de eventos.The name of the event hub. Cuando el nombre del centro de eventos también está presente en la cadena de conexión, ese valor reemplaza esta propiedad en tiempo de ejecución.When the event hub name is also present in the connection string, that value overrides this property at runtime.
eventHubNameeventHubName EventHubNameEventHubName Functions 2.x y versiones posteriores.Functions 2.x and higher. El nombre del centro de eventos.The name of the event hub. Cuando el nombre del centro de eventos también está presente en la cadena de conexión, ese valor reemplaza esta propiedad en tiempo de ejecución.When the event hub name is also present in the connection string, that value overrides this property at runtime. Se puede hacer referencia a él desde la configuración de la aplicación %eventHubName%Can be referenced via app settings %eventHubName%
consumerGroupconsumerGroup ConsumerGroupConsumerGroup Una propiedad opcional que establece el grupo de consumidores que se usará para suscribirse a los eventos del centro.An optional property that sets the consumer group used to subscribe to events in the hub. Si se pasa por alto, se utilizará el grupo de consumidores $Default.If omitted, the $Default consumer group is used.
cardinalidadcardinality N/Dn/a Se utiliza para los lenguajes distintos de C#.Used for all non-C# languages. Defínalo como many para permitir el procesamiento por lotes.Set to many in order to enable batching. Si se omite o se define como one, se pasa un único mensaje a la función.If omitted or set to one, a single message is passed to the function.

En C#, esta propiedad se asigna automáticamente siempre que el desencadenador tenga una matriz para el tipo.In C#, this property is automatically assigned whenever the trigger has an array for the type.
connectionconnection ConnectionConnection El nombre de una configuración de aplicación que contenga la cadena de conexión para el espacio de nombres del centro de eventos.The name of an app setting that contains the connection string to the event hub's namespace. Copie esta cadena de conexión haciendo clic en el botón Información de conexión del espacio de nombres, no del propio centro de eventos.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Esta cadena de conexión debe tener al menos permisos de lectura para activar el desencadenador.This connection string must have at least read permissions to activate the trigger.

Cuando desarrolla localmente, la configuración de aplicación pasa al archivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Metadatos de eventoEvent metadata

El desencadenador de Event Hubs proporciona varias propiedades de metadatos.The Event Hubs trigger provides several metadata properties. Se pueden usar propiedades de metadatos como parte de expresiones de enlace en otros enlaces o como parámetros del código.Metadata properties can be used as part of binding expressions in other bindings or as parameters in your code. Las propiedades proceden de la clase EventData.The properties come from the EventData class.

PropiedadProperty TipoType DescripciónDescription
PartitionContext PartitionContextPartitionContext Instancia de PartitionContext.The PartitionContext instance.
EnqueuedTimeUtc DateTime Hora de puesta en la cola en UTC.The enqueued time in UTC.
Offset string El desplazamiento de los datos relacionados con el flujo de partición de Event Hubs.The offset of the data relative to the Event Hub partition stream. El desplazamiento es un marcador o identificador del flujo de Event Hubs.The offset is a marker or identifier for an event within the Event Hubs stream. El identificador es único dentro de una partición del flujo de Event Hubs.The identifier is unique within a partition of the Event Hubs stream.
PartitionKey string La partición a la que se deben enviar los datos del evento.The partition to which event data should be sent.
Properties IDictionary<String,Object> Las propiedades de usuario de los datos del evento.The user properties of the event data.
SequenceNumber Int64 El número de secuencia de registro del evento.The logical sequence number of the event.
SystemProperties IDictionary<String,Object> Las propiedades del sistema, incluidos los datos del evento.The system properties, including the event data.

Consulte los ejemplos de código que utilizan estas propiedades más arriba en este artículo.See code examples that use these properties earlier in this article.

Propiedades de host.jsonhost.json properties

El archivo host.json contiene opciones de configuración que controlan el comportamiento de Event Hubs.The host.json file contains settings that control Event Hubs trigger behavior. La configuración varía en función de la versión de Azure Functions.The configuration is different depending on the Azure Functions version.

Functions 2.x y superioresFunctions 2.x and higher

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "batchCheckpointFrequency": 5,
            "eventProcessorOptions": {
                "maxBatchSize": 256,
                "prefetchCount": 512
            },
            "initialOffsetOptions": {
                "type": "fromStart",
                "enqueuedTime": ""
            }
        }
    }
}  
PropiedadProperty Valor predeterminadoDefault DescripciónDescription
batchCheckpointFrequencybatchCheckpointFrequency 11 Número de lotes de eventos que se va a procesar antes de crear un punto de comprobación de cursor de EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.
eventProcessorOptions/maxBatchSizeeventProcessorOptions/maxBatchSize 1010 Número máximo de eventos recibido por cada bucle de recepción.The maximum event count received per receive loop.
eventProcessorOptions/prefetchCounteventProcessorOptions/prefetchCount 300300 Número predeterminado de capturas previas utilizado por el elemento EventProcessorHost subyacente.The default pre-fetch count used by the underlying EventProcessorHost. El valor mínimo permitido es 10.The minimum allowed value is 10.
initialOffsetOptions/typeinitialOffsetOptions/type fromStartfromStart Ubicación en el flujo de eventos desde la que se inicia el procesamiento cuando no existe un punto de control en el almacenamiento.The location in the event stream from which to start processing when a checkpoint doesn't exist in storage. Las opciones son fromStart, fromEnd o fromEnqueuedTime.Options are fromStart , fromEnd or fromEnqueuedTime. fromEnd procesa los nuevos eventos que se pusieron en cola después de iniciar la ejecución de la aplicación de funciones.fromEnd processes new events that were enqueued after the function app started running. Se aplica a todas las particiones.Applies to all partitions. Para más información, consulte la documentación de EventProcessorOptions.For more information, see the EventProcessorOptions documentation.
initialOffsetOptions/enqueuedTimeinitialOffsetOptions/enqueuedTime N/DN/A Especifica la hora de puesta en cola del evento en la secuencia a partir de la que se va a iniciar el procesamiento.Specifies the enqueued time of the event in the stream from which to start processing. Cuando initialOffsetOptions/type se configura como fromEnqueuedTime, este valor es obligatorio.When initialOffsetOptions/type is configured as fromEnqueuedTime, this setting is mandatory. Admite la hora en cualquier formato admitido por DateTime.Parse(), como 2020-10-26T20:31Z.Supports time in any format supported by DateTime.Parse(), such as 2020-10-26T20:31Z. Para mayor claridad, también debe especificar una zona horaria.For clarity, you should also specify a timezone. 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.When timezone isn't specified, Functions assumes the local timezone of the machine running the function app, which is UTC when running on Azure. Para más información, consulte la documentación de EventProcessorOptions.For more information, see the EventProcessorOptions documentation.

Nota

Para una referencia de host.json en Azure Functions 2.x y versiones posteriores, consulte Referencia de host.json para Azure Functions.For a reference of host.json in Azure Functions 2.x and beyond, see host.json reference for Azure Functions.

Functions 1.xFunctions 1.x

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}
PropiedadProperty Valor predeterminadoDefault DescripciónDescription
maxBatchSizemaxBatchSize 6464 Número máximo de eventos recibido por cada bucle de recepción.The maximum event count received per receive loop.
prefetchCountprefetchCount N/Dn/a Número predeterminado de capturas previas que utilizará el elemento EventProcessorHost subyacente.The default pre-fetch that will be used by the underlying EventProcessorHost.
batchCheckpointFrequencybatchCheckpointFrequency 11 Número de lotes de eventos que se va a procesar antes de crear un punto de comprobación de cursor de EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.

Nota

Para una referencia de host.json en Azure Functions 1.x, consulte Referencia de host.json para Azure Functions 1.x.For a reference of host.json in Azure Functions 1.x, see host.json reference for Azure Functions 1.x.

Pasos siguientesNext steps