Partilhar via

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

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 propriedade connection refere-se à configuração do ambiente que especifica como a aplicação se liga à Service Bus. Pode especificar:

  • O nome de uma configuração de aplicação que contém uma cadeia de ligação.
  • O nome de um prefixo partilhado para múltiplas definições de aplicação que, em conjunto, definem uma ligação de identidade gerida.

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

Sugestão

Use ligações de identidade gerida em vez de cadeias de ligação para maior segurança. As cadeias de ligação incluem credenciais que podem ser expostas, enquanto as identidades geridas eliminam a necessidade de gerir segredos.

Se estiveres a usar versão 5.x ou superior da extensão, em vez de usares um cadeia de ligação com um segredo, podes fazer com que a aplicação use uma identidade Microsoft Entra. Para usar identidades geridas, defina definições sob um prefixo comum que corresponda à connection propriedade na configuração de gatilho e ligação.

Neste modo, a extensão requer as seguintes definições de aplicação:

Cenário baseado em modelos Descrição Tipo de identidade
<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace O espaço de nomes totalmente qualificado Service Bus. Atribuído pelo sistema ou pelo utilizador
<CONNECTION_NAME_PREFIX>__credential Deve ser definido como managedidentity. Atribuída pelo utilizador
<CONNECTION_NAME_PREFIX>__clientId A ID do cliente da identidade gerenciada atribuída pelo usuário. Atribuída pelo utilizador

O valor por que substituires <CONNECTION_NAME_PREFIX> é tratado pela extensão de ligação como o nome da definição de ligação.

Por exemplo, se a sua configuração de binding especificar connection = "ServiceBusConnection" uma identidade gerida atribuída pelo utilizador, configura as seguintes definições de aplicação:

{
    "ServiceBusConnection__fullyQualifiedNamespace": "myservicebus.servicebus.windows.net",
    "ServiceBusConnection__credential": "managedidentity",
    "ServiceBusConnection__clientId": "00000000-0000-0000-0000-000000000000"
}

Sugestão

Use identidades geridas atribuídas pelo utilizador para cenários de produção onde precisa de controlo detalhado sobre permissões de identidade em múltiplos recursos.

Podes usar outras definições no template para personalizar ainda mais a ligação. Consulte Propriedades comuns para conexões baseadas em identidade.

Nota

Ao usar Azure App Configuration ou Key Vault para fornecer definições para ligações de Identidade Gerida, os nomes de definição devem usar um separador de chave válido como : ou / em vez do __ para garantir que os nomes são resolvidos corretamente.

Por exemplo: ServiceBusConnection:fullyQualifiedNamespace

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

Conceder permissão à identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços Azure, isto significa que precisa de atribuir um papel no Azure RBAC, usando papéis incorporados ou personalizados que forneçam essas permissões.

Importante

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

Você precisará criar uma atribuição de função que forneça acesso aos seus tópicos e filas em tempo de execução. Funções de gerenciamento como Proprietário não são suficientes. A tabela seguinte mostra os papéis incorporados recomendados ao utilizar a extensão Service Bus em funcionamento normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação Exemplo de funções internas
Gatilho1 Azure Service Bus Recetor de Dados, Azure Service Bus Proprietário dos Dados
Vinculação de saída Azure Service Bus Remetente de Dados

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

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

Enlace Referência
Service Bus Service Bus Códigos de Erro
Service Bus Service Bus Limites

Próximos passos

  • Last updated on