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

Artigo
10/24/2023

Use o gatilho do Barramento de Serviço para responder às 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 disparar em uma fila ou tópico habilitado para sessão.

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

As decisões de dimensionamento do Barramento de Serviços para os planos Consumo e Premium são feitas com base na escala baseada em metas. Para obter mais informações, confira Colocação em escala baseada em destino.

Importante

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

O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a ambos os modelos de programação.

Exemplo

A função C# pode ser criada por meio de um dos seguintes modos C#:

Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework. As extensões para funções do processo de trabalho isoladas usam namespaces Microsoft.Azure.Functions.Worker.Extensions.*.
Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions. Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. As extensões para funções dentro do processo usam namespaces Microsoft.Azure.WebJobs.Extensions.*.

Importante

O suporte terminará para o modelo em processo em 10 de novembro de 2026. É altamente recomendável migrar seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

Modelo de trabalho isolado
Modelo em processo

Esse 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 Barramento de Serviço 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 de fila do Barramento de Serviço 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 ffunção C# que recebe várias mensagens de fila do Barramento de Serviço, grava-a nos logs e resolve 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);
}

A exemplo a seguir mostra uma função C# que lê metadados de mensagem e registra uma mensagem de fila do Barramento de Serviço:

[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 @ServiceBusQueueTriggeranotação da biblioteca de tempo de execução@ServiceBusQueueTrigger para descrever a configuração de um acionador de fila do Barramento de Serviço. A função captura 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 disparadas quando uma mensagem é adicionada a um tópico do Barramento de Serviço. O exemplo a seguir usa @ServiceBusTopicTriggeranotação para descrever a configuração.

@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 Barramento de Serviço. A função lê metadados de mensagem e registra uma mensagem de fila do Barramento de Serviço do Microsoft Azure.

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 Barramento de Serviço. A função lê metadados de mensagem e registra uma mensagem de fila do Barramento de Serviço do Microsoft Azure.

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 associação de gatilho de Barramento de Serviço 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 Barramento de Serviço do Microsoft Azure.

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

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

Este é o código do script do 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 de Barramento de Serviço em um arquivo function.json e uma função PowerShell que usa a associação.

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

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

Esta é a função que é executado quando uma mensagem do Barramento de Serviço é enviada.

param([string] $mySbMsg, $TriggerMetadata)

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

O exemplo a seguir demonstra como ler uma mensagem da fila do Barramento de Serviço por meio de um gatilho. O exemplo depende se você utiliza o modelo de programação do 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 Barramento de Serviço do Azure é definida no function.json , em que tipo está definido como serviceBusTrigger e a fila está definida como queueName.

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

O código no arquivo _init_.py declara um parâmetro como func.ServiceBusMessage, que permite que você leia a mensagem da 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 da fila do Barramento de Serviço através 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 Barramento de Serviço do Azure é definida no function.json , em que tipo está definido como serviceBusTrigger e o tópico está definido como 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, o que permite que você leia o tópico na 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# em processo e de processo de trabalho isolado usam o atributo ServiceBusTriggerAttribute para definir o gatilho da função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia do script C# .

Modelo de trabalho isolado
Modelo em processo

A tabela a seguir explica as propriedades que você pode definir usando este atributo de gatilho:

Propriedade	Descrição
QueueName	Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
TopicName	Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
SubscriptionName	Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
Conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.
IsBatched	As mensagens são entregues em lotes. Requer um tipo de matriz ou coleção.
isSessionsEnabled	`true` se estiver se conectando a `true` assinatura com conhecimento de sessão. `false` caso contrário, que é o valor padrão.
Mensagens de preenchimento automático	`true` se o gatilho deve concluir automaticamente a mensagem após uma invocação 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 na `autoCompleteMessages` configuração no `host.json`.

A tabela a seguir explica as propriedades que você pode definir usando este atributo de gatilho:

Propriedade	Descrição
QueueName	Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
TopicName	Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
SubscriptionName	Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
Conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.
Acesso	Direitos de acesso para a cadeia de caracteres 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 `manage`. Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar, defina `accessRights` como "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e posteriores, essa propriedade não está disponível porque a versão mais recente do SDK de Barramento de Serviço não oferece suporte para operações de gerenciamento.
IsBatched	As mensagens são entregues em lotes. Requer um tipo de matriz ou coleção.
isSessionsEnabled	`true` se estiver se conectando a `true` assinatura com conhecimento de sessão. `false` caso contrário, que é o valor padrão.
Preenchimento automático	`true` Se o gatilho deve chamar concluído automaticamente após o processamento ou se o código da função chamará como concluído manualmente. Se definido como `true`, o gatilho concluirá a mensagem automaticamente se a execução da função for concluída com êxito e abandonará a mensagem se ela falhar. Quando definido como `false`, você é responsável por chamar métodos ServiceBusReceiver para concluir, abandonar ou colocar a mensagem, a sessão ou o lote na fila de mensagens mortas. Se uma exceção for lançada (e nenhum dos métodos `ServiceBusReceiver` for chamado), o bloqueio permanecerá. Assim que o bloqueio expirar, a mensagem será colocada novamente na fila com o `DeliveryCount` incrementado e o bloqueio será renovado automaticamente.

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

Decoradores

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

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

Propriedade	DESCRIÇÃO
`arg_name`	O nome da variável que representa a fila ou mensagem de tópico no código de função.
`queue_name`	Nome da fila a ser monitorada. Defina somente se for monitorar 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 Barramento de Serviço. Confira a opção Conexões.

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

Anotações

A anotação ServiceBusQueueTrigger permite que você crie uma função que é executada quando uma mensagem da fila do Barramento de Serviço é criada. As opções de configuração disponíveis incluem estas propriedades:

Propriedade	Descrição
name	O nome da variável que representa a fila ou mensagem de tópico no código de função.
queueName	Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName	Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
subscriptionName	Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
connection	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.

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

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

Confira o exemplo de gatilho para obter mais detalhes.

Configuração

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

Modelo v4
Modelo v3

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

Propriedade	Descrição
queueName	Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName	Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
subscriptionName	Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
connection	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.
accessRights	Direitos de acesso para a cadeia de caracteres 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 `manage`. Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar, defina `accessRights` como "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e posteriores, essa propriedade não está disponível porque a versão mais recente do SDK de Barramento de Serviço não oferece suporte para operações de gerenciamento.
isSessionsEnabled	`true` se estiver se conectando a `true` assinatura com conhecimento de sessão. `false` caso contrário, que é o valor padrão.
autoComplete	Deve ser `true` para funções não C#, o que significa que o gatilho deve chamar concluído automaticamente após o processamento, ou o código de função chama como concluído manualmente. Se definido como `true`, o gatilho concluirá a mensagem automaticamente, se a execução da função for concluída com êxito, e abandonará a mensagem se ela falhar. Exceções na função resultam nas chamadas de runtime `abandonAsync` em segundo plano. Se nenhuma exceção ocorrer, `completeAsync` será chamado em segundo plano. Essa propriedade está disponível somente no Azure Functions 2.x e superior.

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade	Descrição
tipo	Deve ser definido como `serviceBusTrigger`. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction	Deve ser definido como "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name	O nome da variável que representa a fila ou mensagem de tópico no código de função.
queueName	Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName	Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
subscriptionName	Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
connection	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.
accessRights	Direitos de acesso para a cadeia de caracteres 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 `manage`. Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar, defina `accessRights` como "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e posteriores, essa propriedade não está disponível porque a versão mais recente do SDK de Barramento de Serviço não oferece suporte para operações de gerenciamento.
isSessionsEnabled	`true` se estiver se conectando a `true` assinatura com conhecimento de sessão. `false` caso contrário, que é o valor padrão.
autoComplete	Deve ser `true` para funções não C#, o que significa que o gatilho deve chamar concluído automaticamente após o processamento, ou o código de função chama como concluído manualmente. Se definido como `true`, o gatilho concluirá a mensagem automaticamente, se a execução da função for concluída com êxito, e abandonará a mensagem se ela falhar. Exceções na função resultam nas chamadas de runtime `abandonAsync` em segundo plano. Se nenhuma exceção ocorrer, `completeAsync` será chamado em segundo plano. Essa propriedade está disponível somente no Azure Functions 2.x e superior.

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

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json	Descrição
tipo	Deve ser definido como `serviceBusTrigger`. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction	Deve ser definido como "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name	O nome da variável que representa a fila ou mensagem de tópico no código de função.
queueName	Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName	Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
subscriptionName	Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
connection	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.
accessRights	Direitos de acesso para a cadeia de caracteres 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 `manage`. Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar, defina `accessRights` como "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e posteriores, essa propriedade não está disponível porque a versão mais recente do SDK de Barramento de Serviço não oferece suporte para operações de gerenciamento.
isSessionsEnabled	`true` se estiver se conectando a `true` assinatura com conhecimento de sessão. `false` caso contrário, que é o valor padrão.
autoComplete	Deve ser `true` para funções não C#, o que significa que o gatilho deve chamar concluído automaticamente após o processamento, ou o código de função chama como concluído manualmente. Se definido como `true`, o gatilho concluirá a mensagem automaticamente, se a execução da função for concluída com êxito, e abandonará a mensagem se ela falhar. Exceções na função resultam nas chamadas de runtime `abandonAsync` em segundo plano. Se nenhuma exceção ocorrer, `completeAsync` será chamado em segundo plano. Essa propriedade está disponível somente no Azure Functions 2.x e superior.

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

Consulte a Seção de exemplo para obter exemplos completos.

Uso

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

Type	Descrição
System.String	Use quando a mensagem for de 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 básico.

Os tipos de parâmetro específicos do sistema de mensagens contêm metadados de mensagem adicionais. Os tipos específicos com suporte pelo gatilho do Barramento de Serviço dependem da versão de runtime do Functions, da versão do pacote de extensão e da modalidade de C# usada.

Use o tipo ServiceBusReceivedMessage para receber metadados de mensagem de Filas e Assinaturas do Barramento de Serviço. Para saber mais, confira Mensagens, conteúdos e serialização.

Nas 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 Barramento de Serviço a ser usada. O construtor toma o nome de uma configuração de aplicativo que contenha uma cadeia de conexão de Barramento de Serviço. O atributo pode ser aplicado no nível de classe, método ou parâmetro. O exemplo a seguir mostra o nível de classe e 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 de Barramento de Serviço a ser usada é determinada na seguinte ordem:

A propriedade ServiceBusTrigger do atributoConnection.
O ServiceBusAccount atributo aplicado ao mesmo parâmetro do 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, confira Mensagens, conteúdos 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, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

Embora as bibliotecas mais antigas ainda poderão 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, confira o anúncio de desativação do suporte.

Nas 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 de Barramento de Serviço a ser usada é determinada na seguinte ordem:

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

Os seguintes tipos de parâmetro 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 reconhecer mensagens do contêiner de mensagens, o que é obrigató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, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

Embora as bibliotecas mais antigas ainda poderão 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, confira o anúncio de desativação do suporte.

Nas bibliotecas de classes C#, o construtor do atributo usa o nome da fila ou o tópico e a assinatura. In Azure Functions versão 1.x, você também pode especificar os direitos de acesso da conexão. Se você não especificar os direitos de acesso, o padrão é 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 de Barramento de Serviço a ser usada é determinada na seguinte ordem:

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

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).
ServiceBusReceivedMessage¹	O objeto da mensagem. Ao associar ao `ServiceBusReceivedMessage`, você também pode incluir um parâmetro do tipo ServiceBusMessageActions^1,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 ServiceBusMessageActions^1,2 para executar ações de liquidação de mensagens.

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

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

A mensagem do barramento de serviço de entrada está disponível por meio de um parâmetro ServiceBusQueueMessage ou ServiceBusTopicMessage.

Modelo v4
Modelo v3

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

A instância do Barramento de Serviço está disponível por meio do parâmetro configurado na propriedade do arquivo function.json.

A mensagem da fila está disponível para a função por meio de um parâmetro digitado como func.ServiceBusMessage. A mensagem do Barramento de Serviço é passada em uma função como uma cadeia de caracteres ou um objeto JSON.

Para ver um exemplo completo, consultea seção de exemplos.

conexões

A propriedade connection é uma referência à configuração de ambiente que especifica como o aplicativo deve se conectar ao Barramento de Serviço do Azure. Ela pode especificar:

O nome da configuração de um aplicativo contendo uma cadeia de conexão
O nome de um prefixo compartilhado com várias configurações de aplicativo, definindo juntas uma conexão baseada em identidade.

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

Cadeia de conexão

Para obter uma cadeia de conexão, siga as etapas mostradas em Obter as credenciais de gerenciamento. A cadeia de conexão deve ser voltada para um namespace do Barramento de Serviço, não limitada 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 que corresponda ao valor especificado pela propriedade connection da configuração de associação.

Se o nome de configuração do aplicativo começar com "AzureWebJobs", você pode especificar apenas o resto do nome. Por exemplo, se você configurar connection para "MyServiceBus", o runtime do Functions procura por uma configuração de aplicativo que esteja nomeada "AzureWebJobsMyServiceBus". Se você deixar connection vazio, o runtime de Functions usa a cadeia de caracteres de conexão do Barramento de serviço na configuração de aplicativo chamada "AzureWebJobsServiceBus".

Conexões baseadas em identidade

Caso esteja usando a versão 5.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, faça com que o aplicativo use uma identidade do Microsoft Entra. Para fazer isso, defina as configurações em um prefixo comum que mapeia para a propriedade connection na configuração de gatilho e de associação.

Nesse modo, a extensão exige as seguintes propriedades:

Propriedade	Modelo de variável de ambiente	Descrição	Valor de exemplo
Namespace totalmente qualificado	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	O namespace do Barramento de Serviço totalmente qualificado.	<service_bus_namespace>.servicebus.windows.net

É possível definir propriedades adicionais para personalizar a conexão. Confira Propriedades comuns para conexões baseadas em identidade.

Observação

Ao usar a Configuração de Aplicativos do Azure ou o Key Vault 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 de __ para garantir que os nomes sejam resolvidos corretamente.

Por exemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

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

Conceder permissão para a 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 será necessário atribuir uma função no Azure RBAC, usando as funções internas ou as personalizadas que fornecem essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o escopo apenas sobre os recursos que precisam ser lidos.

Será necessário criar uma atribuição de função que forneça acesso aos seus tópicos e filas em runtime. As funções de gerenciamento como a de Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Barramento de Serviço em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código escrito por você.

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

¹ Para disparar os tópicos do Barramento de Serviço, a atribuição de função precisa ter escopo efetivo sobre o recurso de assinatura do Barramento de Serviço. Se apenas o tópico for incluído, ocorrerá um erro. Alguns clientes, como o portal do Azure, não expõem o recurso de assinatura do Barramento de Serviço como um escopo para atribuição de função. Nesses casos, a CLI do Azure pode ser usada. Para saber mais, confira Funções integradas do Azure para o Azure Barramento de Serviço.

Mensagens suspeitas

A manipulação de mensagens suspeitas não pode ser controlada ou configurada no Azure Functions. O barramento de serviço ele mesmo lida com as mensagens suspeitas.

Comportamento de PeekLock

O runtime do Functions recebe uma mensagem no Modo PeekLock.

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

Por padrão, o runtime chama Complete a mensagem se a função for concluída com êxito ou chamadas Abandon se a função falhar. Você pode desabilitar o preenchimento automático com a autoCompleteMessages propriedade em host.json ou por meio de uma propriedade no atributo de gatilho. Você deve desabilitar o preenchimento automático se o código de função lidar com a liquidação de mensagens.

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

Metadados da mensagem

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

Essas propriedades são membros da classe ServiceBusReceivedMessage.

Propriedade	Type	Descrição
`ApplicationProperties`	`ApplicationProperties`	Propriedades definidas pelo remetente.
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo remetente e destinatário específico para lógica de aplicativo.
`CorrelationId`	`string`	ID de correlação.
`DeliveryCount`	`Int32`	Número total de entregas.
`EnqueuedTime`	`DateTime`	O tempo de enfileiramento no UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	O tempo de enfileiramento agendado no UTC.
`ExpiresAt`	`DateTime`	Tempo de expiração em UTC.
`MessageId`	`string`	Um valor definido pelo usuário que o Barramento de Serviço pode usar para identificar mensagens duplicadas, se habilitado.
`ReplyTo`	`string`	A resposta para o endereço da fila.
`Subject`	`string`	O rótulo específico do aplicativo que pode ser usado no lugar da propriedade `Label` de metadados.
`To`	`string`	Enviar para o endereço.

Essas propriedades são membros da classe de mensagem.

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, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

Embora as bibliotecas mais antigas ainda poderão 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, confira o anúncio de desativação do suporte.

Propriedade	Type	Descrição
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo remetente e destinatário específico para lógica de aplicativo.
`CorrelationId`	`string`	ID de correlação.
`DeliveryCount`	`Int32`	Número total de entregas.
`ScheduledEnqueueTimeUtc`	`DateTime`	O tempo de enfileiramento agendado no UTC.
`ExpiresAtUtc`	`DateTime`	Tempo de expiração em UTC.
`Label`	`string`	Rótulo específico do aplicativo.
`MessageId`	`string`	Um valor definido pelo usuário que o Barramento de Serviço pode usar para identificar mensagens duplicadas, se habilitado.
`ReplyTo`	`string`	A resposta para o endereço da fila.
`To`	`string`	Enviar para o endereço.
`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, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

Embora as bibliotecas mais antigas ainda poderão 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, confira o anúncio de desativação do suporte.

Propriedade	Type	Descrição
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo remetente e destinatário específico para lógica de aplicativo.
`CorrelationId`	`string`	ID de correlação.
`DeadLetterSource`	`string`	A origem de mensagens mortas.
`DeliveryCount`	`Int32`	Número total de entregas.
`EnqueuedTimeUtc`	`DateTime`	O tempo de enfileiramento no UTC.
`ExpiresAtUtc`	`DateTime`	Tempo de expiração em UTC.
`Label`	`string`	Rótulo específico do aplicativo.
`MessageId`	`string`	Um valor definido pelo usuário que o Barramento de Serviço pode usar para identificar mensagens duplicadas, se habilitado.
`MessageReceiver`	`MessageReceiver`	Receptor de mensagem do Service Bus. Pode ser usado para abandonar, concluir ou usar a mensagem de mensagens mortas.
`MessageSession`	`MessageSession`	Um receptor de mensagens especificamente para filas e tópicos habilitados para sessão.
`ReplyTo`	`string`	A resposta para o endereço da fila.
`SequenceNumber`	`long`	Número exclusivo atribuído a uma mensagem pelo Barramento de Serviço.
`To`	`string`	Enviar para o endereço.
`UserProperties`	`IDictionary<string, object>`	Propriedades definidas pelo remetente.

Essas propriedades são membros da classe ServiceBusReceivedMessage.

Propriedade	Type	Descrição
`ApplicationProperties`	`ApplicationProperties`	Propriedades definidas pelo remetente.
`ContentType`	`string`	Um identificador de tipo de conteúdo utilizado pelo remetente e destinatário específico para lógica de aplicativo.
`CorrelationId`	`string`	ID de correlação.
`DeliveryCount`	`Int32`	Número total de entregas.
`EnqueuedTime`	`DateTime`	O tempo de enfileiramento no UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	O tempo de enfileiramento agendado no UTC.
`ExpiresAt`	`DateTime`	Tempo de expiração em UTC.
`MessageId`	`string`	Um valor definido pelo usuário que o Barramento de Serviço pode usar para identificar mensagens duplicadas, se habilitado.
`ReplyTo`	`string`	A resposta para o endereço da fila.
`Subject`	`string`	O rótulo específico do aplicativo que pode ser usado no lugar da propriedade `Label` de metadados.
`To`	`string`	Enviar para o endereço.

Próximas etapas

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

Compartilhar via

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

Exemplo

Atributos

Decoradores

Anotações

Configuração

Uso

conexões

Cadeia de conexão

Conexões baseadas em identidade

Conceder permissão para a identidade

Mensagens suspeitas

Comportamento de PeekLock

Metadados da mensagem

Próximas etapas

Comentários

Recursos adicionais