Barramento de Serviço do Azure associação de saída para Azure Functions

Use Barramento de Serviço do Azure associação de saída para enviar mensagens de fila ou 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 o modelo v4 funciona, consulte o Azure Functions Node.js guia do desenvolvedor. Para saber mais sobre as diferenças entre os modelos v3 e a v4, consulte o Guia de migraçã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 Python v2 permite definir associações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor Python.

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

Exemplo

O suporte do Go não está disponível para essa ligação no momento.

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. O processo de trabalho isolado é necessário para dar suporte a funções C# em execução em versões LTS e não LTS .NET e no .NET Framework. As extensões para funções de 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 em 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.

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 de saída múltiplo OutputType, que inclui a definição de associação de saída Barramento de Serviço 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 para uma fila Barramento de Serviço myqueue 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 Java functions runtime, use a anotação @QueueOutput em parâmetros de função cujo valor seria gravado em uma fila de Barramento de Serviço. O tipo de parâmetro deve ser OutputBinding<T>, em que T é qualquer tipo de Java nativo de um pojo (objeto Java antigo) do plano.

Java funções também podem gravar em um tópico 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 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 um Barramento de Serviço tópicos e Barramento de Serviço filas em Python. O exemplo depende se você usa o v1 ou v2 Python modelo de programação.

Este exemplo mostra como gravar em um tópico Barramento de Serviço.

import logging
import azure.functions as func

app = func.FunctionApp()

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

Este exemplo mostra como gravar em uma fila de Barramento de Serviço.

import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_queue_output(
    arg_name="msg",
    connection="AzureServiceBusConnectionString",
    queue_name="outqueue")
def put_message(req: func.HttpRequest, msg: func.Out[str]):
    msg.set(req.get_body().decode('utf-8'))
    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 o ServiceBusOutputAttribute para definir a fila ou o tópico escrito 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 coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.

Decoradores

Aplica somente para o modelo de programação Python v2.

Para Python funções 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 coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.

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

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 somente para o modelo de programação Python v1.

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.
conexão O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a 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.
conexão O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a 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 Azure.
direção Deve ser definido como out. Essa propriedade é definida automaticamente quando você cria o gatilho no portal Azure.
nome 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.
conexão O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.
accessRights (somente v1) Direitos de acesso para o 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 manage. Se você usar um cadeia de conexão que não tenha a permissão Manage, defina accessRights para "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 superior, essa propriedade não está disponível porque a versão mais recente do SDK do Barramento de Serviço não dá suporte a 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

Todas as modalidades e versões de extensão do C# dão suporte aos seguintes tipos de parâmetro de saída:

Tipo 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 de mensagens contêm metadados de mensagem extras e não são compatíveis com a serialização JSON. Como resultado, não é possível usar ServiceBusMessage com a associação de saída no modelo isolado. 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 Barramento de Serviço pode ser associada aos seguintes tipos:

Tipo 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 Barramento de Serviço pode ser associada aos seguintes tipos:

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

Para outros cenários de saída, crie e use um ServiceBusClient com outros tipos de Azure. Messaging.ServiceBus diretamente. Consulte Register Azure clientes para obter um exemplo de como usar a injeção de dependência para criar um tipo de cliente do SDK do Azure.

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 superior, a fila ou o tópico já deve existir; se você especificar uma fila ou um tópico que não existe, a função falhará.

Use o SDK 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 no arquivo function.json.

O parâmetro de função de saída deve ser definido como func.Out[str] ou func.Out[bytes]. Consulte o exemplo de saída para obter detalhes. Como alternativa, você pode usar o SDK 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 connection propriedade é uma referência a uma chave nas configurações da aplicação que retorna um valor usado pelo runtime das Funções para se conectar à instância do Barramento de Serviço usada pela extensão. O valor da configuração da propriedade de conexão depende do tipo de conexão:

  • Conexão de identidade gerenciada: A connection propriedade é <CONNECTION_NAME_PREFIX> compartilhada por um grupo de configurações que, juntas, definem uma conexão baseada em identidade com o Barramento de Serviço. Para mais informações, veja Definir conexões de identidade.
  • Referência Key Vault: A connection configuração de propriedade retorna uma referência ao Azure Key Vault para o local onde a cadeia de conexão é mantida centralmente. Para mais informações, veja Definir conexões do Key Vault.
  • Referência de App Configuration: A connection configuração de propriedade retorna uma referência ao Configuração de Aplicativos do Azure que retorna uma cadeia de conexão ou uma referência ao Key Vault. Para mais informações, veja Configuração de Aplicativos do Azure no artigo de conexões.
  • Connection string: A connection configuração de propriedade retorna a cadeia de conexão real para a instância do Barramento de Serviço. Como a cadeia de conexão contém chaves secretas compartilhadas, você deve considerar usar uma conexão de identidade gerenciada, sempre que possível. Para mais informações, veja Definir conexões.

Para saber mais sobre conexões de bindings, veja Gerenciar conexão no Azure Functions.

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.

Se o nome da configuração do app começar com AzureWebJobs, você pode especificar apenas o restante do nome. Por exemplo, se você definir connection como MyServiceBus, o runtime do Functions procurará uma configuração de aplicativo chamada AzureWebJobsMyServiceBus. Se você deixar connection vazio, o runtime das Funções usa a Barramento de Serviço cadeia de conexão padrão na configuração do app, que é chamada AzureWebJobsServiceBus.

Permissões de escalonamento

A extensão Barramento de Serviço utiliza a API de Administração do Barramento de Serviço (GetQueueRuntimePropertiesAsync / GetSubscriptionRuntimePropertiesAsync) para recuperar contagens precisas de mensagens para decisões de escala. Esta API requer permissões adicionais além do necessário para enviar ou receber mensagens:

  • Strings de conexão SAS: A política SAS deve incluir o direito de Gerenciar acesso.
  • Conexões baseadas em identidade: A identidade deve ser atribuída ao papel Barramento de Serviço do Azure Data Owner, ou a um papel personalizado que inclua Microsoft.ServiceBus/namespaces/*/read.

Quando a conexão não tem essas permissões, você não vê erros na inicialização. Em vez disso, a extensão silenciosamente volta a usar estimativa de mensagens baseada em peek, que é menos precisa e pode resultar em decisões de escalonamento atrasadas ou incorretas.

Dica

Para cargas de trabalho de produção que dependem de auto-escalonamento, inclua o direito de acesso Gerenciar (SAS) ou atribua o papel de Proprietário de Dados do Barramento de Serviço do Azure (conexões baseadas em identidade) para garantir um comportamento de escala preciso. cadeia de conexão na configuração do app que é chamada AzureWebJobsServiceBus.

Exceções e códigos de retorno

Associação Referência
Barramento de Serviço códigos de erro Barramento de Serviço
Barramento de Serviço limites Barramento de Serviço

Próximas etapas

  • Last updated on