Azure Service Bus output binding for Funções do Azure

Use a vinculação de saída do Azure Service Bus para enviar mensagens de fila ou tópicos.

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

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 mais detalhes sobre como funciona o modelo v4, consulte o guia para desenvolvedores Funções do Azure Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

O Funções do Azure 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-te definir bindings usando decoradores diretamente no teu código de função Python. Para mais informações, consulte o guia para desenvolvedores Python.

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

Exemplo

O suporte Go não está atualmente disponível para esta ligação.

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. É necessário um processo trabalhador isolado para suportar funções C# a correr em versões LTS e não-LTS, como .NET e o framework .NET. Extensões para funções de processos trabalhadores isolados usam espaços de nomes Microsoft.Azure.Functions.Worker.Extensions.*.
  • 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#. Extensões para funções em processo utilizam espaços de nomes 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 total.

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 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
   };
}

Este código define o tipo de saída múltipla OutputType, que inclui a definição Service Bus de ligação de saída em OutputEvent:

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

   public HttpResponseData HttpResponse { get; set; }
}

O exemplo seguinte mostra uma função Java que envia uma mensagem para uma fila de Service Bus myqueue quando é acionada por um pedido 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 de funções Java, use a anotação @QueueOutput nos parâmetros da função cujo valor seria escrito numa fila de Service Bus. O tipo de parâmetro deve ser OutputBinding<T>, onde T é qualquer tipo nativo de Java de um plano antigo Java objeto (POJO).

As funções Java também podem escrever para um tópico do Service Bus. O exemplo a seguir usa a @ServiceBusTopicOutput anotaçã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 acionada por temporizador que envia uma mensagem de 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 acionada por temporizador que envia uma mensagem de 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 seguinte mostra uma ligação de saída Service Bus num ficheiro function.json e uma função PowerShell que utiliza a ligação.

Aqui estão os dados de ligaçã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 saída da função.

param($QueueItem, $TriggerMetadata) 

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

O exemplo seguinte demonstra como escrever para um Service Bus tópicos e filas de Service Bus em Python. O exemplo depende se usas o modelo de programação Python v1 ou v2.

Este exemplo mostra como escrever para um tema de Service Bus.

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 escrever para uma fila de Service Bus.

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

As bibliotecas C# do processo de trabalho em processo e isoladas usam atributos para definir a ligação de saída. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Nas bibliotecas de classes C#, use o ServiceBusOutputAttribute para definir a fila ou tópico para o qual foi escrito pela saída.

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

Propriedade Descrição
Tipo de entidade Define o tipo de entidade como Queue para enviar mensagens para uma fila ou Topic ao enviar mensagens para um tópico.
QueueOrTopicName Nome do tópico ou fila para a qual enviar mensagens. Use EntityType para definir o tipo de destino.
Ligação O nome de uma configuração de aplicação ou coleção de definições que especifica como se ligar ao Service Bus. Consulte Conexões.

Decoradores

Aplica-se apenas ao 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 a mensagem de tópico no código da função.
queue_name Nome da fila. Defina apenas se enviar mensagens de fila, não para um tópico.
topic_name Nome do tópico. Defina somente se estiver enviando mensagens de tópico, não para uma fila.
connection O nome de uma configuração de aplicação ou coleção de definições que especifica como se ligar ao Service Bus. Consulte Conexões.

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

Anotações

As ServiceBusQueueOutput anotações e ServiceBusTopicOutput estão disponíveis para escrever 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 estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values coleção.

Configuração

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

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

Propriedade Descrição
queueName Nome da fila.
conexão O nome de uma configuração de aplicação ou coleção de definições que especifica como se ligar ao Service Bus. Consulte Conexões.

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

Propriedade Descrição
nome_tópico Nome do tópico.
conexão O nome de uma configuração de aplicação ou coleção de definições que especifica como se ligar ao Service Bus. Consulte Conexões.

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

function.json propriedade Descrição
tipo Deve ser definido como serviceBus. Esta propriedade é definida automaticamente quando cria o gatilho no portal Azure.
direção Deve ser definido como out. Esta propriedade é definida automaticamente quando cria o gatilho no portal Azure.
Designação O nome da variável que representa a fila ou a mensagem de tópico no código da função. Defina como "$return" para fazer referência ao valor de retorno da função.
queueName Nome da fila. Defina apenas se enviar mensagens de fila, não para um tópico.
nome_tópico Nome do tópico. Defina somente se estiver enviando mensagens de tópico, não para uma fila.
conexão O nome de uma configuração de aplicação ou coleção de definições que especifica como se ligar ao Service Bus. Consulte Conexões.
accessRights (apenas v1) Direitos de acesso para a cadeia de ligaçã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 usares uma cadeia de ligação que não tenha a permissão Manage, define accessRights como "listen". Caso contrário, o tempo de execução do Functions pode falhar ao tentar fazer operações que exigem direitos de gerenciamento. No Funções do Azure versão 2.x e superiores, esta propriedade não está disponível porque a versão mais recente do Service Bus SDK não suporta gerir operações.

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

Todas as modalidades C# e versões de extensão suportam os seguintes tipos de parâmetros de saída:

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

Os tipos de parâmetros específicos de mensagens contêm metadados de mensagens extras e não são compatíveis com a serialização JSON. Como resultado, não é possível usar ServiceBusMessage com a ligação de saída no modelo isolado. Os tipos específicos suportados pela ligação de saída dependem da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Quando se quer que a função escreva uma única mensagem, a ligação de saída do Service Bus pode ser ligada aos seguintes tipos:

Tipo Descrição
string A mensagem como uma cadeia de caracteres. Use quando a mensagem for texto simples.
byte[] Os bytes da mensagem.
Tipos serializáveis JSON Um objeto que representa a mensagem. As funções tentam serializar um tipo de objeto CLR (POCO) antigo em dados JSON.

Quando se quer que a função escreva múltiplas mensagens, a ligação de saída do Service Bus pode ser ligada aos seguintes tipos:

Tipo Descrição
T[] onde 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. Mensagens.ServiceBus diretamente. Veja Register Azure clientes para um exemplo de utilização da injeção de dependências para criar um tipo de cliente a partir do SDK do Azure.

Na Funções do Azure 1.x, o runtime cria a fila se esta não existir e tens definido accessRights para manage. No Funções do Azure versão 2.x e superiores, a fila ou tópico já deve existir; se especificar uma fila ou tópico que não existe, a função falha.

Use o SDK Azure Service Bus em vez da ligação de saída incorporada.

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

A saída para o Service Bus está disponível através do cmdlet Push-OutputBinding, onde se passam argumentos que correspondem ao nome designado pelo parâmetro de nome da ligação no ficheiro function.json.

O parâmetro da 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. Alternativamente, podes usar o SDK Azure Service Bus em vez da ligação de saída incorporada.

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

Ligações

A connection propriedade é uma referência a uma chave nas definições da aplicação que devolve um valor usado pelo runtime das Funções para se ligar à instância do Service Bus usada pela extensão. O valor da definição de propriedade de ligação depende do tipo de ligação:

  • Ligação de identidade gerida: A connection propriedade é <CONNECTION_NAME_PREFIX> partilhada por um grupo de definições que, em conjunto, definem uma ligação baseada em identidade ao Service Bus. Para mais informações, consulte Definir ligações de identidade.
  • Referência Key Vault: A connection definição de propriedade devolve uma referência Azure Key Vault ao local onde a cadeia de ligação é mantida centralmente. Para mais informações, consulte Definir ligações ao Key Vault.
  • Referência de App Configuration: A connection definição de propriedade devolve uma referência Azure App Configuration que devolve uma cadeia de ligação ou uma referência ao Key Vault. Para mais informações, consulte Azure App Configuration no artigo de ligações.
  • Connection string: A connection definição de propriedade devolve a cadeia de ligação real para a instância do Service Bus. Como a cadeia de ligação contém chaves secretas partilhadas, deve considerar usar uma ligação de identidade gerida, sempre que possível. Para mais informações, veja Definir ligações.

Para saber mais sobre ligações de ligações, consulte Gerir ligação no Funções do Azure.

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.

Se o nome da definição da aplicação começar por AzureWebJobs, pode especificar apenas o restante do nome. Por exemplo, se definires connection para MyServiceBus, o tempo de execução das Funções procura uma definição de aplicação chamada AzureWebJobsMyServiceBus. Se deixares connection vazio, o runtime das Funções usa o Service Bus cadeia de ligação predefinido na definição da aplicação que se chama AzureWebJobsServiceBus.

Permissões de escalonamento

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

  • Cadeias de ligação SAS: A política SAS deve incluir o direito de gerir acesso.
  • Ligações baseadas em identidade: A identidade deve ser atribuída ao papel Azure Service Bus Data Owner, ou a um papel personalizado que inclua Microsoft.ServiceBus/namespaces/*/read.

Quando a ligação não tem estas permissões, não vês erros no arranque. Em vez disso, a extensão recorre silenciosamente ao uso de estimativa de mensagens baseada em peek, que é menos precisa e pode resultar em decisões de escalabilidade atrasadas ou incorretas.

Sugestão

Para cargas de trabalho de produção que dependem de auto-escalabilidade, inclua o direito de acesso Gerenciar (SAS) ou atribua o papel de Proprietário de Dados do Azure Service Bus (ligações baseadas em identidade) para garantir um comportamento de escala preciso. cadeia de ligação na definição da aplicação que se chama AzureWebJobsServiceBus.

Exceções e códigos de devolução

Enlace Referência
Barramento de Serviço Service Bus Códigos de Erro
Barramento de Serviço Service Bus Limites

Próximos passos

  • Last updated on