Compartilhar via

Associações de saída de Armazenamento de Fila do Azure para o Azure Functions

  • Artigo

O Azure Functions pode criar novas mensagens de armazenamento de Fila do Azure configurando uma associação de saída.

Para obter informações sobre a instalação e detalhes de configuração, confira a visão geral.

Importante

Este artigo usa guias para dar suporte a várias versões do modelo de programação Node.js. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Para obter mais detalhes sobre como funciona o modelo v4, consulte o Guia do desenvolvedor do Node.js para o Azure Functions. Para saber mais sobre as diferenças entre os modelos v3 e a v4, consulte o Guia de migração.

O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a ambos os modelos de programação.

Exemplo

A função C# pode ser criada por meio de um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework. As extensões para funções do processo de trabalho isoladas usam namespaces Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions. Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. As extensões para funções dentro do processo usam namespaces Microsoft.Azure.WebJobs.Extensions.*.

Importante

O suporte terminará para o modelo em processo em 10 de novembro de 2026. É altamente recomendável migrar seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

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

    // Queue Output messages
    return messages;
}

Para obter um exemplo de ponta a ponta de como configurar uma ligação de saída para o armazenamento de filas, consulte um destes artigos:

O exemplo a seguir mostra uma função Java que cria uma mensagem de fila para quando acionada por uma solicitação HTTP.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> 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. O tipo de parâmetro deve ser OutputBinding<T>, onde T é qualquer tipo Java nativo de um POJO.

Para obter um exemplo de ponta a ponta de como configurar uma ligação de saída para o armazenamento de filas, consulte um destes artigos:

O exemplo a seguir mostra uma função TypeScript disparada por HTTP que cria um item da fila para cada solicitação HTTP recebida.

import { app, HttpRequest, HttpResponseInit, InvocationContext, output } from '@azure/functions';

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

O exemplo a seguir mostra uma função JavaScript disparada por HTTP que cria um item da fila para cada solicitação HTTP recebida.

const { app, output } = require('@azure/functions');

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Para obter um exemplo de ponta a ponta de como configurar uma ligação de saída para o armazenamento de filas, consulte um destes artigos:

Os exemplos de código a seguir demonstram como produzir uma mensagem de fila de uma função disparada por HTTP. A seção de configuração com type de queue define a associação de saída.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Usando essa configuração de associação, uma função do PowerShell pode criar uma mensagem de fila usando Push-OutputBinding. Neste exemplo, uma mensagem é criada a partir de um parâmetro de corpo ou cadeia de caracteres de consulta.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Para enviar várias mensagens de uma vez, defina uma matriz de mensagens e use Push-OutputBinding para enviar mensagens para a associação de saída da Fila.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Para obter um exemplo de ponta a ponta de como configurar uma ligação de saída para o armazenamento de filas, consulte um destes artigos:

O exemplo a seguir demonstra como gerar valores únicos e múltiplos para filas de armazenamento. A configuração necessária para function.json é a mesma de qualquer forma. O exemplo depende do modelo de programação v1 ou v2 do Python que você usa.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Para obter um exemplo de ponta a ponta de como configurar uma ligação de saída para o armazenamento de filas, consulte um destes artigos:

Atributos

O atributo que define uma associação de saída em bibliotecas C# depende do modo no qual a biblioteca de classes C# é executada.

Ao executar em um processo de trabalho isolado, você usa QueueOutputAttribute, que leva o nome da fila, conforme mostrado no exemplo a seguir:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Somente as variáveis retornadas têm suporte durante a execução em um processo de trabalho isolado. Parâmetros de saída não podem ser usados.

Decoradores

Aplica-se somente ao modelo de programação v2 do Python.

Para funções do Python v2 definidas usando um decorador, as seguintes propriedades no queue_output:

Propriedade DESCRIÇÃO
arg_name O nome da variável que representa a fila no código de função.
queue_name O nome da fila.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Filas do Azure. Confira a opção Conexões.

Para funções do Python definidas usando function.json, confira a seção Configuração.

Anotações

A anotação QueueOutput permite que você grave uma mensagem como a saída de uma função. O exemplo a seguir mostra uma função disparada por HTTP que cria uma mensagem de fila.

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
Propriedade Descrição
name Declara o nome do parâmetro na assinatura de função. Quando a função é disparada, o valor desse parâmetro tem o conteúdo da mensagem da fila.
queueName Declara o nome da fila na conta de armazenamento.
connection Aponta para a cadeia de conexão da conta de armazenamento.

O parâmetro associado à anotação QueueOutput é digitado como uma instância de OutputBinding<T>.

Configuração

Aplica-se apenas ao modelo de programação v1 do Python.

A tabela a seguir explica as propriedades que você pode definir no objeto options transmitido para o método output.storageQueue().

Propriedade Descrição
queueName O nome da fila.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Filas do Azure. Confira a opção Conexões.

Quando você estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na coleção Values.

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como queue. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como out. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que representa a fila no código de função. Definido como $return para referenciar o valor de retorno da função.
queueName O nome da fila.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Filas do Azure. Confira a opção Conexões.

Quando você estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na coleção Values.

Consulte a Seção de exemplo para obter exemplos completos.

Uso

O uso da associação de saída de fila depende da versão do pacote de extensão e da modalidade C# usada no aplicativo de funções, que pode ser uma das seguintes:

Uma função C# compilada da biblioteca de classes do processo de trabalho isolado é executada em um processo isolado do runtime.

Escolha uma versão para ver os detalhes de uso do modo e da versão.

Quando você desejar que a função escreva uma única mensagem, a associação de saída da fila pode ser associada aos seguintes tipos:

Type Descrição
string O conteúdo da mensagem como uma cadeia de caracteres. Use quando a mensagem for de texto simples.
byte[] Os bytes da mensagem.
Tipos serializáveis JSON Um objeto que representa o conteúdo de uma mensagem JSON. O Functions tenta serializar um tipo de objeto CLR básico (POCO) em dados JSON.

Quando você deseja que a função escreva várias mensagens, a associação de saída da fila pode ser associada aos seguintes tipos:

Type Descrição
T[] em que T é um dos tipos de mensagem única Uma matriz que contém conteúdo para várias mensagens. Cada entrada representa uma mensagem.

Para outros cenários de saída, crie e use um QueueClient com outros tipos de Azure.Storage.Queues diretamente. Consulte Registrar clientes do Azure para obter um exemplo de como usar a injeção de dependência para criar um tipo de cliente do SDK do Azure.

Há duas opções para gravar em uma fila a partir de uma função usando a anotação QueueOutput:

  • Valor retornado: ao aplicar a anotação à própria função, o valor retornado da função será gravado na fila.

  • Imperativo: para definir o valor da mensagem de modo explícito, aplique a anotação a um parâmetro específico do tipo OutputBinding<T>, em que T será um POJO ou um tipo de Java nativo. Com essa configuração, passar um valor para o método setValuegrava o valor na fila.

Acesse o item da fila de saída retornando o valor diretamente ou usando context.extraOutputs.set(). Você pode usar uma cadeia de caracteres ou um objeto serializável em JSON para o conteúdo de item de fila.

A saída para a mensagem de fila está disponível por do Push-OutputBinding em que você passa argumentos que correspondem ao nome designado pelo parâmetro name da associação no arquivo Push-OutputBinding.

Há duas opções para gravação a partir de sua função na fila configurada:

  • Valor retornado: definir a propriedade name no function.json para $return. Com essa configuração, o valor retornado da função será mantido como uma mensagem de armazenamento de Fila.

  • Imperativo: passe um valor para definir o método do parâmetro declarado como um tipo de Saída. O valor passado para set é persistido como uma mensagem de armazenamento de Fila.

conexões

A propriedade connection é uma referência à configuração do ambiente que especifica como o aplicativo deve se conectar às Filas do Azure. Ela pode especificar:

Se o valor configurado for uma combinação exata para uma única configuração e um correspondência de prefixo para outras configurações, a correspondente exata será usada.

Cadeia de conexão

Para obter uma cadeia de conexão, execute as etapas mostradas em Gerenciar as chaves de acesso à conta de armazenamento.

Essa cadeia de conexão deve ser armazenada em uma configuração de aplicativo com um nome que corresponda ao valor especificado pela propriedade connection da configuração de associação.

Se o nome de configuração do aplicativo começar com "AzureWebJobs", você pode especificar apenas o resto do nome aqui. Por exemplo, se você definir connection como "MyStorage", o runtime do Functions vai procurar uma configuração de aplicativo chamada "AzureWebJobsMyStorage". Se você mantiver connection vazio, o runtime do Functions usará a cadeia de conexão do Armazenamento padrão na configuração de aplicativo chamada AzureWebJobsStorage.

Conexões baseadas em identidade

Se você estiver usando a versão 5.x ou superior da extensão (pacote 3.x ou superior para pilhas de idiomas non-.NET), em vez de usar uma cadeia de conexão com um segredo, poderá fazer com que o aplicativo use uma identidade do Microsoft Entra. Para usar uma identidade, você define as configurações sob um prefixo comum que mapeia para a propriedade connection na configuração do gatilho e da vinculação.

Se estiver definindo connection como "AzureWebJobsStorage", confira Como se conectar ao armazenamento host com uma identidade. Para todas as outras conexões, a extensão requer as seguintes propriedades:

Propriedade Modelo de variável de ambiente Descrição Valor de exemplo
URI do Serviço de Fila <CONNECTION_NAME_PREFIX>__queueServiceUri1 O URI do plano de dados do serviço de fila ao qual você está se conectando, usando o esquema HTTPS. https://<storage_account_name>.queue.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri pode ser usado como um alias. Se as duas formas forem fornecidas, a forma usada será queueServiceUri. O formulário serviceUri não pode ser usado quando a configuração geral da conexão deve ser usada em blobs, filas e/ou tabelas.

Outras propriedades podem ser definidas para personalizar a conexão. Confira Propriedades comuns para conexões baseadas em identidade.

Quando hospedadas no serviço de Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída pelo sistema é usada por padrão, embora a identidade atribuída pelo usuário possa ser especificada com as propriedades credential e clientID. Observe que não há suporte para configurar uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, a identidade do desenvolvedor é usada, embora isso possa ser personalizado. Confira Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão para a identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços do Azure, isso significa que será necessário atribuir uma função no Azure RBAC, usando as funções internas ou as personalizadas que fornecem essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o escopo apenas sobre os recursos que precisam ser lidos.

Será necessário criar uma atribuição de função que forneça acesso a sua fila em runtime. Funções de gerenciamento como Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Armazenamento de Filas em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código escrito por você.

Tipo de associação Exemplo de funções internas
Gatilho Leitor de dados da fila de armazenamento, Processador de mensagens de dados de fila de armazenamento
Associação de saída Colaborador de dados da fila de armazenamento, Remetente de mensagens de dados de fila de armazenamento

Exceções e códigos de retorno

Associação Referência
Fila Fila de códigos de erro
Blob, tabela, fila Códigos de erro de armazenamento
Blob, tabela, fila Solução de problemas

Próximas etapas