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.

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 usando um dos seguintes modos C#:

O exemplo a seguir mostra uma função C# que consulta a fila 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);
}

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 , 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 é 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 , 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.

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

{
  "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 , 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

As bibliotecas C# em processo e de processo isolado usam o atributo QueueTriggerAttribute para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json.

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.

Configuração

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

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 de Fila depende da versão do pacote de extensão e da modalidade do C# usada no aplicativo de funções, que pode ser uma das seguintes:

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.

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:

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.

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

O conteúdo do item da fila está disponível por meio de context.bindings.<NAME>, em que <NAME> corresponde ao nome definido em context.bindings.<NAME>. 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.

As propriedades são membros da classe CloudQueueMessage.

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 int 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.

conexões

A propriedade connection é uma referência à configuração de 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, em vez de usar uma cadeia de conexão com um segredo, faça com que o aplicativo use uma identidade do Azure Active Directory. Para fazer isso, defina as configurações em um prefixo comum que mapeia para a propriedade connection na configuração de gatilho e de associação.

Se estiver definindo connection como "AzureWebJobsStorage", consulte Conectar-se ao armazenamento do host usando 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 pode ser usado como um alias. Se as duas formas forem fornecidas, a forma queueServiceUri será usada. A forma serviceUri não pode ser usada quando a configuração de conexão geral tiver que ser usada entre blobs, filas e/ou tabelas.

É possível definir propriedades adicionais 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. Você precisará atribuir uma função no controle de acesso baseado em função do Azure usando funções internas ou personalizadas que forneçam 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 peek-lock ocorre automaticamente para gatilhos de fila. À medida que as mensagens são removidas da fila, elas são marcadas como invisíveis e associadas a um tempo limite gerenciado pelo serviço de Armazenamento.

Quando a função é iniciada, ela inicia o processamento de uma mensagem sob as condições a seguir.

  • Se a função for bem-sucedida, a execução da função será concluída e a mensagem será excluída.
  • Se a função falhar, a visibilidade da mensagem será redefinida. Após a redefinição, a mensagem será reprocessada na próxima vez que a função solicitar uma nova mensagem.
  • Se a função nunca for concluída devido a uma falha, a visibilidade da mensagem expirará e a mensagem reaparecerá na fila.

Toda a mecânica de visibilidade será manipulada pelo serviço de Armazenamento, não pelo runtime do Functions.

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 a mensagem for encontrada, o runtime aguardará 100 milissegundos e verificará 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.

Para o desenvolvimento local, o intervalo máximo de sondagem padrão é de 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 aplicativo de função for escalado horizontalmente 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