Compartir vía

Introducción al desencadenador y enlaces de Azure Queue Storage para Azure Functions

  • Artículo

Azure Functions puede ejecutarse a medida que se crean nuevos mensajes de Azure Queue Storage y puede escribir mensajes de cola dentro de una función.

Acción Tipo
Ejecución de una función cuando cambian los datos de Queue Storage Desencadenador
Escritura de mensajes de Queue Storage 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 permite enlazar a tipos de Azure.Storage.Queues.

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.

Mediante la CLI de .NET:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

Nota

Azure Blobs, Azure Queues y Azure Tables ahora usan extensiones diferentes y se les hace referencia por separado. Por ejemplo, para usar los desencadenadores y enlaces de los tres servicios en la aplicación en un proceso aislado de .NET, debe agregar los siguientes paquetes al proyecto:

Antes, las extensiones se distribuían juntas como Microsoft.Azure.Functions.Worker.Extensions.Storage, versión 4.x. Este mismo paquete también tiene una versión 5.x que hace referencia solo a los paquetes divididos para blobs y colas. Al actualizar las versiones anteriores de las referencias del paquete, es posible que tenga que hacer referencia también al nuevo paquete NuGet Microsoft.Azure.Functions.Worker.Extensions.Tables. Además, al hacer referencia a estos paquetes divididos más recientes, asegúrese de que no hace referencia a una versión anterior del paquete de almacenamiento combinado, ya que esto provocaría conflictos por las dos definiciones de los mismos enlaces.

Instalación del conjunto

El enlace de almacenamiento de Blob 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 en versión preliminar 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. La compatibilidad con el enlace a tipos de Azure.Storage.Queues está en versión preliminar.

Desencadenador de cola

El desencadenador de cola puede enlazarse a los siguientes tipos:

Tipo Descripción
string Contenido del mensaje como una cadena. Se usa cuando el mensaje es de texto simple.
byte[] Bytes del mensaje.
Tipos serializables con JSON Cuando un mensaje de cola contiene datos JSON, Functions intenta deserializar los datos JSON en un tipo de objeto CLR sin formato (POCO).
QueueMessage1 Mensaje.
BinaryData1 Bytes del mensaje.

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

Enlace de salida de la cola

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

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

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

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

Para otros escenarios de salida, cree y use queueClient con otros tipos de Azure.Storage.Queues 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 en las versiones 2.x y posteriores. La configuración del archivo host.json se aplica a todas las funciones de una instancia de la aplicación de funciones. El siguiente archivo host.json de ejemplo contiene solo la configuración de la versión 2.x+ para este enlace. Para obtener más información sobre la configuración de la aplicación de funciones en las versiones 2.x y posteriores, consulte la referencia de host.json para Azure Functions.

Nota

Para obtener una referencia de host.json en Functions 1.x, consulte la referencia de host.json para Azure Functions, versión 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
Propiedad Valor predeterminado Descripción
maxPollingInterval 00:01:00 Intervalo máximo entre sondeos de la cola. El intervalo mínimo es 00:00:00.100 (100 milisegundos). Los intervalos se incrementan hasta maxPollingInterval. El valor predeterminado de maxPollingInterval es 00:01:00 (1 minuto). maxPollingInterval no debe ser menor que 00:00:00.100 (100 milisegundos). En Functions 2.x y versiones posteriores, el tipo de datos es TimeSpan. En Functions 1.x, se expresa en milisegundos.
visibilityTimeout 00:00:00 Intervalo de tiempo entre los reintentos cuando se produce un error al procesar un mensaje.
batchSize 16 El número de mensajes en cola que el runtime de Functions recupera simultáneamente y procesa en paralelo. Cuando el número que se está procesando llega a newBatchThreshold el runtime obtiene otro lote y empieza a procesar esos mensajes. Por lo tanto, el número máximo de mensajes simultáneos que se procesan por función es batchSize más newBatchThreshold. Este límite se aplica por separado a cada función desencadenada por la cola.

Si desea evitar la ejecución en paralelo de los mensajes de una cola, puede establecer batchSize en 1. Sin embargo, este valor elimina la simultaneidad siempre y cuando la aplicación de funciones se ejecute en una única máquina virtual (VM). Si la aplicación de función se escala horizontalmente a varias máquinas virtuales, cada una de ellas podría ejecutar una instancia de cada función desencadenada por la cola.

El valor máximo de batchSize es 32.
maxDequeueCount 5 Número de veces que se intenta procesar un mensaje antes de pasarlo a la cola de mensajes dudosos.
newBatchThreshold N*batchSize/2 Siempre que el número de mensajes que se procesan simultáneamente llega a este número, el runtime recupera otro lote.

N representa el número de vCPU disponibles al ejecutarse en planes Premium o App Service. Su valor es 1 para el plan de consumo.
messageEncoding base64 Esta opción solo está disponible en la versión de extensión 5.0.0 y posteriores. Representa el formato de codificación de los mensajes. Los valores válidos son base64 y none.

Pasos siguientes