Associações de armazenamento de filas do Azure FunctionsAzure Queue storage bindings for Azure Functions

Este artigo explica como trabalhar com associações de armazenamento de Fila do Azure no Azure Functions.This article explains how to work with Azure Queue storage bindings in Azure Functions. O Azure Functions dá suporte a associações de gatilho e de saída para filas.Azure Functions supports trigger and output bindings for queues.

Essas são as informações de referência para desenvolvedores do Azure Functions.This is reference information for Azure Functions developers. Se for novo no Azure Functions, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Pacotes – Functions 1.xPackages - Functions 1.x

As associações de armazenamento Filas são fornecidas no pacote NuGet Microsoft.Azure.WebJobs, versão 2.x.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs NuGet package, version 2.x. O código-fonte do pacote está no repositório GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

O suporte para essa associação é fornecido automaticamente em todos os ambientes de desenvolvimento.Support for this binding is automatically provided in all development environments. Você não precisa instalar o pacote ou registrar a extensão manualmente.You don't have to manually install the package or register the extension.

Versão do SDK de Armazenamento do Microsoft Azure em Funções 1. xAzure Storage SDK version in Functions 1.x

Em Funções de 1. x, os gatilhos de armazenamento e associações usam a versão 7.2.1 do SDK de Armazenamento do Microsoft Azure (windowsazure pacote NuGet).In Functions 1.x, the Storage triggers and bindings use version 7.2.1 of the Azure Storage SDK (WindowsAzure.Storage NuGet package). Se você referenciar uma versão diferente do SDK do armazenamento e associar a um tipo de SDK de armazenamento na sua assinatura de função, o tempo de execução de funções pode relatar se não é possível associar a esse 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. A solução é verificar as referências do projeto windowsazure 7.2.1.The solution is to make sure your project references WindowsAzure.Storage 7.2.1.

Pacotes-funções 2. x e superiorPackages - Functions 2.x and higher

As associações de Armazenamento de Filas são fornecidas no pacote NuGet Microsoft.Azure.WebJobs.Extensions.Storage, versão 3.x.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Storage NuGet package, version 3.x. O código-fonte do pacote está no repositório GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.The following table tells how to add support for this binding in each development environment.

Ambiente de desenvolvimentoDevelopment environment Para adicionar suporteTo add support
Desenvolvimento local - biblioteca de classes do C#Local development - C# class library Instalar o pacoteInstall the package
Desenvolvimento local - script do C#, JavaScript, F#, Java e PythonLocal development - C# script, JavaScript, F#, Java and Python Registrar a extensãoRegister the extension
Desenvolvimento de portalPortal development Instalar ao adicionar uma associação de saídaInstall when adding output binding

Para saber como atualizar as extensões de associação existentes no portal sem precisar republicar o projeto de aplicativo de funções, consulte Atualizar as extensões.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

CodificaçãoEncoding

O Functions espera uma cadeia de caracteres codificada base64.Functions expect a base64 encoded string. Todos os ajustes ao tipo de codificação (para preparar os dados como uma cadeia de caracteres codificada base64) precisam ser implementados no serviço de chamada.Any adjustments to the encoding type (in order to prepare data as a base64 encoded string) need to be implemented in the calling service.

GatilhoTrigger

Use o gatilho de fila para iniciar uma função quando um novo item é recebido em uma fila.Use the queue trigger to start a function when a new item is received on a queue. A mensagem da fila é fornecida como entrada para a função.The queue message is provided as input to the function.

Gatilho - exemploTrigger - example

Consulte o exemplo específico a um idioma:See the language-specific example:

Gatilho - exemplo C#Trigger - C# example

O exemplo a seguir mostra uma função C# que consulta a fila myqueue-items e grava um log cada vez que um item de fila é processado.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}");
    }
}

Gatilho - exemplo de script C#Trigger - C# script example

O exemplo a seguir mostra uma associação de gatilho de fila em um arquivo function.json e código script C# (.csx) que usa a associação.The following example shows a queue trigger binding in a function.json file and C# script (.csx) code that uses the binding. A função controla a myqueue-items fila e grava um log cada vez que um item de fila é processado.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Aqui está o arquivo function.json:Here's the function.json file:

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

A seção configuração explica essas propriedades.The configuration section explains these properties.

Aqui está o código de script do 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}");
}

A seção uso explica myQueueItem, que é chamado pela name propriedade function.json.The usage section explains myQueueItem, which is named by the name property in function.json. A seção de metadados de mensagem explica todas as outras variáveis mostradas.The message metadata section explains all of the other variables shown.

Gatilho - exemplo de JavaScriptTrigger - JavaScript example

O exemplo a seguir mostra uma associação de gatilho de fila em um arquivo function.json e uma função JavaScript que usa a associação.The following example shows a queue trigger binding in a function.json file and a JavaScript function that uses the binding. A função controla a myqueue-items fila e grava um log cada vez que um item de fila é processado.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Aqui está o arquivo function.json:Here's the function.json file:

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

A seção configuração explica essas propriedades.The configuration section explains these properties.

Observação

O parâmetro nome é refletido como context.bindings.<name> no código JavaScript que contém a carga útil do item da fila.The name parameter reflects as context.bindings.<name> in the JavaScript code which contains the queue item payload. Essa carga útil também é passada como o segundo parâmetro para a função.This payload is also passed as the second parameter to the function.

Aqui está o código 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();
};

A seção uso explica myQueueItem, que é chamado pela name propriedade function.json.The usage section explains myQueueItem, which is named by the name property in function.json. A seção de metadados de mensagem explica todas as outras variáveis mostradas.The message metadata section explains all of the other variables shown.

Trigger - exemplo de JavaTrigger - Java example

O exemplo Java a seguir mostra as funções do acionador da fila de armazenamento que registra a mensagem acionada colocada na fila 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);
}

Gatilho – exemplo do PythonTrigger - Python example

O exemplo a seguir demonstra como ler uma mensagem de fila passada para uma função por meio de um gatilho.The following example demonstrates how to read a queue message passed to a function via a trigger.

Um gatilho de fila de armazenamento é definido em Function. JSON , em que Type é definido como 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"
    }
  ]
}

O código _init_. py declara um parâmetro como func.ServiceBusMessage, o que permite que você leia a mensagem da fila em sua função.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)

Gatilho – atributosTrigger - attributes

Em bibliotecas de classes C#, use os seguintes atributos para configurar um gatilho de fila:In C# class libraries, use the following attributes to configure a queue trigger:

  • QueueTriggerAttributeQueueTriggerAttribute

    O construtor do atributo usa o nome da fila para monitorar, conforme mostrado no exemplo a seguir: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)
    {
        ...
    }
    

    Você pode definir a Connection propriedade para especificar a conta de armazenamento para usar, conforme mostrado no exemplo a seguir: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 ver um exemplo completo, consulte Gatilho – exemplo de C#.For a complete example, see Trigger - C# example.

  • StorageAccountAttributeStorageAccountAttribute

    Oferece uma maneira de especificar a conta de armazenamento para usar.Provides another way to specify the storage account to use. O construtor toma o nome de uma configuração de aplicativo que contenha uma cadeia de conexão de armazenamento.The constructor takes the name of an app setting that contains a storage connection string. O atributo pode ser aplicado no nível de classe, método ou parâmetro.The attribute can be applied at the parameter, method, or class level. O exemplo a seguir mostra o nível de classe e 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( //...
    {
        ...
    }
    

A conta de armazenamento a ser usada é determinada na seguinte ordem:The storage account to use is determined in the following order:

  • A propriedade QueueTrigger do atributoConnection.The QueueTrigger attribute's Connection property.
  • O StorageAccount atributo aplicado ao mesmo parâmetro do QueueTrigger atributo.The StorageAccount attribute applied to the same parameter as the QueueTrigger attribute.
  • O StorageAccount atributo aplicado à função.The StorageAccount attribute applied to the function.
  • O StorageAccount atributo aplicado à classe.The StorageAccount attribute applied to the class.
  • A configuração do aplicativo "AzureWebJobsStorage".The "AzureWebJobsStorage" app setting.

Gatilho – configuraçãoTrigger - configuration

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no QueueTrigger atributo.The following table explains the binding configuration properties that you set in the function.json file and the QueueTrigger attribute.

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype N/Dn/a Deve ser definido como queueTrigger.Must be set to queueTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection N/Dn/a Apenas no arquivo function.json.In the function.json file only. Deve ser definido como in.Must be set to in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
namename N/Dn/a O nome da variável que contém o conteúdo do item de fila no código da função.The name of the variable that contains the queue item payload in the function code.
queueNamequeueName QueueNameQueueName O nome da fila a ser controlada.The name of the queue to poll.
conexãoconnection ConexãoConnection O nome de uma configuração de aplicativo que contém uma cadeia de conexão de Armazenamento para usar para essa associação.The name of an app setting that contains the Storage connection string to use for this binding. Se o nome de configuração do aplicativo começar com "AzureWebJobs", você pode especificar apenas o resto do nome aqui.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Por exemplo, se você configurar connection para “MyStorage”, o runtime do Functions procura por uma configuração de aplicativo que esteja nomeada “AzureWebJobsMyStorage."For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Se você deixar connection vazio, o runtime de Functions usa a cadeia de caracteres de conexão de Armazenamento padrão na configuração de aplicativo chamada AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Gatilho - usoTrigger - usage

Em C# e script C#, acesse os dados da mensagem usando um 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. No script do C#, paramName é o valor especificado na propriedade name de function.json.In C# script, paramName is the value specified in the name property of function.json. É possível associar a qualquer um dos seguintes tipos:You can bind to any of the following types:

  • Objeto - o runtime do Functions desserializa um conteúdo JSON em uma instância de uma classe arbitrária definida em seu código.Object - The Functions runtime deserializes a JSON payload into an instance of an arbitrary class defined in your code.
  • string
  • byte[]
  • CloudQueueMessageCloudQueueMessage

Se você tentar associar CloudQueueMessage e receber uma mensagem de erro, certifique-se de ter uma referência para a versão correta do SDK do Armazenamento.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.

Em JavaScript, use context.bindings.<name> para acessar o conteúdo de item de fila.In JavaScript, use context.bindings.<name> to access the queue item payload. Se o conteúdo for JSON, ele é desserializado em um objeto.If the payload is JSON, it's deserialized into an object.

Gatilho - metadados da mensagemTrigger - message metadata

O gatilho de fila fornece várias propriedades de metadados.The queue trigger provides several metadata properties. Essas propriedades podem ser usadas como parte de expressões de associação em outras associações ou como parâmetros em seu código.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Essas são propriedades da classe CloudQueueMessage.These are properties of the CloudQueueMessage class.

PropriedadeProperty TypeType DescriçãoDescription
QueueTrigger string Conteúdo da fila (se for uma cadeia de caracteres válida).Queue payload (if a valid string). Se o conteúdo de mensagem de fila como uma cadeia de caracteres QueueTrigger tem o mesmo valor da variável nomeada pela name propriedade em 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 O número de vezes que essa mensagem foi removida da fila.The number of times this message has been dequeued.
ExpirationTime DateTimeOffset A hora em que a mensagem expira.The time that the message expires.
Id string ID da mensagem da fila.Queue message ID.
InsertionTime DateTimeOffset A hora em que a mensagem foi adicionada à fila.The time that the message was added to the queue.
NextVisibleTime DateTimeOffset A hora em que a mensagem estará visível.The time that the message will next be visible.
PopReceipt string Recebimento pop da mensagem.The message's pop receipt.

Gatilho - mensagens suspeitasTrigger - poison messages

Quando uma função do gatilho de fila falhar, o Azure Functions repetirá essa função até cinco vezes para uma determinada mensagem da fila, incluindo a primeira tentativa.When a queue trigger function fails, Azure Functions retries the function up to five times for a given queue message, including the first try. Se todas as cinco tentativas falharem, o runtime das funções adicionará uma mensagem em uma fila chamada <originalqueuename>-poison.If all five attempts fail, the functions runtime adds a message to a queue named <originalqueuename>-poison. Você pode gravar uma função para processar as mensagens da fila de mensagens suspeitas registrando-as ou enviando uma notificação de que a atenção manual é necessária.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 tratar mensagens suspeitas manualmente, verifique o dequeueCount da mensagem de fila.To handle poison messages manually, check the dequeueCount of the queue message.

Gatilho - algoritmo de sondagemTrigger - polling algorithm

O gatilho de fila implementa um algoritmo exponencial aleatório de retirada para reduzir o efeito de sondagem de fila ociosa nos custos das transações de armazenamento.The queue trigger implements a random exponential back-off algorithm to reduce the effect of idle-queue polling on storage transaction costs. Quando uma mensagem for encontrada, o runtime aguarda dois segundos e, em seguida, verifica outra mensagem; quando nenhuma mensagem for encontrada, ele aguarda cerca de quatro segundos antes de tentar novamente.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. Após subsequentes tentativas falhas para obter uma mensagem da fila, o tempo de espera continua a aumentar até atingir o tempo de espera máximo, cujo padrão é um 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. O tempo de espera máximo é configurável por meio da propriedade maxPollingInterval no arquivo host.json.The maximum wait time is configurable via the maxPollingInterval property in the host.json file.

Gatilho - simultaneidadeTrigger - concurrency

Quando há várias mensagens de fila aguardando, o gatilho de fila recupera um lote de mensagens e invoca as instâncias de função ao mesmo tempo para processá-las.When there are multiple queue messages waiting, the queue trigger retrieves a batch of messages and invokes function instances concurrently to process them. Por padrão, o tamanho do lote é 16.By default, the batch size is 16. Quando o número que está sendo processado chega até 8, o runtime obtém outro lote e começa a processar as mensagens.When the number being processed gets down to 8, the runtime gets another batch and starts processing those messages. Portanto, o número máximo de mensagens simultâneas que estão sendo processadas por função em uma máquina virtual (VM) é 24.So the maximum number of concurrent messages being processed per function on one virtual machine (VM) is 24. Esse limite se aplica separadamente a cada função acionada por fila em cada VM.This limit applies separately to each queue-triggered function on each VM. Se aplicativo de função for escalado horizontalmente para várias VMs, cada VM aguardará gatilhos e tentará executar funções.If your function app scales out to multiple VMs, each VM will wait for triggers and attempt to run functions. Por exemplo, se um aplicativo de função for escalado horizontalmente para 3 VMs, o número de máximo padrão de instâncias simultâneas de uma função acionada por fila será 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.

O tamanho do lote e o limite para obtenção de um novo lote são configuráveis no arquivo host.json.The batch size and the threshold for getting a new batch are configurable in the host.json file. Se quiser minimizar a execução paralela para funções acionadas por fila em um aplicativo de função, você poder definir o tamanho do lote para 1.If you want to minimize parallel execution for queue-triggered functions in a function app, you can set the batch size to 1. Essa configuração elimina a simultaneidade, desde que seu aplicativo de função seja executado em uma única máquina virtual (VM).This setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM).

O gatilho de fila impede automaticamente que uma função processe uma mensagem da fila várias vezes; as funções não precisam ser escritas para ser 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.

Gatilho - propriedades de host.jsonTrigger - host.json properties

O arquivo host.json contém configurações que controlam o comportamento de gatilho de fila.The host.json file contains settings that control queue trigger behavior. Consulte a seção configurações do host. JSON para obter detalhes sobre as configurações disponíveis.See the host.json settings section for details regarding available settings.

SaídaOutput

Use a associação de saída do armazenamento de Filas do Azure para que você grave mensagens em uma fila.Use the Azure Queue storage output binding to write messages to a queue.

Saída - exemploOutput - example

Consulte o exemplo específico a um idioma:See the language-specific example:

Saída - exemplo C#Output - C# example

O exemplo a seguir mostra uma função C# que cria uma mensagem da fila para cada solicitação HTTP recebida.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;
    }
}

Saída - exemplo de script C#Output - C# script example

O exemplo a seguir mostra uma associação de gatilho de HTTP em um arquivo function.json e código script C# (.csx) que usa a associação.The following example shows an HTTP trigger binding in a function.json file and C# script (.csx) code that uses the binding. A função cria um item de fila com um conteúdo de objeto CustomQueueMessage para cada solicitação HTTP recebida.The function creates a queue item with a CustomQueueMessage object payload for each HTTP request received.

Aqui está o arquivo 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"
    }
  ]
}

A seção configuração explica essas propriedades.The configuration section explains these properties.

Aqui está o código script C# que cria uma mensagem de fila única: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;
}

Você pode enviar várias mensagens ao mesmo tempo usando um parâmetro ICollector ou IAsyncCollector.You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. Aqui está o código de script C# que envia várias mensagens, uma com os dados da solicitação HTTP e outra com valores codificados: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" });
}

Saída - exemplo JavaScriptOutput - JavaScript example

O exemplo a seguir mostra uma associação de gatilho HTTP em um arquivo function.json e uma função JavaScript que usa a associação.The following example shows an HTTP trigger binding in a function.json file and a JavaScript function that uses the binding. A função cria um item da fila para cada solicitação HTTP recebida.The function creates a queue item for each HTTP request received.

Aqui está o arquivo 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"
    }
  ]
}

A seção configuração explica essas propriedades.The configuration section explains these properties.

Aqui está o código JavaScript:Here's the JavaScript code:

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

Você pode enviar várias mensagens de uma vez com a definição de uma matriz de mensagem para a myQueueItem associação de saída.You can send multiple messages at once by defining a message array for the myQueueItem output binding. O código JavaScript a seguir envia duas mensagens de fila com valores codificados para cada solicitação HTTP recebida.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();
};

Saída - exemplo de JavaOutput - Java example

O exemplo a seguir mostra uma função Java que cria uma mensagem de fila para quando acionada por uma solicitação HTTP.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;
 }

No biblioteca de runtime de funções Java, use o @QueueOutput anotação em parâmetros cujo valor seria gravado no armazenamento de fila.In the Java functions runtime library, use the @QueueOutput annotation on parameters whose value would be written to Queue storage. O tipo de parâmetro deve ser OutputBinding<T>, onde T é qualquer tipo Java nativo de um POJO.The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

Saída – exemplo do PythonOutput - Python example

O exemplo a seguir demonstra como gerar valores únicos e múltiplos para filas de armazenamento.The following example demonstrates how to output single and multiple values to storage queues. A configuração necessária para Function. JSON é a mesma de qualquer forma.The configuration needed for function.json is the same either way.

Uma associação de fila de armazenamento é definida em Function. JSON , em que Type é definido como 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 definir uma mensagem individual na fila, você passa um único valor para o 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 criar várias mensagens na fila, declare um parâmetro como o tipo de lista apropriado e passe uma matriz de valores (que correspondam ao tipo de lista) para o 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'

Saída - atributosOutput - attributes

Em bibliotecas de classes do C#, use o QueueAttribute.In C# class libraries, use the QueueAttribute.

O atributo se aplica a um out parâmetro ou o valor de retorno da função.The attribute applies to an out parameter or the return value of the function. O construtor do atributo usa o nome da fila, conforme mostrado no exemplo a seguir: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)
{
    ...
}

Você pode definir a Connection propriedade para especificar a conta de armazenamento para usar, conforme mostrado no exemplo a seguir: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 ver um exemplo completo, consulte Saída – exemplo de C#.For a complete example, see Output - C# example.

Você pode usar o StorageAccount atributo para especificar a conta de armazenamento no nível de classe, método ou parâmetro.You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. Para obter mais informações, confira Gatilho – atributos.For more information, see Trigger - attributes.

Saída - configuraçãoOutput - configuration

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no Queue atributo.The following table explains the binding configuration properties that you set in the function.json file and the Queue attribute.

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype N/Dn/a Deve ser definido como queue.Must be set to queue. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection N/Dn/a Deve ser definido como out.Must be set to out. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
namename N/Dn/a O nome da variável que representa a fila no código de função.The name of the variable that represents the queue in function code. Definido como $return para referenciar o valor de retorno da função.Set to $return to reference the function return value.
queueNamequeueName QueueNameQueueName O nome da fila.The name of the queue.
conexãoconnection ConexãoConnection O nome de uma configuração de aplicativo que contém uma cadeia de conexão de Armazenamento para usar para essa associação.The name of an app setting that contains the Storage connection string to use for this binding. Se o nome de configuração do aplicativo começar com "AzureWebJobs", você pode especificar apenas o resto do nome aqui.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Por exemplo, se você configurar connection para “MyStorage”, o runtime do Functions procura por uma configuração de aplicativo que esteja nomeada “AzureWebJobsMyStorage."For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Se você deixar connection vazio, o runtime de Functions usa a cadeia de caracteres de conexão de Armazenamento padrão na configuração de aplicativo chamada AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Saída - usoOutput - usage

Em C# e script C#, grave uma mensagem de fila única usando um parâmetro de método como o out T paramName.In C# and C# script, write a single queue message by using a method parameter such as out T paramName. No script do C#, paramName é o valor especificado na propriedade name de function.json.In C# script, paramName is the value specified in the name property of function.json. Você pode usar o tipo de retorno de método em vez de um out parâmetro, e T pode ser qualquer um dos seguintes tipos:You can use the method return type instead of an out parameter, and T can be any of the following types:

Se você tentar associar CloudQueueMessage e receber uma mensagem de erro, certifique-se de ter uma referência para a versão correta do SDK do Armazenamento.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.

Em C# e script C#, grave várias mensagens de fila usando um dos seguintes tipos:In C# and C# script, write multiple queue messages by using one of the following types:

Em funções em JavaScript, use context.bindings.<name> para acessar a mensagem de fila de saída.In JavaScript functions, use context.bindings.<name> to access the output queue message. Você pode usar uma cadeia de caracteres ou um objeto serializável em JSON para o conteúdo de item de fila.You can use a string or a JSON-serializable object for the queue item payload.

Exceções e códigos de retornoExceptions and return codes

AssociaçãoBinding ReferênciaReference
FilaQueue Fila de códigos de erroQueue Error Codes
Blob, tabela, filaBlob, Table, Queue Códigos de erro de armazenamentoStorage Error Codes
Blob, tabela, filaBlob, Table, Queue Solução de problemasTroubleshooting

configurações de host.jsonhost.json settings

Esta seção descreve as definições de configuração global disponíveis para essa associação nas versões 2. x e superior.This section describes the global configuration settings available for this binding in versions 2.x and higher. O arquivo host. JSON de exemplo abaixo contém apenas as configurações da versão 2. x + para essa associação.The example host.json file below contains only the version 2.x+ settings for this binding. Para obter mais informações sobre definições de configuração global nas versões 2. x e posteriores, consulte referência de host. JSON para Azure Functions.For more information about global configuration settings in versions 2.x and beyond, see host.json reference for Azure Functions.

Observação

Para obter uma referência de host.json no Functions 1.x, consulte Referência de host.json para o Azure Functions 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
        }
    }
}
PropriedadeProperty PadrãoDefault DescriçãoDescription
maxPollingIntervalmaxPollingInterval 00:00:0100:00:01 O intervalo máximo entre as sondagens de fila.The maximum interval between queue polls. O mínimo é 00:00:00.100 (100 ms) e incrementa até 00:01:00 (1 min).Minimum is 00:00:00.100 (100 ms) and increments up to 00:01:00 (1 min). Em 1. x, o tipo de dados é milissegundos e, em 2. x e superior, é um TimeSpan.In 1.x the data type is milliseconds, and in 2.x and higher it is a TimeSpan.
visibilityTimeoutvisibilityTimeout 00:00:0000:00:00 O intervalo de tempo entre as repetições quando o processamento de uma mensagem falha.The time interval between retries when processing of a message fails.
batchSizebatchSize 1616 O número de mensagens em fila que o runtime de Funções recupera simultaneamente e processa em paralelo.The number of queue messages that the Functions runtime retrieves simultaneously and processes in parallel. Quando o número que está sendo processado chega até newBatchThreshold, o runtime obtém outro lote e começa a processar as mensagens.When the number being processed gets down to the newBatchThreshold, the runtime gets another batch and starts processing those messages. Portanto, o número máximo de mensagens simultâneas que estão sendo processadas por função é batchSize mais newBatchThreshold.So the maximum number of concurrent messages being processed per function is batchSize plus newBatchThreshold. Esse limite se aplica separadamente a cada função acionada por fila.This limit applies separately to each queue-triggered function.

Se quiser evitar uma execução paralela para mensagens recebidas em uma fila, é possível definir batchSize como 1.If you want to avoid parallel execution for messages received on one queue, you can set batchSize to 1. No entanto, essa configuração elimina a simultaneidade desde que seu aplicativo de função seja executado em uma única máquina virtual (VM).However, this setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM). Se o aplicativo de função se expande para várias VMs, cada VM pode executar uma instância de cada função acionada por fila.If the function app scales out to multiple VMs, each VM could run one instance of each queue-triggered function.

O máximo batchSize é 32.The maximum batchSize is 32.
maxDequeueCountmaxDequeueCount 55 O número de vezes para tentar processar uma mensagem antes de movê-la para a fila de mensagens suspeitas.The number of times to try processing a message before moving it to the poison queue.
newBatchThresholdnewBatchThreshold batchSize/2batchSize/2 Sempre que o número de mensagens processadas simultaneamente chega a esse número, o runtime recupera outro lote.Whenever the number of messages being processed concurrently gets down to this number, the runtime retrieves another batch.

Próximos passosNext steps