Associações de saída do Barramento de Serviço para o Azure Functions

  • Artigo

Use a associação de saída do barramento de serviço do Azure para enviar mensagens de fila ou de tópico.

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

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

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 mensagem e a grava em uma segunda fila:

[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 usa um gatilho HTTP com um OutputType objeto para enviar uma resposta HTTP e gravar a mensagem de saída.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

Esse código define o tipo OutputTypede saída múltipla , que inclui a definição de vinculação de saída do Service Bus em OutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

O exemplo a seguir mostra uma função Java que envia uma mensagem a uma fila myqueue do Barramento de Serviço quando disparada por uma solicitação HTTP.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

Na biblioteca de runtime das funções Java, use a anotação @QueueOutput nos parâmetros da função cujo valor poderia ser gravado em uma fila do Barramento de Serviço. O tipo de parâmetro deve ser OutputBinding<T>, onde T é qualquer tipo Java nativo de um POJO.

As funções Java também podem gravar em um tópico do Barramento de Serviço. O exemplo a seguir usa @ServiceBusTopicOutputanotação para descrever a configuração para a associação de saída.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

O exemplo a seguir mostra uma função TypeScript disparada pelo temporizador que envia uma mensagem da fila a cada 5 minutos.

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

O exemplo a seguir mostra uma função JavaScript disparada pelo temporizador que envia uma mensagem da fila a cada 5 minutos.

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

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

O exemplo a seguir mostra uma associação de saída 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": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Aqui está o PowerShell que cria uma mensagem como a saída da função.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

O exemplo a seguir demonstra como gravar em uma fila do Barramento de Serviço em Python. O exemplo depende do modelo de programação v1 ou v2 do Python que você usa.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

Atributos

Ambas as bibliotecas C# em processo e no processo de trabalho isolado usam atributos para definir a associação de saída. Em vez disso, o script em C# usa um arquivo de configuração function.json conforme descrito no guia de redação de scripts em C#.

Em bibliotecas de classes C#, use ServiceBusOutputAttribute para definir a fila ou o tópico gravado pela saída.

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

Propriedade Descrição
EntityType Define o tipo de entidade como Queue para enviar mensagens para uma fila ou Topic ao enviar mensagens para um tópico.
QueueOrTopicName Nome da fila para a qual as mensagens serão enviadas. Use EntityType para definir o tipo de destino.
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.

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_topic_output:

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. Defina somente se for enviar mensagens da fila, não para um tópico.
topic_name Nome do tópico. Defina somente se for enviar mensagens do tópico, não para 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.

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

Anotações

As anotações ServiceBusQueueOutput e ServiceBusTopicOutput estão disponíveis para gravar uma mensagem como uma saída de função. O parâmetro decorado com essas anotações deve ser declarado como um OutputBinding<T> onde T é o tipo correspondente ao tipo da mensagem.

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

Configuração

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

A tabela a seguir explica as propriedades que você pode definir no objeto options transmitido para o método output.serviceBusQueue().

Propriedade Descrição
queueName Nome da 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 tabela a seguir explica as propriedades que você pode definir no objeto options transmitido para o método output.serviceBusTopic().

Propriedade Descrição
topicName Nome do 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.

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 e no atributo ServiceBus.

Propriedade function.json Descrição
tipo Deve ser definido como "serviceBus". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como "out". 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. Definido como "$return" para referenciar o valor de retorno da função.
queueName Nome da fila. Defina somente se for enviar mensagens da fila, não para um tópico.
topicName Nome do tópico. Defina somente se for enviar mensagens do tópico, não para 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 (somente v1) 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.

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 de saída são compatíveis com todas as versões de extensão e modalidades do C#:

Type Descrição
System.String Use quando a mensagem a gravar for de texto simples. Quando o valor de parâmetro não for nulo quando a função sair, o Functions não criará uma mensagem.
byte[] Use para escrever mensagens de dados binários. Quando o valor de parâmetro não for nulo quando a função sair, o Functions não criará uma mensagem.
Objeto Quando uma mensagem contém JSON, o Functions serializa o objeto em um payload de mensagem JSON. Quando o valor do parâmetro for nulo quando a função existir, o Functions criará a mensagem com um objeto nulo.

Os tipos de parâmetro específicos do sistema de mensagens contêm metadados de mensagem adicionais. Os tipos específicos compatíveis com a associação de saída dependem da versão de runtime do Functions, da versão do pacote de extensão e da modalidade C# usada.

Quando você quiser que a função escreva uma única mensagem, a associação de saída do Barramento de Serviço pode ser associada aos seguintes tipos:

Type Descrição
string A mensagem como uma cadeia de caracteres. Use quando a mensagem for de texto simples.
byte[] Os bytes da mensagem.
Tipos serializáveis JSON Um objeto que representa a mensagem. O Functions tenta serializar um tipo de objeto CLR básico (POCO) em dados JSON.

Quando você quiser que a função escreva várias mensagens, a associação de saída do Barramento de Serviço pode ser associada aos seguintes tipos:

Type Descrição
T[] em que T é um dos tipos de mensagem única Uma matriz que contém várias mensagens. Cada entrada representa uma mensagem.

Para outros cenários de saída, crie e use tipos diretamente de Azure.Messaging.ServiceBus.

No Azure Functions 1. x, o runtime criará a fila se ela não existir e você tiver definido accessRights como manage. No Azure Functions versão 2.x e posterior, a fila ou o tópico já precisará existir. Se você especificar uma fila ou um tópico que não existe, a função falhará.

Use o SDK do Barramento de Serviço do Azure em vez da associação de saída interna.

Acesse a mensagem de saída retornando o valor diretamente ou usando context.extraOutputs.set().

A saída para o Barramento de Serviço está disponível por meio do cmdlet Push-OutputBinding em que você passa argumentos que correspondem ao nome designado pelo parâmetro de nome da associação na Push-OutputBinding arquivo.

Use o SDK do Barramento de Serviço do Azure em vez da associação de saída interna.

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:

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
Gatilho1 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

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

Exceções e códigos de retorno

Associação Referência
Barramento de Serviço Códigos de erro do Barramento de Serviço do Microsoft Azure
Barramento de Serviço Limites do Barramento de Serviço do Microsoft Azure

Próximas etapas