Compartilhar via

Associações do Barramento de Serviço para o Azure Functions

  • Artigo

O Azure Functions integra-se com o Barramento de Serviço do Azure por meio de gatilhos e associações. A integração com o Barramento de Serviço permite criar funções que reagem e enviam mensagens de tópico ou de fila.

Ação Tipo
Executar uma função quando uma fila ou mensagem de tópico do Barramento de Serviço for criada Gatilho
Enviar mensagens do Barramento de Serviço do Azure 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.

Adicione a extensão ao seu projeto instalando este pacote do NuGet.

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.Messaging.ServiceBus.

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.

Instalar pacote

A associação do Barramento de Serviço 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 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 de 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.

Gatilho de Barramento de Serviço

Quando você desejar que a função processe uma única mensagem, o gatilho do Barramento de Serviço pode ser associado aos seguintes tipos:

Type Descrição
string A mensagem como uma cadeia de caracteres. Use quando a mensagem for de texto simples.
byte[] Os bytes da mensagem.
Tipos serializáveis JSON Quando um evento contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR básico (POCO).
ServiceBusReceivedMessage1 O objeto da mensagem.

Ao associar ao ServiceBusReceivedMessage, você também pode incluir um parâmetro do tipo ServiceBusMessageActions1,2 para executar ações de liquidação de mensagens.

Quando você quiser que a função processe um lote de mensagens, o gatilho do Barramento de Serviço pode ser associado aos seguintes tipos:

Type Descrição
T[] em que T é um dos tipos de mensagem única Uma matriz de eventos do lote. Cada entrada representa um evento.

Ao associar ao ServiceBusReceivedMessage[], você também pode incluir um parâmetro do tipo ServiceBusMessageActions1,2 para executar ações de liquidação de mensagens.

1 Para usar esses tipos, você precisa referenciar o Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1-preview2 ou posterior e as dependências comuns das associações de tipo de SDK.

2 Ao usar ServiceBusMessageActionso , defina a AutoCompleteMessages propriedade do atributo de gatilho como false. Isso impede que o runtime tente concluir mensagens após uma invocação de função bem-sucedida.

Associação de saída do Barramento de Serviço

Quando você quiser que a função escreva uma única mensagem, a associação de saída do Barramento de Serviço pode ser associada aos seguintes tipos:

Type Descrição
string A 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 a mensagem. O Functions tenta serializar um tipo de objeto CLR básico (POCO) em dados JSON.

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

Type Descrição
T[] em que T é um dos tipos de mensagem única Uma matriz que contém várias mensagens. Cada entrada representa uma mensagem.

Para outros cenários de saída, crie e use um ServiceBusClient com outros tipos diretamente de Azure.Messaging.ServiceBus . 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 essa associação, que depende do tempo de execução e da versão da extensão.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

As configurações clientRetryOptions se aplicam apenas a interações com o serviço do Barramento de Serviço. Elas não afetam as novas tentativas de execuções de função. Para saber mais, confira Repetições.

Propriedade Padrão Descrição
mode Exponential A abordagem a ser usada para calcular atrasos de repetição. O modo exponencial padrão repete as tentativas com um atraso baseado em uma estratégia de retirada em que cada tentativa aumenta a duração da espera antes de tentar novamente. O modo Fixed faz novas tentativas em intervalos fixos com cada atraso tendo uma duração consistente.
tryTimeout 00:01:00 A duração máxima da espera por uma operação, por tentativa.
delay 00:00:00.80 O fator de atraso ou de retirada a ser aplicado entre as tentativas de repetição.
maxDelay 00:01:00 O atraso máximo permitido entre as tentativas de repetição
maxRetries 3 O número máximo de tentativas de repetição antes de considerar que a operação associada falhou.
prefetchCount 0 Obtém ou define o número de mensagens que o destinatário da mensagem pode solicitar simultaneamente.
transportType amqpTcp O protocolo e o transporte usados para a comunicação com o Barramento de Serviço. Opções disponíveis: amqpTcp e amqpWebSockets
webProxy n/d O proxy a ser usado para se comunicar com o Barramento de Serviço por soquetes da Web. Um proxy não pode ser usado com o transporte amqpTcp.
autoCompleteMessages true Determina se as mensagens devem ou não ser concluídas automaticamente após a execução bem-sucedida da função.
maxAutoLockRenewalDuration 00:05:00 A duração máxima na qual o bloqueio de mensagem será renovado automaticamente. Essa configuração se aplica somente a funções que recebem apenas uma mensagem por vez.
maxConcurrentCalls 16 O número máximo de chamadas simultâneas para o retorno de chamada que deve ser iniciado por instância dimensionada. Por padrão, o runtime do Functions processa várias mensagens simultaneamente. Essa configuração só é usada quando a propriedade isSessionsEnabled ou o atributo no gatilho é definido como false. Essa configuração se aplica somente a funções que recebem apenas uma mensagem por vez.
maxConcurrentSessions 8 O número máximo de sessões que podem ser manipuladas simultaneamente por instância dimensionada. Essa configuração só é usada quando a propriedade isSessionsEnabled ou o atributo no gatilho é definido como true. Essa configuração se aplica somente a funções que recebem apenas uma mensagem por vez.
maxMessageBatchSize 1000 O número máximo de mensagens que serão passadas para cada chamada de função. Essa configuração se aplica somente a funções que recebem um lote de mensagens.
minMessageBatchSize1 1 O número mínimo de mensagens desejadas em um lote. O mínimo se aplica somente quando a função estiver recebendo várias mensagens e deve ser menor que maxMessageBatchSize.
O tamanho mínimo não é estritamente garantido. Um lote parcial é expedido quando um lote completo não pode ser preparado antes que maxBatchWaitTime tenha decorrido.
maxBatchWaitTime1 00:00:30 O intervalo máximo que o gatilho deve aguardar para preencher um lote antes de invocar a função. O tempo de espera só é considerado quando minMessageBatchSize é maior que 1. Caso contrário, ele é ignorado. Se menos de minMessageBatchSize mensagens estiverem disponíveis antes do tempo de espera passar, a função será invocada com um lote parcial. O tempo de espera mais longo permitido é 50% da duração do bloqueio de mensagem da entidade, o que significa que o máximo permitido é de 2 minutos e 30 segundos. Caso contrário, você poderá obter exceções de bloqueio.

OBSERVAÇÃO: esse intervalo não é uma garantia estrita para o tempo exato no qual a função é invocada. Há uma pequena margem de erro devido à precisão do temporizador.
sessionIdleTimeout n/d A quantidade máxima de tempo de espera para receber uma mensagem na sessão ativa no momento. Decorrido esse tempo, a sessão será fechada e a função tentará processar outra sessão.
enableCrossEntityTransactions false Se deve ou não habilitar transações que abrangem várias entidades em um namespace Barramento de Serviço dados.

1 Usar minMessageBatchSize e maxBatchWaitTime requer a v5.10.0 do pacote Microsoft.Azure.WebJobs.Extensions.ServiceBus ou uma versão posterior.

Próximas etapas