Partilhar via

Associações do Barramento de Serviço do Azure 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 Service Bus permite criar funções que reagem e enviam mensagens de fila ou tópico.

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

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

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

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.

Instalar pacote

A associação do Service Bus faz parte de um pacote de extensão, que é especificado no 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 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.

Gatilho do Service Bus

Quando você deseja que a função processe uma única mensagem, o gatilho do Service Bus pode se vincular aos seguintes tipos:

Tipo Descrição
string A mensagem como uma cadeia de caracteres. Use quando a mensagem for 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 (POCO) simples.
ServiceBusReceivedMessage1 O objeto message.

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

Quando você deseja que a função processe um lote de mensagens, o gatilho do Service Bus pode se vincular aos seguintes tipos:

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

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

1 Para usar esses tipos, você precisa fazer referência a Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 ou posterior e às dependências comuns para associações de tipo SDK.

2 Ao usar ServiceBusMessageActions, defina a AutoCompleteMessages propriedade do atributo trigger como false. Isso impede que o tempo de execução tente concluir mensagens após uma chamada de função bem-sucedida.

Vinculação de saída do Service Bus

Quando você deseja que a função escreva uma única mensagem, a associação de saída do Service Bus pode se vincular aos seguintes tipos:

Tipo Descrição
string A 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 a mensagem. As funções tentam serializar um tipo de objeto CLR (POCO) antigo em dados JSON.

Quando você deseja que a função escreva várias mensagens, a associação de saída do Service Bus pode se vincular aos seguintes tipos:

Tipo Descrição
T[] onde 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 do Azure.Messaging.ServiceBus 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.

Tipos de vinculação SDK

Os Tipos de SDK para o Barramento de Serviço do Azure estão em Pré-visualização. Siga o exemplo Python SDK Bindings for Service Bus para começar a usar os tipos de SDK para Service Bus em Python.

Importante

Usar associações de tipo SDK requer o modelo de programação Python v2.

Vinculativo Tipos de parâmetros Exemplos
Gatilho do ServiceBus ServiceBusReceivedMessage ServiceBusReceivedMessage

host.json configurações

Esta seção descreve as definições de configuração disponíveis para essa ligação, que dependem 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 clientRetryOptions configurações só se aplicam a interações com o serviço Service Bus. Eles não afetam as repetições de execuções de funções. Para obter mais informações, consulte Tentativas.

Propriedade Predefinição Descrição
modo Exponential A abordagem a ser usada para calcular atrasos de repetição. O modo exponencial padrão tenta novamente com um atraso baseado em uma estratégia de back-off, onde cada tentativa aumenta a duração da espera antes de tentar novamente. O Fixed modo tenta novamente em intervalos fixos, com cada atraso tendo uma duração consistente.
tryTimeout 00:01:00 A duração máxima para aguardar uma operação por tentativa.
atraso 00:00:00.80 O fator de atraso ou recuo a ser aplicado entre as tentativas de repetição.
maxAtraso 00:01:00 O atraso máximo a permitir entre tentativas de repetição
maxTentativas 3 O número máximo de tentativas de repetição antes de considerar que a operação associada falhou.
pré-fetchCount 0 Obtém ou define o número de mensagens que o recetor da mensagem pode solicitar simultaneamente.
Tipo de transporte amqpTcp O protocolo e o transporte usados para comunicação com o Service Bus. Opções disponíveis: amqpTcp, amqpWebSockets
Proxy web n/d O proxy a ser usado para comunicação com o Service Bus por meio de soquetes da Web. Um proxy não pode ser usado com o amqpTcp transporte.
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 dentro da qual o bloqueio de mensagem será renovado automaticamente. Esta definição aplica-se apenas a funções que recebem uma única mensagem de cada 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 tempo de execução do Functions processa várias mensagens simultaneamente. Essa configuração é usada somente quando a isSessionsEnabled propriedade ou atributo no gatilho é definido como false. Esta definição aplica-se apenas a funções que recebem uma única mensagem de cada vez.
maxConcurrentSessions 8 O número máximo de sessões que podem ser tratadas simultaneamente por instância dimensionada. Essa configuração é usada somente quando a isSessionsEnabled propriedade ou atributo no gatilho é definido como true. Esta definição aplica-se apenas a funções que recebem uma única mensagem de cada vez.
maxMessageBatchSize 1000 O número máximo de mensagens que serão passadas para cada chamada de função. Essa configuração só se aplica 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 aplica-se apenas quando a função está a receber várias mensagens e deve ser inferior a maxMessageBatchSize.
O tamanho mínimo não é estritamente garantido. Um lote parcial é enviado quando um lote completo não pode ser preparado antes de ter decorrido maxBatchWaitTime .
maxBatchWaitTime1 00:00:30 O intervalo máximo que o gatilho deve esperar para preencher um lote antes de invocar a função. O tempo de espera só é considerado quando minMessageBatchSize é maior que 1 e é ignorado caso contrário. Se menos do que as mensagens estavam disponíveis antes do minMessageBatchSize tempo de espera passar, a função é invocada com um lote parcial. O maior tempo de espera permitido é de 50% da duração do bloqueio da mensagem da entidade, o que significa que o máximo permitido é de 2 minutos e 30 segundos. Caso contrário, você pode obter exceções de bloqueio.

NOTA: Este intervalo não é uma garantia estrita para o momento exato em que a função é invocada. Existe uma pequena margem de erro devido à precisão do temporizador.
sessionIdleTimeout n/d A quantidade máxima de tempo para aguardar o recebimento de uma mensagem para a sessão ativa no momento. Após este tempo, a sessão será encerrada e a função tentará processar outra sessão.
enableCrossEntityTransactions false Habilitar ou não transações que abrangem várias entidades em um namespace do Service Bus.

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

Próximos passos