Compartilhar via

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

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

Para poder usar essa extensão de associação em seu aplicativo, verifique se o arquivo host.json na raiz do projeto contém esta extensionBundle referência:

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

Neste exemplo, o version valor instrui o host do [4.0.0, 5.0.0) Functions a usar uma versão de pacote pelo menos 4.0.0 menor que 5.0.0, que inclui todas as versões potenciais do 4.x. Essa notação mantém efetivamente seu aplicativo na versão secundária mais recente disponível do pacote de extensão v4.x.

Quando possível, você deve usar a versão principal do pacote de extensão mais recente e permitir que o runtime mantenha automaticamente a versão secundária mais recente. Você pode exibir o conteúdo do pacote mais recente na página de lançamento dos pacotes de extensão. Para obter mais informações, consulte os pacotes de extensão do Azure Functions.

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:

Tipo 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:

Tipo 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:

Tipo 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:

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

Tipos de associação do SDK

Os tipos de SDK para o Barramento de Serviço do Azure estão em versão prévia. Siga as Associações do SDK do Python para o exemplo do Barramento de Serviço para começar a usar os Tipos de SDK para Barramento de Serviço no Python.

Importante

O uso de associações de tipo SDK requer o modelo de programação python v2.

Ligação Tipos de parâmetro Exemplos
Gatilho do ServiceBus ServiceBusReceivedMessage ServiceBusReceivedMessage

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
modo 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.
atraso 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 só se aplica a funções que recebem uma única mensagem por vez e não se aplicam a funções que recebem um lote de mensagens. Para lotes, a duração máxima é definida no Barramento de Serviço no nível da fila ou da assinatura.
maxConcurrentCalls 16 Por padrão, o runtime do Functions processa várias mensagens simultaneamente. Essa configuração limita o número máximo de chamadas simultâneas para o retorno de chamada que pode ser iniciado por instância dimensionada. Quando seu plano de hospedagem tem mais de um núcleo por instância, o número máximo de chamadas é efetivamente multiplicado pelo número de núcleos. Por exemplo, em um plano executado em hardware com dois núcleos, a configuração padrão significa 16 que o número máximo de chamadas simultâneas por instância é realmente 32 (ou 2 * 16). Essa configuração só é usada quando a propriedade isSessionsEnabled ou o atributo no gatilho é definido como false. Essa configuração só se aplica a funções que recebem uma única mensagem por vez, em vez de em um lote.
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

  • Last updated on