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.

v2

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.

v1

El modelo de programación de Python v1 requiere que defina enlaces en un archivo function.json independiente en la carpeta de funciones. 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.

Modelo de trabajo aislado

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.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Modelo de proceso

En el ejemplo siguiente se muestra una función de C# que sondea la cola myqueue-items y escribe un registro cada vez que se procesa un elemento de cola.

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

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);
}

Model v4

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.

Modelo v3

Los ejemplos de TypeScript no están documentados para el modelo v3.

Model v4

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.

Modelo v3

En el ejemplo siguiente se muestra un enlace de desencadenador de cola de un archivo function.json y una función de JavaScript que usa el enlace. La función sondea la cola myqueue-items y escribe un registro cada vez que se procesa un elemento de cola.

Este es el archivo function.json:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

En la sección de configuración se explican estas propiedades.

Nota

El nombre del parámetro se muestra como context.bindings.<name> en el código JavaScript que contiene la carga del elemento de cola. Esta carga también se pasa como segundo parámetro a la función.

Este es el código de JavaScript:

module.exports = async function (context, message) {
    context.log('Node.js queue trigger function processed work item', message);
    // OR access using context.bindings.<name>
    // context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id =', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
};

En la sección acerca del uso se explica myQueueItem, que recibe el nombre de la propiedad name de function.json. 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.

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')

v1

Un desencadenador de cola de almacenamiento se define en function.json, donde type está establecido en queueTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

El código _init_.py declara un parámetro como func.QueueMessage, lo que permite leer el mensaje de la cola en la función.

import logging
import json

import azure.functions as func

def main(msg: func.QueueMessage):
    logging.info('Python queue trigger function processed a queue item.')

    result = json.dumps({
        'id': msg.id,
        'body': msg.get_body().decode('utf-8'),
        'expiration_time': (msg.expiration_time.isoformat()
                            if msg.expiration_time else None),
        'insertion_time': (msg.insertion_time.isoformat()
                           if msg.insertion_time else None),
        'time_next_visible': (msg.time_next_visible.isoformat()
                              if msg.time_next_visible else None),
        'pop_receipt': msg.pop_receipt,
        'dequeue_count': msg.dequeue_count
    })

    logging.info(result)

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#.

Modelo de trabajo aislado

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.

Modelo de proceso

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:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem, 
    ILogger log)
{
    ...
}

Puede establecer la propiedad Connection para especificar la configuración de aplicación que contiene la cadena de conexión de la cuenta de almacenamiento, tal como se muestra en el ejemplo siguiente:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
    ILogger log)
{
    ....
}

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.

Model v4

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.

Model v3

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json.

Propiedad	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.

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:

Modelo de trabajo aislado

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.

Biblioteca de clases en proceso

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

Elija una versión para ver los detalles de utilización del modo y la versión.

Extensión 5.x+

Acceda a los datos de mensaje mediante un parámetro de método, como string paramName. paramName es el valor especificado en QueueTriggerAttribute. Puede enlazar a cualquiera de los siguientes tipos:

• Objeto CLR de .NET sin formato (POCO)
• string
• byte[]
• QueueMessage

Al enlazar a un objeto, el tiempo de ejecución de Functions intenta deserializar una carga JSON en una instancia de una clase arbitraria definida en el código. Para obtener ejemplos de uso de QueueMessage, consulte el repositorio de GitHub de la extensión.

Aunque el atributo toma una propiedad Connection, también puede usar el atributo Connection para especificar una conexión de cuenta de almacenamiento. Puede hacerlo cuando necesite usar una cuenta de almacenamiento diferente a otras funciones de la biblioteca. El constructor toma el nombre de una configuración de aplicación que contiene una cadena de conexión de almacenamiento. El atributo se puede aplicar en el nivel de clase, método o parámetro. En el ejemplo siguiente se muestran el nivel de clase y de método:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

La cuenta de almacenamiento que se debe usar se determina en el orden siguiente:

• La propiedad Connection del atributo de enlace o desencadenador.
• El atributo StorageAccount aplicado al mismo parámetro que el atributo de enlace o desencadenador.
• El atributo StorageAccount aplicado a la función.
• El atributo StorageAccount aplicado a la clase.
• La cuenta de almacenamiento predeterminada de la aplicación de funciones, que se define en la configuración de la aplicación AzureWebJobsStorage.

Extensión 2.x+

Acceda a los datos de mensaje mediante un parámetro de método, como string paramName. paramName es el valor especificado en QueueTriggerAttribute. Puede enlazar a cualquiera de los siguientes tipos:

• Objeto CLR convencional (POCO)
• string
• byte[]
• CloudQueueMessage

Al enlazar a un objeto, el tiempo de ejecución de Functions intenta deserializar una carga JSON en una instancia de una clase arbitraria definida en el código. Si intenta enlazar a CloudQueueMessage y obtiene un mensaje de error, asegúrese de que tiene una referencia a la versión correcta del SDK de Storage.

Aunque el atributo toma una propiedad Connection, también puede usar el atributo Connection para especificar una conexión de cuenta de almacenamiento. Puede hacerlo cuando necesite usar una cuenta de almacenamiento diferente a otras funciones de la biblioteca. El constructor toma el nombre de una configuración de aplicación que contiene una cadena de conexión de almacenamiento. El atributo se puede aplicar en el nivel de clase, método o parámetro. En el ejemplo siguiente se muestran el nivel de clase y de método:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

La cuenta de almacenamiento que se debe usar se determina en el orden siguiente:

• La propiedad Connection del atributo de enlace o desencadenador.
• El atributo StorageAccount aplicado al mismo parámetro que el atributo de enlace o desencadenador.
• El atributo StorageAccount aplicado a la función.
• El atributo StorageAccount aplicado a la clase.
• La cuenta de almacenamiento predeterminada de la aplicación de funciones, que se define en la configuración de la aplicación AzureWebJobsStorage.

Extensión 5.x+

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.

¹ 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.

Extensión 2.x+

Las versiones anteriores de extensiones del proceso de trabajo aislado solo admiten el enlace a cadenas. Hay más opciones disponibles para la extensión 5.x+.

La anotación QueueTrigger proporciona acceso al mensaje de la cola que desencadenó la función.

Model v4

Acceda al elemento de cola como primer argumento de la función. Si la carga es JSON, el valor se deserializa en un objeto.

Modelo v3

Acceda al elemento de cola mediante context.bindings.<NAME>, donde <NAME> coincide con el valor definido en function.json. Si la carga es JSON, el valor se deserializa en un objeto.

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

¹ <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 visibilityTimeout configuració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 la visibilityTimeout configuració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 visibilityTimeout mensaje 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 maxPollingInterval en el maxPollingInterval.

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.

Pasos siguientes

• Escritura de mensajes de Queue Storage (enlace de salida)