Partilhar via

Gatilho de armazenamento de fila do Azure para o Azure Functions

  • Artigo

O gatilho de armazenamento de fila executa uma função à medida que as mensagens são adicionadas ao armazenamento de filas do Azure.

As decisões de dimensionamento do armazenamento em fila do Azure para os planos Consumo e Premium são feitas por meio do dimensionamento baseado em destino. Para obter mais informações, consulte Dimensionamento baseado em destino.

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

Use o gatilho de fila para iniciar uma função quando um novo item é recebido em uma fila. A mensagem da fila é apresentada como uma entrada da função.

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.

O exemplo a seguir mostra uma função C# que sonda a fila input-queue e grava várias mensagens em uma fila de saída cada vez que um item de fila é processado.

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

O exemplo Java a seguir mostra uma função de gatilho de fila de armazenamento, que registra a mensagem acionada colocada na fila myqueuename.

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

O exemplo a seguir mostra uma função TypeScript de gatilho de fila. A função sonda a fila myqueue-items e grava um log cada vez que um item de fila é processado.

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

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Storage queue function processed work item:', queueItem);
    context.log('expirationTime =', context.triggerMetadata.expirationTime);
    context.log('insertionTime =', context.triggerMetadata.insertionTime);
    context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
    context.log('id =', context.triggerMetadata.id);
    context.log('popReceipt =', context.triggerMetadata.popReceipt);
    context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: storageQueueTrigger1,
});

A seção de uso explica queueItem. A seção de metadados da mensagem explica todas as outras variáveis mostradas.

O exemplo a seguir mostra uma função JavaScript de gatilho de fila. A função sonda a fila myqueue-items e grava um log cada vez que um item de fila é processado.

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: (queueItem, context) => {
        context.log('Storage queue function processed work item:', queueItem);
        context.log('expirationTime =', context.triggerMetadata.expirationTime);
        context.log('insertionTime =', context.triggerMetadata.insertionTime);
        context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
        context.log('id =', context.triggerMetadata.id);
        context.log('popReceipt =', context.triggerMetadata.popReceipt);
        context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
    },
});

A seção de uso explica queueItem. A seção de metadados da mensagem explica todas as outras variáveis mostradas.

O exemplo a seguir demonstra como ler uma mensagem de fila passada para uma função por meio de um gatilho.

Um gatilho de fila de armazenamento é definido em function.json arquivo onde type está definido como queueTrigger .

{
  "bindings": [
    {
      "name": "QueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

O código no arquivo Run.ps1 declara um parâmetro como $QueueItem, que permite que você leia a mensagem de fila em sua função.

# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"

O exemplo a seguir demonstra como ler uma mensagem de fila passada para uma função por meio de um gatilho. 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="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
                   connection="storageAccountConnectionString")  # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
                 connection="storageAccountConnectionString")  # Queue output binding
def test_function(msg: func.QueueMessage,
                  outputQueueItem: func.Out[str]) -> None:
    logging.info('Python queue trigger function processed a queue item: %s',
                 msg.get_body().decode('utf-8'))
    outputQueueItem.set('hello')

Atributos

As bibliotecas C# de processo de trabalho em processo e isoladas usam o QueueTriggerAttribute para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Em bibliotecas de classe C#, o construtor do atributo usa o nome da fila para monitorar, conforme mostrado no exemplo a seguir:

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

Este exemplo também demonstra a configuração da cadeia de conexão no próprio atributo.

Anotações

A QueueTrigger anotação dá acesso à fila que aciona a função. O exemplo a seguir torna a mensagem de fila disponível para a função por meio do message parâmetro.

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

public class QueueTriggerDemo {
    @FunctionName("QueueTriggerDemo")
    public void run(
        @QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
        final ExecutionContext context
    ) {
        context.getLogger().info("Queue message: " + message);
    }
}
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.

Decoradores

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

Para funções Python v2 definidas usando decoradores, as seguintes propriedades no queue_trigger decorador definem o gatilho Queue Storage:

Property Description
arg_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.
queue_name Declara o nome da fila na conta de armazenamento.
connection Aponta para a cadeia de conexão da conta de armazenamento.

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

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 app.storageQueue() método.

Property Description
queueName O nome da fila a ser pesquisada.
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.

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

function.json propriedade Description
type Deve ser definido como queueTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direção Somente no arquivo function.json . Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
Designação O nome da variável que contém a carga útil do item de fila no código da função.
queueName O nome da fila a ser pesquisada.
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.

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

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

Utilização

Nota

As funções esperam uma cadeia de caracteres codificada em base64 . Quaisquer ajustes no tipo de codificação (para preparar dados como uma cadeia de caracteres codificada em base64 ) precisam ser implementados no serviço de chamada.

O uso do gatilho Fila depende da versão do pacote de extensão e da modalidade C# usada em seu aplicativo de função, que pode ser um destes modos:

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.

O gatilho de 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 de texto simples..
byte[] Os bytes da mensagem.
Tipos serializáveis JSON Quando uma mensagem de fila contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR (POCO) antigo.
QueueMessage1 A mensagem.
BinaryData1 Os bytes da mensagem.

1 Para usar esses tipos, você precisa fazer referência a Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 ou posterior e às dependências comuns para associações de tipo SDK.

A anotação QueueTrigger dá acesso à mensagem de fila que disparou a função.

Acesse o item de fila como o primeiro argumento para sua função. Se a carga for JSON, o valor será desserializado em um objeto.

Acesse a mensagem de fila por meio do parâmetro string que corresponde ao nome designado pelo parâmetro da name ligação no arquivo function.json .

Acesse a mensagem de fila por meio do parâmetro digitado como QueueMessage.

Metadados

O gatilho de fila fornece várias propriedades de metadados. 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, para trabalhadores de linguagem que fornecem esse acesso aos metadados da mensagem.

As propriedades de metadados de mensagem são membros da classe CloudQueueMessage .

As propriedades dos metadados da mensagem podem ser acessadas em context.triggerMetadata.

As propriedades de metadados da mensagem podem ser acessadas a partir do parâmetro passado $TriggerMetadata .

Propriedade Type Description
QueueTrigger string Carga útil da fila (se for uma cadeia de caracteres válida). Se a carga útil da mensagem da fila for uma cadeia de caracteres, QueueTrigger terá o mesmo valor que a variável nomeada pela name propriedade em function.json.
DequeueCount long O número de vezes que esta mensagem foi retirada da fila.
ExpirationTime DateTimeOffset A hora em que a mensagem expira.
Id string ID da mensagem da fila.
InsertionTime DateTimeOffset A hora em que a mensagem foi adicionada à fila.
NextVisibleTime DateTimeOffset A próxima hora em que a mensagem estará visível.
PopReceipt string O recibo pop da mensagem.

As seguintes propriedades de metadados de mensagem podem ser acessadas a partir do parâmetro de vinculação passado (msg em exemplos anteriores).

Property Description
body Fila de carga como uma cadeia de caracteres.
dequeue_count O número de vezes que esta mensagem foi retirada da fila.
expiration_time A hora em que a mensagem expira.
id ID da mensagem da fila.
insertion_time A hora em que a mensagem foi adicionada à fila.
time_next_visible A próxima hora em que a mensagem estará visível.
pop_receipt O recibo pop da mensagem.

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

Mensagens venenosas

Quando uma função de gatilho de fila falha, o Azure Functions tenta novamente a função até cinco vezes para uma determinada mensagem de fila, incluindo a primeira tentativa. Se todas as cinco tentativas falharem, o tempo de execução das funções adicionará uma mensagem a uma fila chamada originalqueuename-poison>.< Você pode escrever uma função para processar mensagens da fila de venenos registrando-as ou enviando uma notificação de que a atenção manual é necessária.

Para manipular mensagens suspeitas manualmente, verifique o dequeueCount da mensagem da fila.

Fechadura de espreitar

O padrão peek-lock acontece automaticamente para gatilhos de fila, usando a mecânica de visibilidade fornecida pelo serviço de armazenamento. À medida que as mensagens são retiradas da fila pela função acionada, elas são marcadas como invisíveis. A execução de uma função acionada por fila pode ter um destes resultados na mensagem na fila:

  • A execução da função é concluída com êxito e a mensagem é excluída da fila.
  • A execução da função falha e o host Functions atualiza a visibilidade da mensagem com base na visibilityTimeout configuração no arquivo host.json. O tempo limite de visibilidade padrão é zero, o que significa que a mensagem reaparece imediatamente na fila para reprocessamento. Use a visibilityTimeout configuração para atrasar o reprocessamento de mensagens que não são processadas. Essa configuração de tempo limite se aplica a todas as funções acionadas por fila no aplicativo de função.
  • O host Functions falha durante a execução da função. Quando esse evento incomum ocorre, o host não pode aplicar o visibilityTimeout à mensagem que está sendo processada. Em vez disso, a mensagem é deixada com o tempo limite padrão de 10 minutos definido pelo serviço de armazenamento. Após 10 minutos, a mensagem reaparece na fila para reprocessamento. Esse tempo limite padrão definido pelo serviço não pode ser alterado.

Algoritmo de sondagem

O gatilho de fila implementa um algoritmo de back-off exponencial aleatório para reduzir o efeito da sondagem de fila ociosa nos custos de transação de armazenamento.

O algoritmo usa a seguinte lógica:

  • Quando uma mensagem é encontrada, o tempo de execução aguarda 100 milissegundos e, em seguida, verifica se há outra mensagem.
  • Quando nenhuma mensagem é encontrada, ela aguarda cerca de 200 milissegundos antes de tentar novamente.
  • Após tentativas subsequentes com falha para obter uma mensagem de fila, o tempo de espera continua a aumentar até atingir o tempo máximo de espera, que por padrão é de um minuto.
  • O tempo máximo de espera é configurável através da maxPollingInterval propriedade no arquivo host.json.

Durante o desenvolvimento local, o intervalo máximo de sondagem tem como padrão dois segundos.

Nota

Em relação ao faturamento ao hospedar aplicativos de função no plano de consumo, você não é cobrado pelo tempo gasto na sondagem pelo tempo de execução.

Simultaneidade

Quando há várias mensagens de fila aguardando, o gatilho de fila recupera um lote de mensagens e invoca instâncias de função simultaneamente para processá-las. Por padrão, o tamanho do lote é 16. Quando o número que está sendo processado cai para 8, o tempo de execução recebe outro lote e começa a processar essas mensagens. Portanto, o número máximo de mensagens simultâneas sendo processadas por função em uma máquina virtual (VM) é 24. Esse limite se aplica separadamente a cada função acionada por fila em cada VM. Se o seu aplicativo de função for expandido para várias VMs, cada VM aguardará gatilhos e tentará executar funções. Por exemplo, se um aplicativo de função for expandido para 3 VMs, o número máximo padrão de instâncias simultâneas de uma função acionada por fila será 72.

O tamanho do lote e o limite para obter um novo lote são configuráveis no arquivo host.json. Se quiser minimizar a execução paralela para funções acionadas por fila em um aplicativo de função, você pode definir o tamanho do lote como 1. Essa configuração elimina a simultaneidade apenas enquanto seu aplicativo de função for executado em uma única máquina virtual (VM).

O gatilho de fila impede automaticamente que uma função processe uma mensagem de fila várias vezes simultaneamente.

host.json propriedades

O arquivo host.json contém configurações que controlam o comportamento do gatilho da fila. Consulte a seção Configurações de host.json para obter detalhes sobre as configurações disponíveis.

Próximos passos