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.
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 ServiceBusMessageActions
o , 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.