Gatilho do Armazenamento de Filas do Azure do Azure para o Azure Functions

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

As decisões de ampliação de armazenamento da Fila de Espera do Azure para os planos Consumo e Premium são tomadas por meio da ampliação baseada no destino. Para obter mais informações, consulte Ampliação baseada em destino.

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.

v2

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.

v1

O modelo de programação v1 do Python requer que você defina as associações em um arquivo function.json separado na pasta de funções. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a 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 é fornecida como entrada para a função.

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.

Modelo de trabalho isolado

O exemplo a seguir mostra uma função C# que consulta a fila input-queue e grava várias mensagens em uma fila de saída cada vez que um item da 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}"};

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

    // Queue Output messages
    return messages;
}

Modelo em processo

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.

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

O exemplo Java a seguir mostra a função de gatilho da 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);
}

Modelo v4

O exemplo a seguir mostra uma função TypeScript de gatilho de fila. A função controla a myqueue-items fila 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 uso explica queueItem. A seção de metadados de mensagem explica todas as outras variáveis mostradas.

Modelo v3

As amostras de TypeScript não estão documentadas para o modelo v3.

Modelo v4

O exemplo a seguir mostra uma função JavaScript do gatilho de fila. A função controla a myqueue-items fila 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 uso explica queueItem. A seção de metadados de mensagem explica todas as outras variáveis mostradas.

Modelo v3

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. A função controla a myqueue-items fila e grava um log cada vez que um item de fila é processado.

Aqui está o arquivo function.json:

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

A seção configuração explica essas propriedades.

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. Essa carga útil também é passada como o segundo parâmetro para a função.

Aqui está o código JavaScript:

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

A seção uso explica myQueueItem, que é chamado pela name propriedade function.json. A seção de metadados de 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 no arquivo function.json em que type é 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 da 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 varia dependendo de você utilizar o modelo de programação v1 ou v2 do Python.

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')

v1

Um gatilho de fila de Armazenamento é definido em function.json, em que o tipo é definido como queueTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

O código no arquivo _init_.py declara um parâmetro como func.QueueMessage, que permite que você leia a mensagem da fila em sua função.

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)

Atributos

Ambas as bibliotecas C# em processo e no processo de trabalho isolado 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 do script C#.

Modelo de trabalho isolado

Nas bibliotecas da 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 como definir a configuração da cadeia de conexão no próprio atributo.

Modelo em processo

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

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

Você pode definir a propriedade Connection para especificar a configuração do aplicativo que contém a cadeia de conexão da conta de armazenamento a ser usada, conforme mostrado no seguinte exemplo:

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

Anotações

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

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

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.

Decoradores

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

Para as funções v2 do Python definidas utilizando decoradores, as seguintes propriedades no decorador queue_trigger definem os gatilhos do Armazenamento de Filas:

Propriedade	Descrição
arg_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.
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 do Python definidas usando function.json, confira a seção Configuração.

Configuração

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

Modelo v4

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

Propriedade	Descrição
queueName	O nome da fila a ser controlada.
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.

Modelo v3

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

Propriedade	Descrição
tipo	Deve ser definido como queueTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction	Apenas no arquivo function.json. Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name	O nome da variável que contém o conteúdo do item de fila no código da função.
queueName	O nome da fila a ser controlada.
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.

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

Propriedade function.json	Descrição
tipo	Deve ser definido como queueTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction	Apenas no arquivo function.json. Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name	O nome da variável que contém o conteúdo do item de fila no código da função.
queueName	O nome da fila a ser controlada.
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.

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

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

Uso

Observação

O Functions espera uma cadeia de caracteres codificada base64. 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.

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

Modelo de trabalho isolado

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

Biblioteca de classes em processo

Uma biblioteca de classes em processo é uma função C# compilada no mesmo processo que o runtime do Functions.

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

Extensão 5.x+

Acesse os dados da mensagem usando um parâmetro de método, como string paramName. O paramName é o valor especificado em QueueTriggerAttribute. É possível associar a qualquer um dos seguintes tipos:

• POCO (objeto CLR do .NET simples)
• string
• byte[]
• QueueMessage

Ao vincular a um objeto, o runtime do Functions tenta desserializar o payload JSON em uma instância de uma classe arbitrária definida em seu código. Para obter exemplos usando QueueMessage, consulte o repositório GitHub para a extensão.

Embora o atributo use uma propriedade Connection, não é possível usar Connection para especificar uma conexão da conta de armazenamento. Isso pode ser feito quando for necessário usar uma conta de armazenamento diferente de outras funções na biblioteca. O construtor toma o nome de uma configuração de aplicativo que contenha uma cadeia de conexão de armazenamento. O atributo pode ser aplicado no nível de classe, método ou parâmetro. O exemplo a seguir mostra o nível de classe e método:

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

A conta de armazenamento a ser usada é determinada na seguinte ordem:

• A propriedade Connection do atributo de gatilho ou associação.
• O atributo StorageAccount aplicado ao mesmo parâmetro do atributo de gatilho ou associação.
• O StorageAccount atributo aplicado à função.
• O StorageAccount atributo aplicado à classe.
• A conta de armazenamento padrão do aplicativo de funções, que é definido na configuração do aplicativo AzureWebJobsStorage.

Extensão 2.x+

Acesse os dados da mensagem usando um parâmetro de método, como string paramName. O paramName é o valor especificado em QueueTriggerAttribute. É possível associar a qualquer um dos seguintes tipos:

• Objeto CRL básico (POCO)
• string
• byte[]
• CloudQueueMessage

Ao vincular a um objeto, o runtime do Functions tenta desserializar o payload JSON em uma instância de uma classe arbitrária definida em seu código. 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.

Embora o atributo use uma propriedade Connection, não é possível usar Connection para especificar uma conexão da conta de armazenamento. Isso pode ser feito quando for necessário usar uma conta de armazenamento diferente de outras funções na biblioteca. O construtor toma o nome de uma configuração de aplicativo que contenha uma cadeia de conexão de armazenamento. O atributo pode ser aplicado no nível de classe, método ou parâmetro. O exemplo a seguir mostra o nível de classe e método:

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

A conta de armazenamento a ser usada é determinada na seguinte ordem:

• A propriedade Connection do atributo de gatilho ou associação.
• O atributo StorageAccount aplicado ao mesmo parâmetro do atributo de gatilho ou associação.
• O StorageAccount atributo aplicado à função.
• O StorageAccount atributo aplicado à classe.
• A conta de armazenamento padrão do aplicativo de funções, que é definido na configuração do aplicativo AzureWebJobsStorage.

Extensão 5.x+

O gatilho de fila pode se associar 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	Quando uma mensagem da fila contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR básico (POCO).
QueueMessage1	A mensagem.
BinaryData1	Os bytes da mensagem.

¹ Para usar esses tipos, você precisa referenciar Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 5.2.0-preview2 ou posterior e as dependências comuns para associações do tipo SDK.

Extensão 2.x+

Versões anteriores dessa extensão no processo de trabalho isolado só dão suporte à associação de cadeia de caracteres. Mais opções estão disponíveis para a Extensão 5.x+.

A anotação QueueTrigger fornece acesso à mensagem da fila que disparou a função.

Modelo v4

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

Modelo v3

Acesse o item de fila usando context.bindings.<NAME>, em que <NAME> corresponde ao valor definido em function.json. Se o conteúdo for JSON, o valor será desserializado em um objeto.

Acesse a mensagem da fila por meio do parâmetro de cadeia de caracteres que corresponde ao nome designado pelo parâmetro name da associação no arquivo name.

Acesse a mensagem da 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 trabalhos de linguagem que fornecem esse acesso a metadados de mensagens.

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

As propriedades de metadados da mensagem podem ser acessadas a partir do context.triggerMetadata.

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

Propriedade	Type	Descrição
QueueTrigger	string	Conteúdo da fila (se for uma cadeia de caracteres válida). Se o conteúdo da mensagem da fila for uma cadeia de caracteres, QueueTrigger tem o mesmo valor da variável nomeada pela propriedade name em QueueTrigger.
DequeueCount	long	O número de vezes que essa mensagem foi removida 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 hora em que a mensagem estará visível.
PopReceipt	string	Recebimento pop da mensagem.

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

Propriedade	Descrição
body	Carga útil da fila como uma cadeia de caracteres.
dequeue_count	O número de vezes que essa mensagem foi removida 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 hora em que a mensagem estará visível.
pop_receipt	Recebimento pop da mensagem.

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:

• O nome da configuração de um aplicativo contendo uma cadeia de conexão
• O nome de um prefixo compartilhado com várias configurações de aplicativo, definindo juntas uma conexão baseada em identidade.

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

¹ <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

Mensagens suspeitas

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. Se todas as cinco tentativas falharem, o runtime das funções adicionará uma mensagem em uma fila chamada <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.

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

Bloqueio de inspeção

O padrão de bloqueio de espiada ocorre automaticamente para gatilhos de fila, usando a mecânica de visibilidade fornecida pelo serviço de armazenamento. À medida que as mensagens são removidas da fila pela função disparada, elas são marcadas como invisíveis. A execução de uma função disparada 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 do 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 disparadas pela fila no aplicativo de funções.
• O host do 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 exponencial aleatório de retirada para reduzir o efeito de sondagem de fila ociosa nos custos das transações de armazenamento.

O algoritmo usa a seguinte lógica:

• Quando uma mensagem é encontrada, o runtime aguarda 100 milissegundos e verifica se há outra mensagem.
• Quando nenhuma mensagem for encontrada, ele aguardará cerca de 200 milissegundos antes de tentar novamente.
• 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.
• O tempo de espera máximo é configurável por meio da propriedade maxPollingInterval no maxPollingInterval.

Durante o desenvolvimento local, o intervalo máximo de sondagem é padronizado para dois segundos.

Observação

Com relação à cobrança ao hospedar aplicativos de funções no plano de Consumo, você não é cobrado pelo tempo gasto na sondagem pelo runtime.

Simultaneidade

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. Por padrão, o tamanho do lote é 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. 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. Esse limite se aplica separadamente a cada função acionada por fila em cada VM. Se o aplicativo de funções for dimensionado para várias VMs, cada VM aguardará gatilhos e tentará executar funções. 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.

O tamanho do lote e o limite para obtenção de 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ê poder definir o tamanho do lote para 1. Essa configuração elimina a simultaneidade, desde que seu aplicativo de função seja executado em uma única máquina virtual (VM).

O gatilho de fila impede de forma automática que uma função processe uma mensagem da fila várias vezes simultaneamente.

Propriedades de host.json

O arquivo host.json contém configurações que controlam o comportamento de gatilho de fila. Confira a seção Configurações de host.json para obter detalhes em relação às configurações disponíveis.

Próximas etapas

• Gravar mensagens de armazenamento de fila (associação de saída)