Partilhar 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 da Fila do Azure configurando uma associação de saída.

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

Importante

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

O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

Este artigo suporta ambos os modelos de programação.

Exemplo

Uma função C# pode ser criada usando um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
  • Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte total.

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

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

    // Queue Output messages
    return messages;
}

Para obter um exemplo completo de como configurar uma ligação de saída para o armazenamento em fila, 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;
 }

Na biblioteca de tempo de execução de funções Java, use a @QueueOutput anotação em parâmetros cujo valor seria gravado no armazenamento em fila. O tipo de parâmetro deve ser OutputBinding<T>, onde T é qualquer tipo Java nativo de um POJO.

Para obter um exemplo completo de como configurar uma ligação de saída para o armazenamento em fila, consulte um destes artigos:

O exemplo a seguir mostra uma função TypeScript acionada por HTTP que cria um item de 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 acionada por HTTP que cria um item de 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 completo de como configurar uma ligação de saída para o armazenamento em fila, consulte um destes artigos:

Os exemplos de código a seguir demonstram como gerar uma mensagem de fila de uma função acionada por HTTP. A seção de configuração com o type de define a ligação de queue 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 vinculação, uma função do PowerShell pode criar uma mensagem de fila usando Push-OutputBindingo . Neste exemplo, uma mensagem é criada a partir de uma cadeia de caracteres de consulta ou parâmetro body.

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 só vez, defina uma matriz de mensagens e use Push-OutputBinding para enviar mensagens para a ligaçã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 completo de como configurar uma ligação de saída para o armazenamento em fila, consulte um destes artigos:

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

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 completo de como configurar uma ligação de saída para o armazenamento em fila, consulte um destes artigos:

Atributos

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

Ao executar em um processo de trabalho isolado, você usa o 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 variáveis retornadas são suportadas quando executadas em um processo de trabalho isolado. Os parâmetros de saída não podem ser usados.

Decoradores

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

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

Property Description
arg_name O nome da variável que representa a fila no código da 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. Consulte Conexões.

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

Anotações

A anotação QueueOutput permite que você escreva uma mensagem como a saída de uma função. O exemplo a seguir mostra uma função acionada 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();
    }
}
Property Description
name Declara o nome do parâmetro na assinatura da função. Quando a função é acionada, o valor desse parâmetro tem o conteúdo da mensagem de 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 OutputBinding<T>.

Configuração

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

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

Property Description
queueName O nome da fila.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Filas do Azure. Consulte Conexões.

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

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .

function.json propriedade Description
type Deve ser definido como queue. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direção Deve ser definido como out. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
Designação O nome da variável que representa a fila no código da função. Defina como $return para fazer referência ao valor de retorno da função.
queueName O nome da fila.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Filas do Azure. Consulte Conexões.

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

Consulte a seção Exemplo para obter exemplos completos.

Utilização

O uso da vinculação de saída Queue depende da versão do pacote de extensão e da modalidade C# usada em seu aplicativo de função, que pode ser uma das seguintes:

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

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

Quando você deseja que a função escreva uma única mensagem, a ligação de saída da fila pode se vincular aos seguintes tipos:

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

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

Tipo Description
T[] onde 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 tipos de Azure.Storage.Queues diretamente.

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

  • Valor de retorno: Ao aplicar a anotação à própria função, o valor de retorno da função é gravado na fila.

  • Imperativo: Para definir explicitamente o valor da mensagem, aplique a anotação a um parâmetro específico do tipo OutputBinding<T>, onde T é um POJO ou qualquer tipo Java nativo. Com essa configuração, passar um valor para o setValue método grava o valor na fila.

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

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

Há duas opções para escrever a partir da sua função para a fila configurada:

  • Valor de retorno: defina a name propriedade em function.json como $return. Com essa configuração, o valor de retorno da função é mantido como uma mensagem de armazenamento de fila.

  • Imperativo: Passe um valor para o método set do parâmetro declarado como um tipo out . O valor passado para set é persistido como uma mensagem de armazenamento de fila.

Ligações

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

  • O nome de uma configuração de aplicativo que contém uma cadeia de conexão
  • O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade.

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

Connection string

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

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

Se o nome da configuração do aplicativo começar com "AzureWebJobs", você poderá especificar apenas o restante do nome aqui. Por exemplo, se você definir connection como "MyStorage", o tempo de execução do Functions procurará uma configuração de aplicativo chamada "AzureWebJobsMyStorage". Se você deixar connection vazio, o tempo de execução do Functions usará a cadeia de conexão de armazenamento padrão na configuração do 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, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para usar uma identidade, defina as configurações sob um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e ligação.

Se você estiver definindo connection como "AzureWebJobsStorage", consulte Conectando-se ao armazenamento de host com uma identidade. Para todas as outras conexões, a extensão requer as seguintes propriedades:

Property Modelo de variável de ambiente Description 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>

<CONNECTION_NAME_PREFIX>__serviceUri 1 pode ser usado como um alias. Se ambos os formulários forem fornecidos, o queueServiceUri formulário é usado. O serviceUri formulário 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. Consulte Propriedades comuns para conexões baseadas em identidade.

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

Conceder permissão à 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 você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha escopo apenas sobre os recursos que precisam ser lidos.

Você precisará criar uma atribuição de função que forneça acesso à sua fila em tempo de execução. Funções de gestão como Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão de Armazenamento em Fila em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação Exemplo de funções internas
Acionador Leitor de dados da fila de armazenamento, processador de mensagens de dados da fila de armazenamento
Vinculação de saída Contribuidor de dados da fila de armazenamento, remetente de mensagem de dados da fila de armazenamento

Exceções e códigos de devolução

Enlace Referência
Queue Códigos de erro de fila
Blob, Tabela, Fila Códigos de erro de armazenamento
Blob, Tabela, Fila Resolução de problemas

Próximos passos