Desencadenador de Azure Queue Storage para Azure Functions
El desencadenador de Queue Storage ejecuta una función a medida que se agregan mensajes a Azure Queue Storage.
Las decisiones de escalado de Azure Queue para los planes de Consumo y Premium se realizan a través del escalado basado en el destino. Para obtener más información, consulte Escalado basado en el destino.
Importante
En este artículo se usan pestañas para admitir varias versiones del modelo de programación de Node.js. El modelo v4 está disponible de forma general y está diseñado para que los desarrolladores de JavaScript y TypeScript tengan una experiencia más flexible e intuitiva. Para más detalles acerca de cómo funciona el modelo v4, consulte la Guía para desarrolladores de Node.js de Azure Functions. Para más información sobre las diferencias entre v3 y v4, consulte la Guía de migración.
Azure Functions admite dos modelos de programación para Python. La forma en que defina los enlaces depende del modelo de programación seleccionado.
El modelo de programación de Python v2 permite definir enlaces mediante decoradores directamente en el código de función de Python. Para más información, consulte la Guía para desarrolladores de Python.
En este artículo se admiten los modelos de programación.
Ejemplo
Use el desencadenador de cola para iniciar una función cuando se reciba un nuevo elemento en una cola. El mensaje de la cola se proporciona a modo de entrada para la función.
Se puede crear una función C# mediante uno de los siguientes modos de C#:
- Modelo de trabajo aislado: función compilada en C# que se ejecuta en un proceso trabajador aislado del tiempo de ejecución. Se requiere un proceso de trabajo aislado para admitir funciones de C# ejecutándose en versiones de .NET que son y no son LTS y .NET Framework. Las extensiones para las funciones de proceso de trabajo aisladas usan espacios de nombres
Microsoft.Azure.Functions.Worker.Extensions.*. - Modelo en curso: función C# compilada que se ejecuta en el mismo proceso que el tiempo de ejecución de 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#. Las extensiones para funciones en proceso utilizan espacios de nombres
Microsoft.Azure.WebJobs.Extensions.*.
Importante
El soporte técnico del modelo en proceso finalizará el 10 de noviembre de 2026. Se recomienda encarecidamente migrar las aplicaciones al modelo de trabajo aislado para obtener soporte técnico completo.
En el ejemplo siguiente se muestra una función de C# que sondea la cola input-queue y escribe varios mensajes a una cola de salida cada vez que se procesa un elemento de cola.
[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
// Use a string array to return more than one message.
string[] messages = {
$"Album name = {myQueueItem.Name}",
$"Album songs = {myQueueItem.Songs}"};
_logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);
// Queue Output messages
return messages;
}
En el siguiente ejemplo de Java se muestra una función de desencadenador de cola de almacenamiento que registra el mensaje desencadenado que se pone en la cola myqueuename.
@FunctionName("queueprocessor")
public void run(
@QueueTrigger(name = "msg",
queueName = "myqueuename",
connection = "myconnvarname") String message,
final ExecutionContext context
) {
context.getLogger().info(message);
}
En el ejemplo siguiente se muestra una función de TypeScript de desencadenador de cola. La función sondea la cola myqueue-items y escribe un registro cada vez que se procesa un elemento de cola.
import { app, InvocationContext } from '@azure/functions';
export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
context.log('Storage queue function processed work item:', queueItem);
context.log('expirationTime =', context.triggerMetadata.expirationTime);
context.log('insertionTime =', context.triggerMetadata.insertionTime);
context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
context.log('id =', context.triggerMetadata.id);
context.log('popReceipt =', context.triggerMetadata.popReceipt);
context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
handler: storageQueueTrigger1,
});
En la sección de uso se explica queueItem. En la sección de metadatos del mensaje se explican el resto de variables que se muestran.
En el ejemplo siguiente se muestra una función de JavaScript de desencadenador de cola. La función sondea la cola myqueue-items y escribe un registro cada vez que se procesa un elemento de cola.
const { app } = require('@azure/functions');
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
handler: (queueItem, context) => {
context.log('Storage queue function processed work item:', queueItem);
context.log('expirationTime =', context.triggerMetadata.expirationTime);
context.log('insertionTime =', context.triggerMetadata.insertionTime);
context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
context.log('id =', context.triggerMetadata.id);
context.log('popReceipt =', context.triggerMetadata.popReceipt);
context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
},
});
En la sección de uso se explica queueItem. En la sección de metadatos del mensaje se explican el resto de variables que se muestran.
En el ejemplo siguiente se muestra cómo leer un mensaje en cola pasado a una función a través de un desencadenador.
Un desencadenador de cola de almacenamiento se define en el archivo function.json, donde type se establece en queueTrigger.
{
"bindings": [
{
"name": "QueueItem",
"type": "queueTrigger",
"direction": "in",
"queueName": "messages",
"connection": "MyStorageConnectionAppSetting"
}
]
}
El código del archivo Run.ps1 declara un parámetro como $QueueItem, que permite leer el mensaje de la cola en la función.
# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)
# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"
En el ejemplo siguiente se muestra cómo leer un mensaje en cola pasado a una función a través de un desencadenador. El ejemplo depende de si usas el modelo de programación de Python v1 o v2.
import logging
import azure.functions as func
app = func.FunctionApp()
@app.function_name(name="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
connection="storageAccountConnectionString") # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
connection="storageAccountConnectionString") # Queue output binding
def test_function(msg: func.QueueMessage,
outputQueueItem: func.Out[str]) -> None:
logging.info('Python queue trigger function processed a queue item: %s',
msg.get_body().decode('utf-8'))
outputQueueItem.set('hello')
Atributos
Las bibliotecas de C# de In-Process y de procesos de trabajo aislados usan el atributo QueueTriggerAttribute para definir la función. En su lugar, el script de C# usa un archivo de configuración function.json como se describe en la Guía de scripting de C#.
En las bibliotecas de clase C#, el constructor del atributo toma el nombre de la cola que debe supervisar, tal como se muestra en el ejemplo siguiente:
[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
En este ejemplo también se muestra cómo establecer la configuración de la cadena de conexión en el propio atributo.
anotaciones
La anotación QueueTrigger proporciona acceso a la cola que desencadena la función. En el ejemplo siguiente, el mensaje de la cola se hace disponible para la función mediante el parámetro message.
package com.function;
import com.microsoft.azure.functions.annotation.*;
import java.util.Queue;
import com.microsoft.azure.functions.*;
public class QueueTriggerDemo {
@FunctionName("QueueTriggerDemo")
public void run(
@QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
final ExecutionContext context
) {
context.getLogger().info("Queue message: " + message);
}
}
| Propiedad | Descripción |
|---|---|
name |
Declara el nombre del parámetro en la firma de la función. Cuando se desencadena la función, el valor de este parámetro tiene el contenido del mensaje de la cola. |
queueName |
Declara el nombre de la cola en la cuenta de almacenamiento. |
connection |
Apunta a la cadena de conexión de la cuenta de almacenamiento. |
Elementos Decorator
Solo se aplica al modelo de programación de Python v2.
Para las funciones de Python v2 definidas mediante decoradores, las siguientes propiedades del decorador de queue_trigger definen el desencadenador de Queue Storage:
| Propiedad | Descripción |
|---|---|
arg_name |
Declara el nombre del parámetro en la firma de la función. Cuando se desencadena la función, el valor de este parámetro tiene el contenido del mensaje de la cola. |
queue_name |
Declara el nombre de la cola en la cuenta de almacenamiento. |
connection |
Apunta a la cadena de conexión de la cuenta de almacenamiento. |
Para las funciones de Python definidas usando function.json, consulta la sección Configuración.
Configuración
Solo se aplica al modelo de programación de Python v1.
En la tabla siguiente se explican las propiedades que puede establecer en el objeto options que se pasa al métodoapp.storageQueue().
| Propiedad | Descripción |
|---|---|
| queueName | Nombre de la cola que se sondea. |
| connection | Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a las colas de Azure. Consulte Conexiones. |
En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json y el atributo QueueTrigger.
| Propiedad de function.json | Descripción |
|---|---|
| type | Se debe establecer en queueTrigger. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal. |
| direction | Solo en el archivo function.json. Se debe establecer en in. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal. |
| name | El nombre de la variable que contiene la carga del elemento de cola en el código de función. |
| queueName | Nombre de la cola que se sondea. |
| connection | Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a las colas de Azure. Consulte Conexiones. |
Consulte la sección de ejemplos para ver ejemplos completos.
Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.
Uso
Nota:
Las funciones esperan una cadena codificada en base64. Cualquier ajuste al tipo de codificación (para preparar los datos como una cadena codificada en base64) debe implementarse en el servicio de llamada.
El uso del desencadenador Queue depende de la versión del paquete de extensión y de la modalidad de C# que se usa en la aplicación de funciones, que puede ser uno de estos modos:
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.
Elija una versión para ver los detalles de utilización del modo y la versión.
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.
La anotación QueueTrigger proporciona acceso al mensaje de la cola que desencadenó la función.
Acceda al mensaje de la cola a través de un parámetro de cadena que coincida con el nombre designado por el parámetro name del enlace en el archivo name.
Puede acceder al mensaje de la cola mediante un parámetro de tipo QueueMessage.
Metadatos
El desencadenador de cola proporciona varias propiedades de metadatos. Estas propiedades se pueden usar como parte de expresiones de enlace en otros enlaces o como parámetros en el código, para los trabajadores del lenguaje que proporcionan este acceso a los metadatos del mensaje.
Las propiedades de metadatos del mensaje son miembros de la clase CloudQueueMessage .
Se puede tener acceso a las propiedades de metadatos del mensaje desde context.triggerMetadata.
Se puede acceder a las propiedades de metadatos del mensaje desde el parámetro pasado $TriggerMetadata .
| Propiedad | Tipo | Descripción |
|---|---|---|
QueueTrigger |
string |
Carga de cola (si hay una cadena válida). Si la carga del mensaje de la cola es una cadena, QueueTrigger tiene el mismo valor que la variable denominada por la propiedad name en QueueTrigger. |
DequeueCount |
long |
Es el número de veces que se ha quitado de la cola este mensaje. |
ExpirationTime |
DateTimeOffset |
Es la hora de expiración del mensaje. |
Id |
string |
Es el identificador del mensaje de cola. |
InsertionTime |
DateTimeOffset |
Es la hora en la que el mensaje se agregó a la cola. |
NextVisibleTime |
DateTimeOffset |
Es la siguiente hora a la que será visible el mensaje. |
PopReceipt |
string |
Es la confirmación de extracción del mensaje. |
Se puede acceder a las siguientes propiedades de metadatos de mensaje desde el parámetro de enlace pasado (msg en ejemplos anteriores).
| Propiedad | Descripción |
|---|---|
body |
Carga de cola como una cadena. |
dequeue_count |
Es el número de veces que se ha quitado de la cola este mensaje. |
expiration_time |
Es la hora de expiración del mensaje. |
id |
Es el identificador del mensaje de cola. |
insertion_time |
Es la hora en la que el mensaje se agregó a la cola. |
time_next_visible |
Es la siguiente hora a la que será visible el mensaje. |
pop_receipt |
Es la confirmación de extracción del mensaje. |
Conexiones
La propiedad connection es una referencia a la configuración del entorno que especifica cómo se debe conectar la aplicación a las colas de Azure. Puede especificar lo siguiente:
- El nombre de una configuración de la aplicación que contiene una cadena de conexión.
- El nombre de un prefijo compartido para varias configuraciones de la aplicación que juntas definen una conexión basada en identidad.
Si el valor configurado es tanto una coincidencia exacta de una única configuración como una coincidencia de prefijo de otras configuraciones, se usa la coincidencia exacta.
Cadena de conexión
Para obtener una cadena de conexión, siga los pasos mostrados en Administración de las claves de acceso de la cuenta de almacenamiento.
La cadena de conexión debe almacenarse en una configuración de la aplicación con un nombre que coincida con el valor especificado por la propiedad connection de la configuración de enlace.
Si el nombre de la configuración de aplicación comienza con "AzureWebJobs", puede especificar solo el resto del nombre aquí. Por ejemplo, si establece connection en "MyStorage", el tiempo de ejecución de Functions busca una configuración de aplicación denominada "AzureWebJobsMyStorage". Si deja connection vacío, el tiempo de ejecución de Functions usa la cadena de conexión de Storage predeterminada en la configuración de la aplicación denominada AzureWebJobsStorage.
Conexiones basadas en identidades
Si usa la versión 5.x o posterior de la extensión (agrupación 3.x o superior para non-.NET pilas de lenguaje), en lugar de usar un cadena de conexión con un secreto, puede hacer que la aplicación use una identidad de Microsoft Entra. Para usar una identidad, se define la configuración con un prefijo común que se asigna a la propiedad de connection en la configuración de desencadenador y enlace.
Si va a establecer connection en "AzureWebJobsStorage", consulte Conexión al almacenamiento de host con una identidad. Para todas las demás conexiones, la extensión requiere las siguientes propiedades:
| Propiedad | Plantilla de variable de entorno | Descripción | Valor de ejemplo |
|---|---|---|---|
| URI del servicio Queue | <CONNECTION_NAME_PREFIX>__queueServiceUri1 |
Uri del plano de datos del servicio de cola al que se conecta, mediante el esquema HTTPS. | https://<storage_account_name>.queue.core.windows.net |
1 <CONNECTION_NAME_PREFIX>__serviceUri se puede usar como alias. Si se proporcionan ambos formularios, se usa el formulario queueServiceUri. El formulario serviceUri no se puede usar cuando la configuración de conexión general se va a usar en blobs, colas o tablas.
Se pueden establecer otras propiedades para personalizar la conexión. Consulte Propiedades comunes para conexiones basadas en identidades.
Cuando se hospeda en el servicio de Azure Functions, las conexiones basadas en identidades usan una identidad administrada. La identidad asignada por el sistema se usa de manera predeterminada, aunque se puede especificar una identidad asignada por el usuario con las propiedades credential y clientID. Tenga en cuenta que no se admite la configuración de una identidad asignada por el usuario con un identificador de recurso. Cuando se ejecuta en otros contextos, como el de desarrollo local, se usa en su lugar la identidad del desarrollador, aunque se puede personalizar. Consulte Desarrollo local con conexiones basadas en identidades.
Concesión de permiso a la identidad
Cualquier identidad que se utilice debe tener permisos para realizar las acciones previstas. Para la mayoría de los servicios de Azure, esto significa que debe asignar un rol en Azure RBAC mediante roles integrados o personalizados que proporcionen esos permisos.
Importante
Es posible que el servicio de destino muestre algunos permisos que no son necesarios para todos los contextos. Siempre que sea posible, respete el principio de privilegios mínimos y conceda solo los privilegios necesarios a la identidad. Por ejemplo, si la aplicación solo necesita poder leer desde un origen de datos, use un rol que solo tenga permiso de lectura. Sería inadecuado asignar un rol que también permita escribir en ese servicio, ya que sería un permiso excesivo para una operación de lectura. De forma similar, le interesa asegurarse de que la asignación de roles esté limitada solo a los recursos que se deben leer.
Deberá crear una asignación de roles que proporcione acceso a la cola en tiempo de ejecución. Los roles de administración, como propietario no son suficientes. En la tabla siguiente se muestran los roles integrados que se recomiendan al usar la extensión Queue Storage en funcionamiento normal. Puede que la aplicación precise permisos adicionales en función del código que escriba.
| Tipo de enlace | Roles integrados de ejemplo |
|---|---|
| Desencadenador | Lector de datos de la cola de Storage Blob, Procesador de mensajes de datos de Queue Storage |
| Enlace de salida | Colaborador de datos de la cola de Storage Blob, Remitente de mensajes de datos de Queue Storage |
Mensajes dudosos
Si se produce un error en una función del desencadenador de cola, Azure Functions volverá a intentar esa función hasta cinco veces para un determinado mensaje en la cola, incluido el primer intento. Si los cinco intentos son infructuosos, Functions agregará un mensaje a la cola denominada <originalqueuename>-poison. Puede escribir una función para procesar los mensajes desde la cola de mensajes dudosos registrándolos o enviando una notificación indicando que se necesita atención manual.
Para controlar manualmente los mensajes dudosos, compruebe el elemento dequeueCount del mensaje de la cola.
Inspección y bloqueo
El patrón peek-lock se produce automáticamente para los desencadenadores de cola, mediante la mecánica de visibilidad proporcionada por el servicio de almacenamiento. A medida que la función desencadenada quita los mensajes, se marcan como invisibles. La ejecución de una función desencadenada por cola puede tener uno de estos resultados en el mensaje de la cola:
- La ejecución de la función se completa correctamente y el mensaje se elimina de la cola.
- Se produce un error en la ejecución de la función y el host de Functions actualiza la visibilidad del mensaje en función de la
visibilityTimeoutconfiguración del archivo host.json. El tiempo de espera de visibilidad predeterminado es cero, lo que significa que el mensaje vuelve a aparecer inmediatamente en la cola para volver a procesarlo. Use lavisibilityTimeoutconfiguración para retrasar el reprocesamiento de mensajes que no se pueden procesar. Esta configuración de tiempo de espera se aplica a todas las funciones desencadenadas por la cola en la aplicación de funciones. - El host de Functions se bloquea durante la ejecución de la función. Cuando se produce este evento poco común, el host no puede aplicar al
visibilityTimeoutmensaje que se está procesando. En su lugar, el mensaje se deja con el tiempo de espera predeterminado de 10 minutos establecido por el servicio de almacenamiento. Después de 10 minutos, el mensaje vuelve a aparecer en la cola para volver a procesarlo. Este tiempo de espera predeterminado definido por el servicio no se puede cambiar.
Algoritmo de sondeo
El desencadenador de cola implementa un algoritmo de interrupción exponencial aleatorio para reducir el efecto del sondeo de cola inactiva en los costos de transacción de almacenamiento.
El algoritmo utiliza la siguiente lógica:
- Cuando se encuentra un mensaje, el tiempo de ejecución espera 100 milisegundos y, a continuación, comprueba si hay otro mensaje.
- Si no encuentra ninguno, espera unos 200 milisegundos antes de volver a intentarlo.
- Después de varios intentos fallidos para obtener un mensaje de la cola, el tiempo de espera sigue aumentando hasta que alcanza el tiempo de espera máximo, predeterminado en un minuto.
- El tiempo de espera máximo se configura mediante la propiedad
maxPollingIntervalen elmaxPollingInterval.
Durante el desarrollo local, el intervalo de sondeo máximo tiene como valor predeterminado dos segundos.
Nota:
Respecto a la facturación al hospedar aplicaciones de función en el plan de consumo, no se le cobrará por el tiempo empleado en el sondeo del runtime.
Simultaneidad
Cuando hay varios mensajes en cola en espera, el desencadenador de cola recupera un lote de mensajes e invoca instancias de función de manera simultánea para procesarlas. De manera predeterminada, el tamaño de lote es 16. Cuando el número que se está procesando llega a 8, el entorno en tiempo de ejecución 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 en una máquina virtual es 24. Este límite se aplica por separado a cada función desencadenada por la cola en cada máquina virtual. Si la aplicación de funciones se escala horizontalmente a varias máquinas virtuales, cada máquina virtual espera desencadenadores e intenta ejecutar funciones. Por ejemplo, si una aplicación de función se escala horizontalmente a 3 máquinas virtuales, el número máximo predeterminado de instancias simultáneas de una función desencadenada por la cola es 72.
El tamaño de lote y el umbral para obtener un lote nuevo se configuran en el archivo host.json. Si quiere minimizar la ejecución en paralelo para las funciones desencadenadas por la cola en una aplicación de función, puede establecer el tamaño de lote en 1. Este valor solo elimina la simultaneidad siempre y cuando la aplicación de función se ejecute en una única máquina virtual (VM).
El desencadenador de cola impide automáticamente que una función procese un mensaje de cola varias veces al mismo tiempo.
Propiedades de host.json
El archivo host.json contiene opciones de configuración que controlan el comportamiento de desencadenador de cola. Consulte la sección de configuración de host.json para más información sobre las opciones de configuración disponibles.