Partilhar via

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

Ação Type
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 Description
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 Description
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 Description
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 Description
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.

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.

Property Predefinição Description
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