Compartilhar via

Visão geral de associações e do gatilho de armazenamento de fila do Azure para o Azure Functions

  • Artigo

O Azure Functions pode executar enquanto novas mensagens de armazenamento de fila do Azure são criadas e pode gravar mensagens de fila em uma função.

Ação Tipo
Executar uma função enquanto os dados de armazenamento de fila são alterados Gatilho
Gravar mensagens de armazenamento de fila Associação de saída

Instalar a extensão

O pacote NuGet da extensão instalado depende do modo C# usado no aplicativo de funções:

As funções são executadas em um processo de trabalho do C# isolado. Para saber mais, confira o Guia para executar C# do Azure Functions em um processo de trabalho isolado.

A funcionalidade da extensão varia de acordo com a versão da extensão:

Essa versão apresenta a capacidade de se conectar usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções com conexões baseadas em identidade.

Essa versão permite que você se associe a tipos do Azure.Storage.Queues.

Esta versão oferece suporte à configuração de gatilhos e associações por meio da integração do .NET Aspire.

Adicione a extensão ao seu projeto instalando o pacote NuGet, versão 5.x.

Usando a CLI do .NET:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

Observação

Agora, os Blobs do Azure, as Filas do Azure e as Tabelas do Azure usam extensões separadas e são referenciados individualmente. Por exemplo, para usar os gatilhos e as associações para os três serviços no aplicativo de processo isolado .NET, você deve adicionar os seguintes pacotes ao projeto:

Anteriormente, as extensões eram enviadas juntas como Microsoft.Azure.Functions.Worker.Extensions.Storage, versão 4.x. Esse mesmo pacote também tem uma versão 5.x, que faz referência apenas aos pacotes divididos para blobs e filas. Ao atualizar as referências de pacote de versões mais antigas, talvez seja necessário também fazer referência ao novo pacote NuGet Microsoft.Azure.Functions.Worker.Extensions.Tables. Além disso, ao referenciar esses pacotes divididos mais recentes, verifique se você não está fazendo referência a uma versão mais antiga do pacote de armazenamento combinado, pois isso resultará em conflitos de duas definições das mesmas associações.

Instalar pacote

A associação do armazenamento de blobs faz parte de um pacote de extensão que é especificado no arquivo de projeto host.json. Talvez seja necessário modificar esse pacote se for preciso alterar a versão das associações ou se os pacotes ainda não estiverem instalados. Para saber mais, confira pacotes de extensão.

Essa versão apresenta a capacidade de se conectar usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções com conexões baseadas em identidade.

Você pode adicionar esta versão da extensão do pacote de extensão de versão prévia v3 adicionando ou substituindo o seguinte código em seu arquivo host.json:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Para saber mais, confira Atualizar suas extensões.

Tipos de associação

Os tipos de associação com suporte para .NET dependem da versão da extensão e do modo de execução do C#, que pode ser um dos seguintes:

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

Escolha uma versão para ver os detalhes do tipo de associação para o modo e a versão.

O processo de trabalho isolado dá suporte a tipos de parâmetro de acordo com a tabela abaixo. O suporte para associação a tipos de Azure.Storage.Queues está em versão prévia.

Gatilho de Fila

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.

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

Associação da saída da fila

Quando você desejar que a função escreva uma única mensagem, a associação de saída da fila pode ser associada 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 Um objeto que representa o conteúdo de uma mensagem JSON. O Functions tenta serializar um tipo de objeto CLR básico (POCO) em dados JSON.

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

Type Descrição
T[] em que 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 um QueueClient com outros tipos de Azure.Storage.Queues diretamente. Consulte Registrar clientes do Azure para obter um exemplo de como usar a injeção de dependência para criar um tipo de cliente do SDK do Azure.

configurações de host.json

Esta seção descreve as definições de configuração disponíveis para a associação nas versões 2.x e superiores. As configurações no arquivo host.json se aplicam a todas as funções em uma instância do aplicativo de funções. O arquivo host.json de exemplo abaixo contém apenas as configurações das versões 2.x e superiores para a associação. Para saber mais sobre as definições de configuração do aplicativo de funções nas versões 2.x e superiores, confira a referência de host.json para o Azure Functions.

Observação

Para obter uma referência de host.json no Functions 1.x, confira Referência de host.json para o Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
Propriedade Padrão Descrição
maxPollingInterval 00:01:00 O intervalo máximo entre as sondagens de fila. O intervalo mínimo é 00:00:00,100 (100 ms). Intervalos incrementados até maxPollingInterval. O valor padrão de maxPollingInterval é de 00:01:00 (1 min). maxPollingInterval não deve ser menor que 00:00:00,100 (100 ms). No Functions 2.x e posterior, o tipo de dados é um TimeSpan. No Functions 1.x, ele está em milissegundos.
visibilityTimeout 00:00:00 O intervalo de tempo entre as repetições quando o processamento de uma mensagem falha.
batchSize 16 O número de mensagens em fila que o runtime de Funções recupera simultaneamente e processa em paralelo. Quando o número que está sendo processado chega até newBatchThreshold, 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 é batchSize mais newBatchThreshold. Esse limite se aplica separadamente a cada função acionada por fila.

Se quiser evitar uma execução paralela para mensagens recebidas em uma fila, é possível definir batchSize como 1. No entanto, essa configuração elimina a simultaneidade desde que seu aplicativo de funções seja executado em uma única VM (máquina virtual). Se o aplicativo de função se expande para várias VMs, cada VM pode executar uma instância de cada função acionada por fila.

O máximo batchSize é 32.
maxDequeueCount 5 O número de vezes para tentar processar uma mensagem antes de movê-la para a fila de mensagens suspeitas.
newBatchThreshold N*batchSize/2 Sempre que o número de mensagens processadas simultaneamente chega a esse número, o runtime recupera outro lote.

N representa o número de vCPUs disponíveis durante a execução no Serviço de Aplicativo ou nos Planos Premium. Seu valor é 1 para o Plano de Consumo.
messageEncoding base64 Essa configuração só está disponível na versão do pacote de extensão 5.0.0 e superior. Ela representa o formato de codificação para mensagens. Os valores válidos são base64 e none.

Próximas etapas