Partilhar via

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

  • Artigo

O Azure Functions pode ser executado à medida que novas mensagens de armazenamento de fila do Azure são criadas e pode gravar mensagens de fila dentro de uma função.

Ação Type
Executar uma função como alterações de dados de armazenamento de fila Acionador
Gravar mensagens de armazenamento em fila Vinculação de saída

Instalar a extensão

O pacote de extensão NuGet que você instala depende do modo C# que você está usando em seu aplicativo de função:

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

A funcionalidade da extensão varia dependendo da versão da extensão:

Esta versão introduz a capacidade de se conectar usando uma identidade em vez de um segredo. Para obter um tutorial sobre como configurar seus aplicativos de função com identidades gerenciadas, consulte o tutorial de criação de um aplicativo de função com conexões baseadas em identidade.

Esta versão permite que você se associe a tipos de Azure.Storage.Queues.

Esta versão suporta a configuração de gatilhos e ligações através 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

Nota

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

Anteriormente, as extensões eram fornecidas juntas como Microsoft.Azure.Functions.Worker.Extensions.Storage, versão 4.x. Este mesmo pacote também tem uma versão 5.x, que faz referência aos pacotes divididos apenas para blobs e filas. Ao atualizar suas referências de pacote de versões mais antigas, talvez seja necessário fazer referência adicional ao novo pacote NuGet Microsoft.Azure.Functions.Worker.Extensions.Tables . Além disso, ao fazer referência a esses pacotes divididos mais recentes, certifique-se de não estar 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 de armazenamento de Blob faz parte de um pacote de extensão, que é especificado em seu arquivo de projeto host.json. Talvez seja necessário modificar esse pacote para alterar a versão da associação ou se os pacotes ainda não estiverem instalados. Para saber mais, consulte Pacote de extensão.

Esta versão introduz a capacidade de se conectar usando uma identidade em vez de um segredo. Para obter um tutorial sobre como configurar seus aplicativos de função com identidades gerenciadas, consulte o tutorial de criação de um aplicativo de função com conexões baseadas em identidade.

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

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

Para saber mais, consulte Atualizar suas extensões.

Tipos de vinculação

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

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 do tipo de vinculação para o modo e a versão.

O processo de trabalho isolado suporta tipos de parâmetros de acordo com as tabelas abaixo. O suporte para associação a tipos de Azure.Storage.Queues está em pré-visualização.

Gatilho de fila

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.

Vinculação de saída de fila

Quando você deseja que a função escreva uma única mensagem, a ligação de saída da 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 texto simples.
byte[] Os bytes da mensagem.
Tipos serializáveis JSON Um objeto que representa o conteúdo de uma mensagem JSON. Functions tenta serializar um tipo de objeto CLR (POCO) simples em dados JSON.

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

Tipo Description
T[] onde 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 a partir do SDK do Azure.

host.json configurações

Esta seção descreve as definições de configuração disponíveis para essa 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 de aplicativo de função. O exemplo host.json arquivo abaixo contém apenas as configurações da versão 2.x+ para essa ligação. Para obter mais informações sobre definições de configuração de aplicativo de função nas versões 2.x e versões posteriores, consulte host.json referência para o Azure Functions.

Nota

Para obter uma referência de host.json no Functions 1.x, consulte host.json referência do 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"
        }
    }
}
Property Predefinição Description
maxPollingInterval 00:01:00 O intervalo máximo entre as sondagens da fila. O intervalo mínimo é 00:00:00.100 (100 ms). Os intervalos aumentam até maxPollingInterval. O valor padrão de maxPollingInterval é 00:01:00 (1 min). maxPollingInterval não deve ser inferior a 00:00:00.100 (100 ms). No Functions 2.x e posterior, o tipo de dados é um TimeSpanarquivo . No Functions 1.x, é em milissegundos.
visibilidadeTempo limite 00:00:00 O intervalo de tempo entre novas tentativas quando o processamento de uma mensagem falha.
batchSize 16 O número de mensagens de fila que o tempo de execução do Functions recupera simultaneamente e processa em paralelo. Quando o número que está sendo processado desce para o newBatchThreshold, o tempo de execução recebe outro lote e começa a processar essas mensagens. Assim, o número máximo de mensagens simultâneas sendo processadas por função é batchSize mais newBatchThreshold. Esse limite se aplica separadamente a cada função acionada por fila.

Se quiser evitar a execução paralela de mensagens recebidas em uma fila, você pode definir batchSize como 1. No entanto, essa configuração elimina a simultaneidade, desde que seu aplicativo de função seja executado apenas em uma única máquina virtual (VM). Se o aplicativo de função for expandido para várias VMs, cada VM poderá 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 venenos.
newBatchThreshold N*batchSize/2 Sempre que o número de mensagens que estão sendo processadas simultaneamente é reduzido a esse número, o tempo de execução recupera outro lote.

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

Próximos passos