Gatilho do Barramento de Serviço do Azure para o Azure Functions

Artigo
10/18/2023

Use o gatilho do Barramento de Serviço para responder a mensagens de uma fila ou tópico do Barramento de Serviço. A partir da versão 3.1.0 da extensão, você pode acionar em uma fila ou tópico habilitado para sessão.

Para obter informações sobre detalhes de instalação e configuração, consulte a visão geral.

As decisões de dimensionamento do Service Bus para os planos Consumo e Premium são tomadas com base no dimensionamento baseado em metas. Para obter mais informações, consulte Dimensionamento baseado em destino.

Importante

Este artigo usa guias para oferecer suporte a várias versões do modelo de programação Node.js. O modelo v4 está geralmente disponível e foi projetado para ter uma experiência mais flexível e intuitiva para desenvolvedores JavaScript e TypeScript. Para obter mais detalhes sobre como o modelo v4 funciona, consulte o Guia do desenvolvedor do Azure Functions Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

Este artigo suporta ambos os modelos de programação.

Exemplo

Uma função C# pode ser criada usando um dos seguintes modos C#:

Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte total.

Modelo de trabalhador isolado
Modelo em processo

Este código define e inicializa o ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

Este exemplo mostra uma função C# que recebe uma única mensagem de fila do Service Bus e a grava nos logs:

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    var outputMessage = $"Output message created at {DateTime.Now}";
    return outputMessage;
}

Este exemplo mostra uma função C# que recebe várias mensagens da fila do Service Bus em um único lote e grava cada uma nos logs:

[Function(nameof(ServiceBusReceivedMessageBatchFunction))]
public void ServiceBusReceivedMessageBatchFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", IsBatched = true)] ServiceBusReceivedMessage[] messages)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        _logger.LogInformation("Message ID: {id}", message.MessageId);
        _logger.LogInformation("Message Body: {body}", message.Body);
        _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);
    }
}

Este exemplo mostra uma função C# que recebe várias mensagens de fila do Service Bus, grava-a nos logs e liquida a mensagem como concluída:

[Function(nameof(ServiceBusMessageActionsFunction))]
public async Task ServiceBusMessageActionsFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", AutoCompleteMessages = false)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    // Complete the message
    await messageActions.CompleteMessageAsync(message);
}

O exemplo a seguir mostra uma função C# que lê metadados de mensagem e registra uma mensagem de fila do Service Bus:

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
    string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    ILogger log)
{
    log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"DeliveryCount={deliveryCount}");
    log.LogInformation($"MessageId={messageId}");
}

A função Java a seguir usa a @ServiceBusQueueTrigger anotação da biblioteca de tempo de execução de funções Java para descrever a configuração para um gatilho de fila do Service Bus. A função pega a mensagem colocada na fila e a adiciona aos logs.

@FunctionName("sbprocessor")
 public void serviceBusProcess(
    @ServiceBusQueueTrigger(name = "msg",
                             queueName = "myqueuename",
                             connection = "myconnvarname") String message,
   final ExecutionContext context
 ) {
     context.getLogger().info(message);
 }

As funções Java também podem ser acionadas quando uma mensagem é adicionada a um tópico do Service Bus. O exemplo a seguir usa a @ServiceBusTopicTrigger anotação para descrever a configuração do gatilho.

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

Modelo v4
Modelo v3

O exemplo a seguir mostra uma função TypeScript de gatilho do Service Bus. A função lê metadados de mensagem e registra uma mensagem de fila do Service Bus.

import { app, InvocationContext } from '@azure/functions';

export async function serviceBusQueueTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Service bus queue function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
    context.log('MessageId =', context.triggerMetadata.messageId);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: serviceBusQueueTrigger1,
});

Modelo v4
Modelo v3

O exemplo a seguir mostra uma função JavaScript de gatilho do Service Bus. A função lê metadados de mensagem e registra uma mensagem de fila do Service Bus.

const { app } = require('@azure/functions');

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: (message, context) => {
        context.log('Service bus queue function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
        context.log('MessageId =', context.triggerMetadata.messageId);
    },
});

O exemplo a seguir mostra uma ligação de gatilho do Service Bus em um arquivo function.json e uma função JavaScript que usa a associação. A função lê metadados de mensagem e registra uma mensagem de fila do Service Bus.

Aqui estão os dados de ligação no arquivo function.json :

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Aqui está o código de script JavaScript:

module.exports = async function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.bindingData.deliveryCount);
    context.log('MessageId =', context.bindingData.messageId);
};

O exemplo a seguir mostra uma associação de gatilho do Service Bus em um arquivo de function.json e uma função do PowerShell que usa a associação.

Aqui estão os dados de ligação no arquivo function.json :

{
  "bindings": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Esta é a função que é executada quando uma mensagem do Service Bus é enviada.

param([string] $mySbMsg, $TriggerMetadata)

Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"

O exemplo a seguir demonstra como ler uma mensagem de fila do Service Bus por meio de um gatilho. O exemplo depende se você usa o modelo de programação Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusQueueTrigger1")
@app.service_bus_queue_trigger(arg_name="msg", 
                               queue_name="<QUEUE_NAME>", 
                               connection="<CONNECTION_SETTING>")
def test_function(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message: %s',
                 msg.get_body().decode('utf-8'))

Uma associação do Service Bus é definida em function.json onde type é definido como serviceBusTrigger e a fila é definida por queueName.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "inputqueue",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

O código em _init_.py declara um parâmetro como func.ServiceBusMessage, que permite que você leia a mensagem de fila em sua função.

import azure.functions as func

import logging
import json

def main(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message.')

    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'expiration_time': msg.expiration_time,
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': msg.scheduled_enqueue_time,
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
        'metadata' : msg.metadata
    }, default=str)

    logging.info(result)

O exemplo a seguir demonstra como ler um tópico de fila do Service Bus por meio de um gatilho.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusTopicTrigger1")
@app.service_bus_topic_trigger(arg_name="message", 
                               topic_name="TOPIC_NAME", 
                               connection="CONNECTION_SETTING", 
                               subscription_name="SUBSCRIPTION_NAME")
def test_function(message: func.ServiceBusMessage):
    message_body = message.get_body().decode("utf-8")
    logging.info("Python ServiceBus topic trigger processed message.")
    logging.info("Message Body: " + message_body)

Uma associação do Service Bus é definida em function.json onde type é definido como serviceBusTrigger e o tópico é definido por topicName.

{
  "scriptFile": "__init__.py",
  "bindings": [
   {
     "type": "serviceBusTrigger",
     "direction": "in",
     "name": "msg",
     "topicName": "inputtopic",
     "connection": "AzureServiceBusConnectionString"
   }
  ]
}

O código em _init_.py declara um parâmetro como func.ServiceBusMessage, que permite que você leia o tópico em sua função.

import json

import azure.functions as azf


def main(msg: azf.ServiceBusMessage) -> str:
    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'delivery_count': msg.delivery_count,
        'expiration_time': (msg.expiration_time.isoformat() if
                            msg.expiration_time else None),
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': (msg.scheduled_enqueue_time.isoformat() if
                                   msg.scheduled_enqueue_time else None),
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
    })

    logging.info(result)

Atributos

As bibliotecas C# de processo de trabalho em processo e isoladas usam o atributo ServiceBusTriggerAttribute para definir o gatilho de função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Modelo de trabalhador isolado
Modelo em processo

A tabela a seguir explica as propriedades que você pode definir usando esse atributo trigger:

Property	Description
Nome da fila	Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
Nome do tópico	Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
Nome da Subscrição	Nome da subscrição a monitorizar. Defina somente se estiver monitorando um tópico, não para uma fila.
Ligação	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.
IsBatched	As mensagens são entregues em lotes. Requer uma matriz ou tipo de coleção.
IsSessionsEnabled	`true` se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. `false` caso contrário, que é o valor padrão.
AutoCompleteMessages	`true` se o gatilho deve completar automaticamente a mensagem após uma chamada bem-sucedida. `false` se não deveria, como quando você está lidando com a liquidação de mensagens no código. Se não for definido explicitamente, o comportamento será baseado `autoCompleteMessages` na configuração em `host.json`.

A tabela a seguir explica as propriedades que você pode definir usando esse atributo trigger:

Property	Description
Nome da fila	Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
Nome do tópico	Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
Nome da Subscrição	Nome da subscrição a monitorizar. Defina somente se estiver monitorando um tópico, não para uma fila.
Ligação	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.
Acesso	Direitos de acesso para a cadeia de conexão. Os valores disponíveis são `manage` e `listen`. O padrão é `manage`, que indica que o `connection` tem a permissão Gerenciar . Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar , defina `accessRights` como "ouvir". Caso contrário, o tempo de execução do Functions pode falhar ao tentar fazer operações que exigem direitos de gerenciamento. No Azure Functions versão 2.x e superior, essa propriedade não está disponível porque a versão mais recente do SDK do Service Bus não oferece suporte a operações de gerenciamento.
IsBatched	As mensagens são entregues em lotes. Requer uma matriz ou tipo de coleção.
IsSessionsEnabled	`true` se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. `false` caso contrário, que é o valor padrão.
Preenchimento Automático	`true` Se o gatilho deve chamar automaticamente complete após o processamento ou se o código da função chamará manualmente complete. Se definido como `true`, o gatilho conclui a mensagem automaticamente se a execução da função for concluída com êxito e abandona a mensagem caso contrário. Quando definido como `false`, você é responsável por chamar os métodos ServiceBusReceiver para concluir, abandonar ou fazer deadletter da mensagem, sessão ou lote. Quando uma exceção é lançada (e nenhum dos `ServiceBusReceiver` métodos é chamado), o bloqueio permanece. Quando o bloqueio expirar, a mensagem é novamente enfileirada com o incrementado `DeliveryCount` e o bloqueio é renovado automaticamente.

Quando estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values coleção.

Decoradores

Aplica-se apenas ao modelo de programação Python v2.

Para funções Python v2 definidas usando um decorador, as seguintes propriedades no service_bus_queue_trigger:

Property	Description
`arg_name`	O nome da variável que representa a fila ou a mensagem de tópico no código da função.
`queue_name`	Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
`connection`	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.

Para funções Python definidas usando function.json, consulte a seção Configuração .

Anotações

A ServiceBusQueueTrigger anotação permite criar uma função que é executada quando uma mensagem de fila do Service Bus é criada. As opções de configuração disponíveis incluem as seguintes propriedades:

Property	Descrição
Designação	O nome da variável que representa a fila ou a mensagem de tópico no código da função.
queueName	Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
nome_tópico	Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
nome_do-assinante	Nome da subscrição a monitorizar. Defina somente se estiver monitorando um tópico, não para uma fila.
conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.

A ServiceBusTopicTrigger anotação permite que você designe um tópico e uma assinatura para direcionar quais dados acionam a função.

Quando estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values coleção.

Consulte o exemplo de gatilho para obter mais detalhes.

Configuração

Aplica-se apenas ao modelo de programação Python v1.

Modelo v4
Modelo v3

A tabela a seguir explica as propriedades que você pode definir no options objeto passado para os app.serviceBusQueue() métodos or app.serviceBusTopic() .

Property	Description
queueName	Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
nome_tópico	Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
nome_do-assinante	Nome da subscrição a monitorizar. Defina somente se estiver monitorando um tópico, não para uma fila.
conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.
Direitos de acesso	Direitos de acesso para a cadeia de conexão. Os valores disponíveis são `manage` e `listen`. O padrão é `manage`, que indica que o `connection` tem a permissão Gerenciar . Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar , defina `accessRights` como "ouvir". Caso contrário, o tempo de execução do Functions pode falhar ao tentar fazer operações que exigem direitos de gerenciamento. No Azure Functions versão 2.x e superior, essa propriedade não está disponível porque a versão mais recente do SDK do Service Bus não oferece suporte a operações de gerenciamento.
isSessionsEnabled	`true` se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. `false` caso contrário, que é o valor padrão.
Preenchimento automático	Deve ser `true` para funções não-C#, o que significa que o gatilho deve chamar automaticamente complete após o processamento ou o código da função chama manualmente complete. Quando definido como `true`, o gatilho conclui a mensagem automaticamente se a execução da função for concluída com êxito e abandona a mensagem caso contrário. Exceções na função resultam nas chamadas `abandonAsync` de tempo de execução em segundo plano. Se nenhuma exceção ocorrer, então `completeAsync` é chamado em segundo plano. Esta propriedade está disponível apenas no Azure Functions 2.x e superior.

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .

Property	Descrição
type	Deve ser definido como `serviceBusTrigger`. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direção	Deve ser definido como "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
Designação	O nome da variável que representa a fila ou a mensagem de tópico no código da função.
queueName	Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
nome_tópico	Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
nome_do-assinante	Nome da subscrição a monitorizar. Defina somente se estiver monitorando um tópico, não para uma fila.
conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.
Direitos de acesso	Direitos de acesso para a cadeia de conexão. Os valores disponíveis são `manage` e `listen`. O padrão é `manage`, que indica que o `connection` tem a permissão Gerenciar . Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar , defina `accessRights` como "ouvir". Caso contrário, o tempo de execução do Functions pode falhar ao tentar fazer operações que exigem direitos de gerenciamento. No Azure Functions versão 2.x e superior, essa propriedade não está disponível porque a versão mais recente do SDK do Service Bus não oferece suporte a operações de gerenciamento.
isSessionsEnabled	`true` se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. `false` caso contrário, que é o valor padrão.
Preenchimento automático	Deve ser `true` para funções não-C#, o que significa que o gatilho deve chamar automaticamente complete após o processamento ou o código da função chama manualmente complete. Quando definido como `true`, o gatilho conclui a mensagem automaticamente se a execução da função for concluída com êxito e abandona a mensagem caso contrário. Exceções na função resultam nas chamadas `abandonAsync` de tempo de execução em segundo plano. Se nenhuma exceção ocorrer, então `completeAsync` é chamado em segundo plano. Esta propriedade está disponível apenas no Azure Functions 2.x e superior.

Quando estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values coleção.

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .

function.json propriedade	Description
type	Deve ser definido como `serviceBusTrigger`. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direção	Deve ser definido como "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
Designação	O nome da variável que representa a fila ou a mensagem de tópico no código da função.
queueName	Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
nome_tópico	Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
nome_do-assinante	Nome da subscrição a monitorizar. Defina somente se estiver monitorando um tópico, não para uma fila.
conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.
Direitos de acesso	Direitos de acesso para a cadeia de conexão. Os valores disponíveis são `manage` e `listen`. O padrão é `manage`, que indica que o `connection` tem a permissão Gerenciar . Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar , defina `accessRights` como "ouvir". Caso contrário, o tempo de execução do Functions pode falhar ao tentar fazer operações que exigem direitos de gerenciamento. No Azure Functions versão 2.x e superior, essa propriedade não está disponível porque a versão mais recente do SDK do Service Bus não oferece suporte a operações de gerenciamento.
isSessionsEnabled	`true` se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. `false` caso contrário, que é o valor padrão.
Preenchimento automático	Deve ser `true` para funções não-C#, o que significa que o gatilho deve chamar automaticamente complete após o processamento ou o código da função chama manualmente complete. Quando definido como `true`, o gatilho conclui a mensagem automaticamente se a execução da função for concluída com êxito e abandona a mensagem caso contrário. Exceções na função resultam nas chamadas `abandonAsync` de tempo de execução em segundo plano. Se nenhuma exceção ocorrer, então `completeAsync` é chamado em segundo plano. Esta propriedade está disponível apenas no Azure Functions 2.x e superior.

Quando estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values coleção.

Consulte a seção Exemplo para obter exemplos completos.

Utilização

Os seguintes tipos de parâmetros são suportados por todas as modalidades C# e versões de extensão:

Tipo	Description
System.String	Use quando a mensagem for texto simples.
byte[]	Use para mensagens de dados binários.
Objeto	Quando uma mensagem contém JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR antigo conhecido.

Os tipos de parâmetros específicos de mensagens contêm metadados de mensagem adicionais. Os tipos específicos suportados pelo gatilho do Service Bus dependem da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Use o tipo ServiceBusReceivedMessage para receber metadados de mensagens de Filas e Assinaturas do Service Bus. Para saber mais, consulte Mensagens, cargas úteis e serialização.

Em bibliotecas de classes C#, o construtor do atributo usa o nome da fila ou o tópico e a assinatura.

Você também pode usar o ServiceBusAccountAttribute para especificar a conta do Service Bus a ser usada. O construtor leva o nome de uma configuração de aplicativo que contém uma cadeia de conexão do Service Bus. O atributo pode ser aplicado no nível de parâmetro, método ou classe. O exemplo a seguir mostra o nível da classe e o nível do método:

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

A conta do Service Bus a ser usada é determinada na seguinte ordem:

A ServiceBusTrigger propriedade do Connection atributo.
O ServiceBusAccount atributo aplicado ao mesmo parâmetro que o ServiceBusTrigger atributo.
O ServiceBusAccount atributo aplicado à função.
O ServiceBusAccount atributo aplicado à classe.
A AzureWebJobsServiceBus configuração do aplicativo.

Use o tipo de mensagem para receber mensagens com metadados. Para saber mais, consulte Mensagens, cargas úteis e serialização.

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, consulte o anúncio de aposentadoria de suporte.

Em bibliotecas de classes C#, o construtor do atributo usa o nome da fila ou o tópico e a assinatura.

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

A conta do Service Bus a ser usada é determinada na seguinte ordem:

A ServiceBusTrigger propriedade do Connection atributo.
O ServiceBusAccount atributo aplicado ao mesmo parâmetro que o ServiceBusTrigger atributo.
O ServiceBusAccount atributo aplicado à função.
O ServiceBusAccount atributo aplicado à classe.
A AzureWebJobsServiceBus configuração do aplicativo.

Os seguintes tipos de parâmetros estão disponíveis para a mensagem de fila ou tópico:

BrokeredMessage - Fornece a mensagem desserializada com o método BrokeredMessage.GetBody<T>().
MessageReceiver - Usado para receber e confirmar mensagens do contêiner de mensagens, que é necessário quando autoComplete definido como false.

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, consulte o anúncio de aposentadoria de suporte.

Em bibliotecas de classes C#, o construtor do atributo usa o nome da fila ou o tópico e a assinatura. No Azure Functions versão 1.x, você também pode especificar os direitos de acesso da conexão. Se você não especificar direitos de acesso, o padrão será Manage.

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

A conta do Service Bus a ser usada é determinada na seguinte ordem:

A ServiceBusTrigger propriedade do Connection atributo.
O ServiceBusAccount atributo aplicado ao mesmo parâmetro que o ServiceBusTrigger atributo.
O ServiceBusAccount atributo aplicado à função.
O ServiceBusAccount atributo aplicado à classe.
A AzureWebJobsServiceBus configuração do aplicativo.

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.
ServiceBusReceivedMessage¹	O objeto message. Ao vincular ao `ServiceBusReceivedMessage`, você também pode, opcionalmente, incluir um parâmetro do tipo ServiceBusMessageActions^1,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 ServiceBusMessageActions^1,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.

Quando a Connection propriedade não está definida, Functions procura uma configuração de aplicativo chamada AzureWebJobsServiceBus, que é o nome padrão para a cadeia de conexão do Service Bus. Você também pode definir a Connection propriedade para especificar o nome de uma configuração de aplicativo que contém a cadeia de conexão do Service Bus a ser usada.

A mensagem recebida do Service Bus está disponível por meio de um ServiceBusQueueMessage ou ServiceBusTopicMessage parâmetro.

Modelo v4
Modelo v3

Acesse a mensagem de fila ou tópico como o primeiro argumento para sua função. A mensagem do Service Bus é passada para a função como uma cadeia de caracteres ou objeto JSON.

A instância do Service Bus está disponível por meio do parâmetro configurado na propriedade name do arquivo function.json .

A mensagem de fila está disponível para a função através de um parâmetro digitado como func.ServiceBusMessage. A mensagem do Service Bus é passada para a função como uma cadeia de caracteres ou objeto JSON.

Para obter um exemplo completo, consulte a seção de exemplos.

Ligações

A connection propriedade é uma referência à configuração do ambiente que especifica como o aplicativo deve se conectar ao Service Bus. Pode especificar:

O nome de uma configuração de aplicativo que contém uma cadeia de conexão
O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade.

Se o valor configurado for uma correspondência exata para uma única configuração e uma correspondência de prefixo para outras configurações, a correspondência exata será usada.

Connection string

Para obter uma cadeia de conexão, siga as etapas mostradas em Obter as credenciais de gerenciamento. A cadeia de conexão deve ser para um namespace do Service Bus, não limitado a uma fila ou tópico específico.

Essa cadeia de conexão deve ser armazenada em uma configuração de aplicativo com um nome correspondente ao valor especificado pela connection propriedade da configuração de ligação.

Se o nome da configuração do aplicativo começar com "AzureWebJobs", você poderá especificar apenas o restante do nome. Por exemplo, se você definir connection como "MyServiceBus", o tempo de execução do Functions procurará uma configuração de aplicativo chamada "AzureWebJobsMyServiceBus". Se você deixar connection vazio, o tempo de execução do Functions usará a cadeia de conexão padrão do Service Bus na configuração do aplicativo chamada "AzureWebJobsServiceBus".

Conexões baseadas em identidade

Se você estiver usando a versão 5.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para fazer isso, você definiria as configurações sob um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e vinculação.

Neste modo, a extensão requer as seguintes propriedades:

Property	Modelo de variável de ambiente	Description	Valor de exemplo
Namespace totalmente qualificado	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	O namespace do Service Bus totalmente qualificado.	<service_bus_namespace.servicebus.windows.net>

Propriedades adicionais podem ser definidas para personalizar a conexão. Consulte Propriedades comuns para conexões baseadas em identidade.

Nota

Ao usar a Configuração do Aplicativo do Azure ou o Cofre da Chave para fornecer configurações para conexões de Identidade Gerenciada, os nomes de configuração devem usar um separador de chave válido, como : ou / no lugar do para garantir que os __ nomes sejam resolvidos corretamente.

Por exemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Quando hospedadas no serviço Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída ao sistema é usada por padrão, embora uma identidade atribuída ao usuário possa ser especificada com as credential propriedades e clientID . Observe que não há suporte para a configuração de uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, sua identidade de desenvolvedor é usada, embora isso possa ser personalizado. Consulte Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão à identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços do Azure, isso significa que você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha escopo apenas sobre os recursos que precisam ser lidos.

Você precisará criar uma atribuição de função que forneça acesso aos seus tópicos e filas em tempo de execução. Funções de gerenciamento como Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Service Bus em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação	Exemplo de funções internas
Gatilho¹	Recetor de Dados do Barramento de Serviço do Azure, Proprietário de Dados do Barramento de Serviço do Azure
Vinculação de saída	Remetente de dados do Barramento de Serviço do Azure

1 Para acionar a partir de tópicos do Service Bus, a atribuição de função precisa ter escopo efetivo sobre o recurso de assinatura do Service Bus. Se apenas estiver incluído o tópico, ocorrerá um erro. Alguns clientes, como o portal do Azure, não expõem o recurso de subscrição do Service Bus como um âmbito para atribuição de função. Nesses casos, a CLI do Azure pode ser usada. Para saber mais, consulte Funções internas do Azure para o Barramento de Serviço do Azure.

Mensagens venenosas

O tratamento de mensagens suspeitas não pode ser controlado ou configurado no Azure Functions. O Service Bus lida com mensagens suspeitas em si.

Comportamento PeekLock

O tempo de execução do Functions recebe uma mensagem no modo PeekLock.

Por padrão, o tempo de execução chama Complete a mensagem se a função for concluída com êxito ou chama Abandon se a função falhar. Você pode desativar o preenchimento automático através da autoCompleteMessages propriedade em host.json.

Por padrão, o tempo de execução chama Complete a mensagem se a função for concluída com êxito ou chama Abandon se a função falhar. Você pode desabilitar a conclusão automática através da propriedade in host.json ou através de autoCompleteMessages uma propriedade no atributo trigger. Você deve desativar o preenchimento automático se o código da função lidar com a liquidação de mensagens.

Se a função for executada por mais tempo do que o PeekLock tempo limite, o bloqueio será renovado automaticamente enquanto a função estiver em execução. O maxAutoRenewDuration é configurável no host.json, que mapeia para ServiceBusProcessor.MaxAutoLockRenewalDuration. O valor padrão dessa configuração é 5 minutos.

Metadados da mensagem

Os tipos específicos de mensagens permitem recuperar facilmente metadados como propriedades do objeto. Essas propriedades dependem da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Essas propriedades são membros da classe ServiceBusReceivedMessage .

Propriedade	Type	Description
`ApplicationProperties`	`ApplicationProperties`	Propriedades definidas pelo remetente.
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo emissor e recetor para lógica específica do aplicativo.
`CorrelationId`	`string`	O ID de correlação.
`DeliveryCount`	`Int32`	O número de entregas.
`EnqueuedTime`	`DateTime`	A hora enfileirada em UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	A hora enfileirada agendada em UTC.
`ExpiresAt`	`DateTime`	O tempo de expiração em UTC.
`MessageId`	`string`	Um valor definido pelo usuário que o Service Bus pode usar para identificar mensagens duplicadas, se habilitado.
`ReplyTo`	`string`	A resposta ao endereço da fila.
`Subject`	`string`	O rótulo específico do aplicativo que pode ser usado no lugar da `Label` propriedade de metadados.
`To`	`string`	O endereço de envio para.

Essas propriedades são membros da classe Message .

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, consulte o anúncio de aposentadoria de suporte.

Propriedade	Type	Description
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo emissor e recetor para lógica específica do aplicativo.
`CorrelationId`	`string`	O ID de correlação.
`DeliveryCount`	`Int32`	O número de entregas.
`ScheduledEnqueueTimeUtc`	`DateTime`	A hora enfileirada agendada em UTC.
`ExpiresAtUtc`	`DateTime`	O tempo de expiração em UTC.
`Label`	`string`	O rótulo específico do aplicativo.
`MessageId`	`string`	Um valor definido pelo usuário que o Service Bus pode usar para identificar mensagens duplicadas, se habilitado.
`ReplyTo`	`string`	A resposta ao endereço da fila.
`To`	`string`	O endereço de envio para.
`UserProperties`	`IDictionary<string, object>`	Propriedades definidas pelo remetente.

Essas propriedades são membros das classes BrokeredMessage e MessageReceiver .

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, consulte o anúncio de aposentadoria de suporte.

Propriedade	Type	Description
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo emissor e recetor para lógica específica do aplicativo.
`CorrelationId`	`string`	O ID de correlação.
`DeadLetterSource`	`string`	A fonte letra morta.
`DeliveryCount`	`Int32`	O número de entregas.
`EnqueuedTimeUtc`	`DateTime`	A hora enfileirada em UTC.
`ExpiresAtUtc`	`DateTime`	O tempo de expiração em UTC.
`Label`	`string`	O rótulo específico do aplicativo.
`MessageId`	`string`	Um valor definido pelo usuário que o Service Bus pode usar para identificar mensagens duplicadas, se habilitado.
`MessageReceiver`	`MessageReceiver`	Recetor de mensagens do Service Bus. Pode ser usado para abandonar, completar ou fazer deadletter na mensagem.
`MessageSession`	`MessageSession`	Um recetor de mensagem especificamente para filas e tópicos habilitados para sessão.
`ReplyTo`	`string`	A resposta ao endereço da fila.
`SequenceNumber`	`long`	O número exclusivo atribuído a uma mensagem pelo Service Bus.
`To`	`string`	O endereço de envio para.
`UserProperties`	`IDictionary<string, object>`	Propriedades definidas pelo remetente.

Essas propriedades são membros da classe ServiceBusReceivedMessage .

Propriedade	Type	Description
`ApplicationProperties`	`ApplicationProperties`	Propriedades definidas pelo remetente.
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo emissor e recetor para lógica específica do aplicativo.
`CorrelationId`	`string`	O ID de correlação.
`DeliveryCount`	`Int32`	O número de entregas.
`EnqueuedTime`	`DateTime`	A hora enfileirada em UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	A hora enfileirada agendada em UTC.
`ExpiresAt`	`DateTime`	O tempo de expiração em UTC.
`MessageId`	`string`	Um valor definido pelo usuário que o Service Bus pode usar para identificar mensagens duplicadas, se habilitado.
`ReplyTo`	`string`	A resposta ao endereço da fila.
`Subject`	`string`	O rótulo específico do aplicativo que pode ser usado no lugar da `Label` propriedade de metadados.
`To`	`string`	O endereço de envio para.

Próximos passos

Enviar mensagens do Barramento de Serviço do Azure a partir do Azure Functions (Ligação de saída)

Partilhar via

Gatilho do Barramento de Serviço do Azure para o Azure Functions

Exemplo

Atributos

Decoradores

Anotações

Configuração

Utilização

Ligações

Connection string

Conexões baseadas em identidade

Conceder permissão à identidade

Mensagens venenosas

Comportamento PeekLock

Metadados da mensagem

Próximos passos

Comentários

Recursos adicionais