Compartir vía

Enlaces de Azure Service Bus en Azure Functions

  • Artículo

Azure Functions se integra con Azure Service Bus mediante desencadenadores y enlaces. La integración con Service Bus permite crear funciones que reaccionan ante y envían mensajes de cola o tema.

Acción Tipo
Ejecutar una función cuando se crea un mensaje de cola o tema de Service Bus Desencadenador
Enviar mensajes de Azure Service Bus 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 obtener más información, consulte la Guía para ejecutar C# Azure Functions en un proceso aislado.

Para agregar la extensión al proyecto, instale este paquete NuGet.

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 permite enlazar a tipos de Azure.Messaging.ServiceBus.

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

El enlace de Service Bus 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:

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.

Desencadenador de Service Bus

Cuando desee que la función procese un único mensaje, el desencadenador de Service Bus puede enlazarse a los siguientes tipos:

Tipo Descripción
string El mensaje como una cadena. Se usa cuando el mensaje es de texto simple.
byte[] Bytes del mensaje.
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).
ServiceBusReceivedMessage1 El objeto del mensaje.

Si se enlaza a ServiceBusReceivedMessage, también puede incluir un parámetro de tipo ServiceBusMessageActions1,2 para realizar acciones de liquidación de mensajes.

Cuando quiera que la función procese un lote de mensajes, el desencadenador de Service Bus puede enlazarse a los siguientes tipos:

Tipo Descripción
T[] donde T es uno de los tipos de mensaje únicos Una matriz de eventos del lote. Cada entrada representa un evento.

Si se enlaza a ServiceBusReceivedMessage[], también puede incluir un parámetro de tipo ServiceBusMessageActions1,2 para realizar acciones de liquidación de mensajes.

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

2 Al usar ServiceBusMessageActions, establezca la AutoCompleteMessages propiedad del atributo trigger en false. Esto impide que el tiempo de ejecución intente completar los mensajes después de una invocación de función correcta.

Enlace de salida de Service Bus

Cuando quiera que la función escriba un único mensaje, el enlace de salida de Service Bus puede enlazarse a los siguientes tipos:

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

Cuando quiera que la función escriba varios mensajes, el enlace de salida de Service Bus puede enlazarse a los siguientes tipos:

Tipo Descripción
T[] donde T es uno de los tipos de mensaje únicos Una matriz que contiene varios mensajes. Cada entrada representa un mensaje.

Para otros escenarios de salida, cree y use un ServiceBusClient con otros tipos de Azure.Messaging.ServiceBus 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

En esta sección se describen las opciones de configuración disponibles para este enlace, que depende de la versión del runtime y de la extensión.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

La configuración clientRetryOptions solo se aplica a las interacciones con el servicio Service Bus. No afectan a los reintentos de las ejecuciones de funciones. Para obtener más información, vea Reintentos.

Propiedad Valor predeterminado Descripción
mode Exponential Enfoque que se debe usar para calcular los retrasos de reintento. El modo exponencial predeterminado aplica un retraso a los reintentos en función de una estrategia de interrupción, en la que cada intento aumenta la duración que espera antes de volver a intentarlo. El modo Fixed reintenta la operación a intervalos fijos, donde cada retraso tiene una duración uniforme.
tryTimeout 00:01:00 Duración máxima que se debe esperar para una operación por intento.
delay 00:00:00.80 Factor de retraso o de interrupción que se aplicará entre reintentos.
maxDelay 00:01:00 Retraso máximo para permitir entre los reintentos.
maxRetries 3 Número máximo de reintentos antes de considerar que hay un error en la operación asociada.
prefetchCount 0 Obtiene o establece el número de mensajes que el destinatario del mensaje puede solicitar simultáneamente.
transportType amqpTcp El protocolo y el transporte que se usan para comunicarse con Service Bus. Opciones disponibles: amqpTcp, amqpWebSockets.
webProxy N/D Proxy que se usará para comunicarse con Service Bus a través de sockets web. Recuerde que no se puede usar un proxy con el transporte amqpTcp.
autoCompleteMessages true Determina si se van a completar automáticamente los mensajes después de la ejecución correcta de la función.
maxAutoLockRenewalDuration 00:05:00 Duración máxima dentro de la cual el bloqueo de mensajes se renovará automáticamente. Esta configuración solo se aplica a las funciones que reciben un único mensaje a la vez.
maxConcurrentCalls 16 Número máximo de llamadas simultáneas a la devolución de llamada que se deben iniciar por instancia escalada. De forma predeterminada, el entorno de ejecución de Functions procesa simultáneamente varios mensajes. Esta configuración solo se usa cuando la propiedad isSessionsEnabled o el atributo en el desencadenador se establece en false. Esta configuración solo se aplica a las funciones que reciben un único mensaje a la vez.
maxConcurrentSessions 8 Número máximo de sesiones que se puede administrar simultáneamente por instancia con escala. Esta configuración solo se usa cuando la propiedad isSessionsEnabled o el atributo en el desencadenador se establece en true. Esta configuración solo se aplica a las funciones que reciben un único mensaje a la vez.
maxMessageBatchSize 1000 Número máximo de mensajes que se pasarán a cada llamada de función. Este ajuste solo se aplica a las funciones que reciben un lote de mensajes.
minMessageBatchSize1 1 Número mínimo de mensajes deseados en un lote. El número mínimo solo se aplica cuando la función recibe varios mensajes y debe ser menor que maxMessageBatchSize.
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 maxBatchWaitTime haya transcurrido.
maxBatchWaitTime1 00:00:30 Intervalo máximo que el desencadenador debe esperar para rellenar un lote antes de invocar la función. El tiempo de espera solo se tiene en cuenta cuando minMessageBatchSize es mayor que 1 y se ignora en caso contrario. Si hay menos de minMessageBatchSize mensajes 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 el 50 % de la duración del bloqueo del mensaje de entidad, lo que significa que el máximo permitido es de 2 minutos y 30 segundos. De lo contrario, puede obtener excepciones de bloqueo.

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.
sessionIdleTimeout N/D Cantidad máxima de tiempo que se esperará a que se reciba un mensaje para la sesión activa actualmente. Una vez transcurrido este tiempo, se cerrará la sesión y la función intentará procesar otra sesión.
enableCrossEntityTransactions false Si se habilitan o no las transacciones que abarcan varias entidades en un espacio de nombres de Service Bus.

1 El uso de minMessageBatchSize y maxBatchWaitTime requiere la versión v5.10.0 del paquete Microsoft.Azure.WebJobs.Extensions.ServiceBus o una versión posterior.

Pasos siguientes