Enlaces de Azure Queue Storage para Azure FunctionsAzure Queue storage bindings for Azure Functions

En este artículo se explica cómo trabajar con enlaces de Azure Queue Storage en Azure Functions.This article explains how to work with Azure Queue storage bindings in Azure Functions. Azure Functions admite enlaces de salida y desencadenador para colas.Azure Functions supports trigger and output bindings for queues.

Esta es la información de referencia para desarrolladores de Azure Functions.This is reference information for Azure Functions developers. Si está familiarizado con Azure Functions, comience con los siguientes recursos:If you're new to Azure Functions, start with the following resources:

Paquetes: Functions 1.xPackages - Functions 1.x

Los enlaces de almacenamiento de Queue se proporcionan en el paquete NuGet Microsoft.Azure.WebJobs, versión 2.x.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs NuGet package, version 2.x. El código fuente del paquete se encuentra en el repositorio azure-webjobs-sdk de GitHub.Source code for the package is in the azure-webjobs-sdk GitHub repository.

En todos los entornos de desarrollo, se proporciona automáticamente compatibilidad para este enlace.Support for this binding is automatically provided in all development environments. No tiene que instalar el paquete manualmente ni que registrar la extensión.You don't have to manually install the package or register the extension.

Versión de SDK de Azure Storage en Functions 1.xAzure Storage SDK version in Functions 1.x

En Functions 1.x, los desencadenadores y enlaces de Storage usan la versión 7.2.1 del SDK de Azure Storage (paquete NuGet WindowsAzure.Storage)In Functions 1.x, the Storage triggers and bindings use version 7.2.1 of the Azure Storage SDK (WindowsAzure.Storage NuGet package). Si hace referencia a una versión diferente del SDK de Storage y enlaza a un tipo de SDK de Storage en la signatura de función, el runtime de Functions puede notificar que no se puede enlazar con ese tipo.If you reference a different version of the Storage SDK, and you bind to a Storage SDK type in your function signature, the Functions runtime may report that it can't bind to that type. La solución es asegurarse de que el proyecto hace referencia a WindowsAzure.Storage 7.2.1.The solution is to make sure your project references WindowsAzure.Storage 7.2.1.

Paquetes: Functions 2.xPackages - Functions 2.x

Los enlaces de almacenamiento de Queue se proporcionan en el paquete NuGet Microsoft.Azure.WebJobs.Extensions.Storage, versión 3.x.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Storage NuGet package, version 3.x. El código fuente del paquete se encuentra en el repositorio azure-webjobs-sdk de GitHub.Source code for the package is in the azure-webjobs-sdk GitHub repository.

En la siguiente tabla se explica cómo agregar compatibilidad para este enlace en cada entorno de desarrollo.The following table tells how to add support for this binding in each development environment.

Entorno de desarrolloDevelopment environment Para agregar compatibilidad enTo add support in
Functions 2.xFunctions 2.x
Desarrollo local: biblioteca de clases C#Local development - C# class library Instalación del paqueteInstall the package
Desarrollo local: script de C#, JavaScript, F#, Java y PythonLocal development - C# script, JavaScript, F#, Java and Python Registro de la extensiónRegister the extension
Desarrollo con PortalPortal development Instalación al agregar el enlace de salidaInstall when adding output binding

Para saber cómo actualizar las extensiones de enlace existentes en el portal sin tener que volver a publicar su proyecto de aplicación de función, consulte Actualización de las extensiones.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

EncodingEncoding

Las funciones esperan una cadena codificada en base64.Functions expect a base64 encoded string. Cualquier ajuste al tipo de codificación (para preparar los datos como una cadena codificada en base64) debe implementarse en el servicio de llamada.Any adjustments to the encoding type (in order to prepare data as a base64 encoded string) need to be implemented in the calling service.

DesencadenadorTrigger

Use el desencadenador de cola para iniciar una función cuando se reciba un nuevo elemento en una cola.Use the queue trigger to start a function when a new item is received on a queue. El mensaje de la cola se proporciona a modo de entrada para la función.The queue message is provided as input to the function.

Desencadenador: ejemploTrigger - example

Vea el ejemplo específico del lenguaje:See the language-specific example:

Desencadenador: ejemplo de C#Trigger - C# example

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.The following example shows a C# function that polls the myqueue-items queue and writes a log each time a queue item is processed.

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

Desencadenador: ejemplo de script de C#Trigger - C# script example

En el ejemplo siguiente se muestra un enlace de desencadenador de cola de un archivo function.json y código de script de C# (.csx) que usa el enlace.The following example shows a queue trigger binding in a function.json file and C# script (.csx) code that uses the binding. La función sondea la cola myqueue-items y escribe un registro cada vez que se procesa un elemento de cola.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Este es el archivo function.json:Here's the function.json file:

{
    "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.The configuration section explains these properties.

Este es el código de script de C#:Here's the C# script code:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.Extensions.Logging;
using Microsoft.WindowsAzure.Storage.Queue;
using System;

public static void Run(CloudQueueMessage myQueueItem, 
    DateTimeOffset expirationTime, 
    DateTimeOffset insertionTime, 
    DateTimeOffset nextVisibleTime,
    string queueTrigger,
    string id,
    string popReceipt,
    int dequeueCount,
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem.AsString}\n" +
        $"queueTrigger={queueTrigger}\n" +
        $"expirationTime={expirationTime}\n" +
        $"insertionTime={insertionTime}\n" +
        $"nextVisibleTime={nextVisibleTime}\n" +
        $"id={id}\n" +
        $"popReceipt={popReceipt}\n" + 
        $"dequeueCount={dequeueCount}");
}

En la sección acerca del uso se explica myQueueItem, que recibe el nombre de la propiedad name de function.json.The usage section explains myQueueItem, which is named by the name property in function.json. En la sección de metadatos del mensaje se explican el resto de variables que se muestran.The message metadata section explains all of the other variables shown.

Desencadenador: ejemplo de JavaScriptTrigger - JavaScript example

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.The following example shows a queue trigger binding in a function.json file and a JavaScript function that uses the binding. La función sondea la cola myqueue-items y escribe un registro cada vez que se procesa un elemento de cola.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Este es el archivo function.json:Here's the function.json file:

{
    "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.The configuration section explains these properties.

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.The name parameter reflects as context.bindings.<name> in the JavaScript code which contains the queue item payload. Esta carga también se pasa como segundo parámetro a la función.This payload is also passed as the second parameter to the function.

Este es el código de JavaScript:Here's the JavaScript code:

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);
    context.done();
};

En la sección acerca del uso se explica myQueueItem, que recibe el nombre de la propiedad name de function.json.The usage section explains myQueueItem, which is named by the name property in function.json. En la sección de metadatos del mensaje se explican el resto de variables que se muestran.The message metadata section explains all of the other variables shown.

Desencadenador: ejemplo de JavaTrigger - Java example

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.The following Java example shows a storage queue trigger functions which logs the triggered message placed into queue myqueuename.

@FunctionName("queueprocessor")
public void run(
   @QueueTrigger(name = "msg",
                  queueName = "myqueuename",
                  connection = "myconnvarname") String message,
    final ExecutionContext context
) {
    context.getLogger().info(message);
}

Ejemplo de desencadenador de PythonTrigger - Python example

En el ejemplo siguiente se muestra cómo leer un mensaje en cola pasado a una función a través de un desencadenador.The following example demonstrates how to read a queue message passed to a function via a trigger.

Un desencadenador de cola de almacenamiento se define en function.json, donde type está establecido en queueTrigger.A Storage queue trigger is defined in function.json where type is set to 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.ServiceBusMessage, que permite leer el mensaje de la cola en la función.The code _init_.py declares a parameter as func.ServiceBusMessage which allows you to read the queue message in your function.

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)

Desencadenador: atributosTrigger - attributes

Para bibliotecas de clases de C#, use los siguientes atributos para configurar un desencadenador de cola:In C# class libraries, use the following attributes to configure a queue trigger:

  • QueueTriggerAttributeQueueTriggerAttribute

    El constructor del atributo toma el nombre de la cola que debe supervisar, tal como se muestra en el ejemplo siguiente:The attribute's constructor takes the name of the queue to monitor, as shown in the following example:

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

    Puede establecer la propiedad Connection para especificar la cuenta de almacenamiento que se usará, tal como se muestra en el ejemplo siguiente:You can set the Connection property to specify the storage account to use, as shown in the following example:

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

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

  • StorageAccountAttributeStorageAccountAttribute

    Proporciona otra manera de especificar la cuenta de almacenamiento que se debe usar.Provides another way to specify the storage account to use. El constructor toma el nombre de una configuración de aplicación que contiene una cadena de conexión de almacenamiento.The constructor takes the name of an app setting that contains a storage connection string. El atributo se puede aplicar en el nivel de clase, método o parámetro.The attribute can be applied at the parameter, method, or class level. En el ejemplo siguiente se muestran el nivel de clase y de método:The following example shows class level and method level:

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

La cuenta de almacenamiento que se debe usar se determina en el orden siguiente:The storage account to use is determined in the following order:

  • La propiedad Connection del atributo QueueTrigger.The QueueTrigger attribute's Connection property.
  • El atributo StorageAccount aplicado al mismo parámetro que el atributo QueueTrigger.The StorageAccount attribute applied to the same parameter as the QueueTrigger attribute.
  • El atributo StorageAccount aplicado a la función.The StorageAccount attribute applied to the function.
  • El atributo StorageAccount aplicado a la clase.The StorageAccount attribute applied to the class.
  • La configuración de aplicación "AzureWebJobsStorage".The "AzureWebJobsStorage" app setting.

Desencadenador: configuraciónTrigger - configuration

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.The following table explains the binding configuration properties that you set in the function.json file and the QueueTrigger attribute.

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DESCRIPCIÓNDescription
typetype N/Dn/a Se debe establecer en queueTrigger.Must be set to queueTrigger. 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 Solo en el archivo function.json.In the function.json file only. 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 El nombre de la variable que contiene la carga del elemento de cola en el código de función.The name of the variable that contains the queue item payload in the function code.
queueNamequeueName QueueNameQueueName Nombre de la cola que se sondea.The name of the queue to poll.
conexiónconnection ConnectionConnection El nombre de una configuración de aplicación que contiene la cadena de conexión de almacenamiento que se usará para este enlace.The name of an app setting that contains the Storage connection string to use for this binding. Si el nombre de la configuración de aplicación comienza con "AzureWebJobs", puede especificar solo el resto del nombre aquí.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Por ejemplo, si establece connection en "MyStorage", el entorno en tiempo de ejecución de Functions busca una configuración de aplicación denominada "AzureWebJobsMyStorage".For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Si deja connection vacía, el entorno en tiempo de ejecución de Functions usa la cadena de conexión de almacenamiento predeterminada en la configuración de aplicación que se denomina AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

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.

Desencadenador: usoTrigger - usage

En C# y el script de C#, acceda a los datos de mensaje mediante un parámetro de método, como string paramName.In C# and C# script, access the message data by using a method parameter such as string paramName. En script de C#, paramName es el valor especificado en la propiedad name de function.json.In C# script, paramName is the value specified in the name property of function.json. Puede enlazar a cualquiera de los siguientes tipos:You can bind to any of the following types:

  • Objeto: el entorno de tiempo de ejecución de Functions deserializa una carga JSON en una instancia de una clase arbitraria definida en el código.Object - The Functions runtime deserializes a JSON payload into an instance of an arbitrary class defined in your code.
  • string
  • byte[]
  • CloudQueueMessageCloudQueueMessage

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.If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

En JavaScript, use context.bindings.<name> para tener acceso a la carga del elemento de la cola.In JavaScript, use context.bindings.<name> to access the queue item payload. Si la carga es JSON, se deserializa en un objeto.If the payload is JSON, it's deserialized into an object.

Desencadenador: metadatos del mensajeTrigger - message metadata

El desencadenador de cola proporciona varias propiedades de metadatos.The queue trigger provides several metadata properties. Estas propiedades pueden usarse como parte de expresiones de enlace en otros enlaces o como parámetros del código.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Estas son propiedades de la clase CloudQueueMessage.These are properties of the CloudQueueMessage class.

PropiedadProperty EscribaType DESCRIPCIÓNDescription
QueueTrigger string Carga de cola (si hay una cadena válida).Queue payload (if a valid string). Si la cola envía la carga como una cadena, QueueTrigger tiene el mismo valor que la variable denominada por la propiedad name en function.json.If the queue message payload as a string, QueueTrigger has the same value as the variable named by the name property in function.json.
DequeueCount int Es el número de veces que se ha quitado de la cola este mensaje.The number of times this message has been dequeued.
ExpirationTime DateTimeOffset Es la hora de expiración del mensaje.The time that the message expires.
Id string Es el identificador del mensaje de cola.Queue message ID.
InsertionTime DateTimeOffset Es la hora en la que el mensaje se agregó a la cola.The time that the message was added to the queue.
NextVisibleTime DateTimeOffset Es la siguiente hora a la que será visible el mensaje.The time that the message will next be visible.
PopReceipt string Es la confirmación de extracción del mensaje.The message's pop receipt.

Desencadenador: mensajes dudososTrigger - poison messages

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.When a queue trigger function fails, Azure Functions retries the function up to five times for a given queue message, including the first try. Si se produce un error en los cinco intentos, Functions agregará un mensaje a la cola denominada <nombreDeColaOriginal>-poison.If all five attempts fail, the functions runtime adds a message to a queue named <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.You can write a function to process messages from the poison queue by logging them or sending a notification that manual attention is needed.

Para controlar manualmente los mensajes dudosos, compruebe el elemento dequeueCount del mensaje de la cola.To handle poison messages manually, check the dequeueCount of the queue message.

Desencadenador: algoritmo de sondeoTrigger - polling algorithm

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.The queue trigger implements a random exponential back-off algorithm to reduce the effect of idle-queue polling on storage transaction costs. Cuando se encuentra un mensaje, el entorno en tiempo de ejecución espera dos segundos y, a continuación, comprueba si hay otro mensaje; cuando no se encuentra ningún mensaje, espera unos cuatro segundos antes de intentarlo de nuevo.When a message is found, the runtime waits two seconds and then checks for another message; when no message is found, it waits about four seconds before trying again. 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.After subsequent failed attempts to get a queue message, the wait time continues to increase until it reaches the maximum wait time, which defaults to one minute. El tiempo de espera máximo se configura mediante la propiedad maxPollingInterval en el archivo host.json.The maximum wait time is configurable via the maxPollingInterval property in the host.json file.

Desencadenador: simultaneidadTrigger - concurrency

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.When there are multiple queue messages waiting, the queue trigger retrieves a batch of messages and invokes function instances concurrently to process them. De manera predeterminada, el tamaño de lote es 16.By default, the batch size is 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.When the number being processed gets down to 8, the runtime gets another batch and starts processing those messages. 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.So the maximum number of concurrent messages being processed per function on one virtual machine (VM) is 24. Este límite se aplica por separado a cada función desencadenada por la cola en cada máquina virtual.This limit applies separately to each queue-triggered function on each VM. Si la aplicación de función se escala horizontalmente a varias máquinas virtuales, cada máquina virtual esperará los desencadenadores e intentará ejecutar las funciones.If your function app scales out to multiple VMs, each VM will wait for triggers and attempt to run functions. 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.For example, if a function app scales out to 3 VMs, the default maximum number of concurrent instances of one queue-triggered function is 72.

El tamaño de lote y el umbral para obtener un lote nuevo se configuran en el archivo host.json.The batch size and the threshold for getting a new batch are configurable in the host.json file. 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.If you want to minimize parallel execution for queue-triggered functions in a function app, you can set the batch size to 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).This setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM).

El desencadenador de la cola automáticamente impide que una función procese un mensaje de cola varias veces; las funciones no tienen que escribirse para que sean idempotentes.The queue trigger automatically prevents a function from processing a queue message multiple times; functions do not have to be written to be idempotent.

Desencadenador: propiedades de host.jsonTrigger - host.json properties

El archivo host.json contiene opciones de configuración que controlan el comportamiento de desencadenador de cola.The host.json file contains settings that control queue trigger behavior. Consulte la sección de configuración de host.json para más información sobre las opciones de configuración disponibles.See the host.json settings section for details regarding available settings.

OutputOutput

Use el enlace de salida de Azure Queue Storage para escribir mensajes en una cola.Use the Azure Queue storage output binding to write messages to a queue.

Salida: ejemploOutput - example

Vea el ejemplo específico del lenguaje:See the language-specific example:

Salida: ejemplo de C#Output - C# example

En el ejemplo siguiente se muestra una función de C# que crea un mensaje de cola para cada una de las solicitudes HTTP que se reciben.The following example shows a C# function that creates a queue message for each HTTP request received.

[StorageAccount("AzureWebJobsStorage")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

Salida: ejemplo de script de C#Output - C# script example

En el ejemplo siguiente se muestra un enlace de desencadenador HTTP de un archivo function.json y el código de script de C# (.csx) que usa el enlace.The following example shows an HTTP trigger binding in a function.json file and C# script (.csx) code that uses the binding. La función crea un elemento de cola con una carga del objeto CustomQueueMessage para cada una de las solicitudes HTTP recibidas.The function creates a queue item with a CustomQueueMessage object payload for each HTTP request received.

Este es el archivo function.json:Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

En la sección de configuración se explican estas propiedades.The configuration section explains these properties.

Este es el código de script de C# que crea un único mensaje de cola:Here's C# script code that creates a single queue message:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, ILogger log)
{
    return input;
}

Puede enviar varios mensajes a la vez mediante el uso de un parámetro ICollector o IAsyncCollector.You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. Este es el código de script de C# que envía varios mensajes, uno con los datos de la solicitud HTTP y otro con valores codificados de forma rígida:Here's C# script code that sends multiple messages, one with the HTTP request data and one with hard-coded values:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItems, 
    ILogger log)
{
    myQueueItems.Add(input);
    myQueueItems.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

Salida: ejemplo de JavaScriptOutput - JavaScript example

En el ejemplo siguiente se muestra un enlace de desencadenador HTTP de un archivo function.json y una función de JavaScript que usa el enlace.The following example shows an HTTP trigger binding in a function.json file and a JavaScript function that uses the binding. La función crea un elemento de cola para cada una de las solicitudes HTTP recibidas.The function creates a queue item for each HTTP request received.

Este es el archivo function.json:Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

En la sección de configuración se explican estas propiedades.The configuration section explains these properties.

Este es el código de JavaScript:Here's the JavaScript code:

module.exports = function (context, input) {
    context.done(null, input.body);
};

Puede enviar varios mensajes a la vez mediante la definición de una matriz de mensajes para el enlace de salida myQueueItem.You can send multiple messages at once by defining a message array for the myQueueItem output binding. El código JavaScript envía dos mensajes de cola con valores codificados de forma rígida para cada una de las solicitudes HTTP recibidas.The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

module.exports = function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
    context.done();
};

Salida: ejemplo de JavaOutput - Java example

En el ejemplo siguiente se muestra una función de Java que crea un mensaje de cola cuando una solicitud HTTP la desencadena.The following example shows a Java function that creates a queue message for when triggered by a HTTP request.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "AzureWebJobsStorage")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding&lt;String&gt; result) {
       result.setValue(message + " has been added.");
       return message;
 }

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @QueueOutput en los parámetros cuyo valor se escribiría en Queue Storage.In the Java functions runtime library, use the @QueueOutput annotation on parameters whose value would be written to Queue storage. El parámetro type debe ser OutputBinding<T>, donde T es cualquier tipo nativo de Java de un POJO.The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

Salida: ejemplo de PythonOutput - Python example

En el ejemplo siguiente se muestra cómo generar valores únicos y múltiples en las colas de almacenamiento.The following example demonstrates how to output single and multiple values to storage queues. La configuración necesaria para function.json es la misma en cualquier caso.The configuration needed for function.json is the same either way.

Un enlace de cola de almacenamiento se define en function.json, donde type está establecido en queue.A Storage queue binding is defined in function.json where type is set to queue.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

Para establecer un mensaje individual en la cola, se pasa un valor único al método set.To set a individual message on the queue, you pass a single value to the set method.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Para crear varios mensajes en la cola, declare un parámetro como el tipo de lista adecuado y pase una matriz de valores (que coincidan con el tipo de lista) al método set.To create multiple messages on the queue, declare a parameter as the appropriate list type and pass an array of values (that match the list type) to the set method.

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

Salida: atributosOutput - attributes

En las bibliotecas de clase C#, use QueueAttribute.In C# class libraries, use the QueueAttribute.

El atributo se aplica a un parámetro out o al valor de retorno de la función.The attribute applies to an out parameter or the return value of the function. El constructor del atributo toma el nombre de la cola, tal como se muestra en el ejemplo siguiente:The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Puede establecer la propiedad Connection para especificar la cuenta de almacenamiento que se usará, tal como se muestra en el ejemplo siguiente:You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Para obtener un ejemplo completo, consulte Salida: ejemplo de C#.For a complete example, see Output - C# example.

Puede usar el atributo StorageAccount para especificar la cuenta de almacenamiento en el nivel de clase, método o parámetro.You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. Para obtener más información, consulte Desencadenador: atributos.For more information, see Trigger - attributes.

Salida: configuraciónOutput - configuration

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

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DESCRIPCIÓNDescription
typetype N/Dn/a Se debe establecer en queue.Must be set to queue. 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 out.Must be set to out. 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 la cola en el código de la función.The name of the variable that represents the queue in function code. Se establece en $return para hacer referencia al valor devuelto de la función.Set to $return to reference the function return value.
queueNamequeueName QueueNameQueueName Nombre de la cola.The name of the queue.
conexiónconnection ConnectionConnection El nombre de una configuración de aplicación que contiene la cadena de conexión de almacenamiento que se usará para este enlace.The name of an app setting that contains the Storage connection string to use for this binding. Si el nombre de la configuración de aplicación comienza con "AzureWebJobs", puede especificar solo el resto del nombre aquí.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Por ejemplo, si establece connection en "MyStorage", el entorno en tiempo de ejecución de Functions busca una configuración de aplicación denominada "AzureWebJobsMyStorage".For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Si deja connection vacía, el entorno en tiempo de ejecución de Functions usa la cadena de conexión de almacenamiento predeterminada en la configuración de aplicación que se denomina AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

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.

Uso de salidasOutput - usage

En C# y script de C#, escriba un mensaje de cola único mediante un parámetro de método como out T paramName.In C# and C# script, write a single queue message by using a method parameter such as out T paramName. En script de C#, paramName es el valor especificado en la propiedad name de function.json.In C# script, paramName is the value specified in the name property of function.json. Puede usar el tipo de valor devuelto del método en lugar de un parámetro out, y T puede ser cualquiera de los siguientes tipos:You can use the method return type instead of an out parameter, and T can be any of the following types:

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.If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

En C# y script de C#, escriba varios mensajes de cola mediante uno de los siguientes tipos:In C# and C# script, write multiple queue messages by using one of the following types:

En las funciones de JavaScript, use context.bindings.<name> para tener acceso al mensaje de cola de salida.In JavaScript functions, use context.bindings.<name> to access the output queue message. Puede usar una cadena o un objeto JSON serializable para la carga del elemento de cola.You can use a string or a JSON-serializable object for the queue item payload.

Excepciones y códigos de retornoExceptions and return codes

EnlaceBinding ReferenciaReference
ColaQueue Códigos de error de colaQueue Error Codes
Blob, tabla, colaBlob, Table, Queue Códigos de error de almacenamientoStorage Error Codes
Blob, tabla, colaBlob, Table, Queue Solución de problemasTroubleshooting

configuración de host.jsonhost.json settings

En esta sección se describen las opciones de configuración globales disponibles para este enlace en la versión 2.x.This section describes the global configuration settings available for this binding in version 2.x. El siguiente archivo host.json de ejemplo contiene solo la configuración de la versión 2.x para este enlace.The example host.json file below contains only the version 2.x settings for this binding. Para obtener más información acerca de las opciones de configuración globales de la versión 2.x, consulte la referencia de host.json para Azure Functions, versión 2.x.For more information about global configuration settings in version 2.x, see host.json reference for Azure Functions version 2.x.

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.For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8
        }
    }
}
PropiedadProperty Valor predeterminadoDefault DESCRIPCIÓNDescription
maxPollingIntervalmaxPollingInterval 00:00:0100:00:01 Intervalo máximo entre sondeos de la cola.The maximum interval between queue polls. El mínimo es 00:00:00.100 (100 ms) y se incrementa hasta 00:01:00 (1 min).Minimum is 00:00:00.100 (100 ms) and increments up to 00:01:00 (1 min). En 1. x, el tipo de datos es milisegundos y en 2. x es un intervalo de tiempo.In 1.x the data type is milliseconds, and in 2.x it is a TimeSpan.
visibilityTimeoutvisibilityTimeout 00:00:0000:00:00 Intervalo de tiempo entre los reintentos cuando se produce un error al procesar un mensaje.The time interval between retries when processing of a message fails.
batchSizebatchSize 1616 El número de mensajes en cola que el runtime de Functions recupera simultáneamente y procesa en paralelo.The number of queue messages that the Functions runtime retrieves simultaneously and processes in parallel. Cuando el número que se está procesando llega a newBatchThreshold el runtime obtiene otro lote y empieza a procesar esos mensajes.When the number being processed gets down to the newBatchThreshold, the runtime gets another batch and starts processing those messages. Por lo tanto, el número máximo de mensajes simultáneos que se procesan por función es batchSize más newBatchThreshold.So the maximum number of concurrent messages being processed per function is batchSize plus newBatchThreshold. Este límite se aplica por separado a cada función desencadenada por la cola.This limit applies separately to each queue-triggered function.

Si desea evitar la ejecución en paralelo de los mensajes de una cola, puede establecer batchSize en 1.If you want to avoid parallel execution for messages received on one queue, you can set batchSize to 1. Sin embargo, este valor solo elimina la simultaneidad siempre y cuando la aplicación de función se ejecute en una única máquina virtual (VM).However, this setting eliminates concurrency only so long as your function app runs on a single virtual machine (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.If the function app scales out to multiple VMs, each VM could run one instance of each queue-triggered function.

El valor máximo de batchSize es 32.The maximum batchSize is 32.
maxDequeueCountmaxDequeueCount 55 Número de veces que se intenta procesar un mensaje antes de pasarlo a la cola de mensajes dudosos.The number of times to try processing a message before moving it to the poison queue.
newBatchThresholdnewBatchThreshold batchSize/2batchSize/2 Siempre que el número de mensajes que se procesan simultáneamente llega a este número, el runtime recupera otro lote.Whenever the number of messages being processed concurrently gets down to this number, the runtime retrieves another batch.

Pasos siguientesNext steps