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.

Codificaçã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.

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.

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

Atributos e anotações

Em bibliotecas de classes C#, use os seguintes atributos para configurar um gatilho de fila:

  • QueueTriggerAttribute

    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)
    {
        ....
    }
    

    Para ver um exemplo completo, confira o exemplo.

  • StorageAccountAttribute

    Oferece uma maneira de especificar a conta de armazenamento para usar. 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("QueueTrigger")]
        [StorageAccount("FunctionLevelStorageAppSetting")]
        public static void Run( //...
    {
        ...
    }
    

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

  • A propriedade QueueTrigger do atributoConnection.
  • O StorageAccount atributo aplicado ao mesmo parâmetro do QueueTrigger atributo.
  • O StorageAccount atributo aplicado à função.
  • O StorageAccount atributo aplicado à classe.
  • A configuração do aplicativo "AzureWebJobsStorage".

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

Propriedade function.json Propriedade de atributo Descrição
tipo n/d Deve ser definido como queueTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction n/d Apenas no arquivo function.json. Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name n/d O nome da variável que contém o conteúdo do item de fila no código da função.
queueName QueueName O nome da fila a ser controlada.
connection Conexão O nome de uma configuração de aplicativo que contém uma cadeia de conexão de Armazenamento para usar para essa 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ê configurar connection para "MyStorage", o runtime do Functions procurará por uma configuração de aplicativo chamada "MyStorage". Se você deixar connection vazio, o runtime de Functions usa a cadeia de caracteres de conexão de Armazenamento padrão na configuração de aplicativo chamada AzureWebJobsStorage.

Caso esteja usando a versão 5.x ou posterior da extensão, em vez de uma cadeia de conexão, será possível fornecer uma referência a uma seção de configuração que definirá a conexão. Confira a opção Conexões.

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.

Uso

Padrão

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

  • Objeto - o runtime do Functions desserializa um conteúdo JSON em uma instância de uma classe arbitrária definida em seu código.
  • string
  • byte[]
  • CloudQueueMessage

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.

Tipos adicionais

Os aplicativos que usam a versão 5.0.0 ou posterior da extensão de Armazenamento também poderão usar tipos do SDK do Azure para .NET. Essa versão removerá o suporte do tipo CloudQueueMessage herdado para beneficiar os seguintes tipos:

Para obter exemplos de como usar esses tipos, confira o repositório GitHub da extensão.

Metadados da mensagem

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 Tipo 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 function.json.
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.

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 arquivo host.json.

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