Vinculação de saída do Barramento de Serviço do Azure 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 tópico.

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 obter mais detalhes sobre como o modelo v4 funciona, consulte o Guia do desenvolvedor do Azure Functions Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

O Azure Functions 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 definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do 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. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
  • 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#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

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 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 para uma fila myqueue do Service Bus quando acionada 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 tempo de execução de funções Java, use a anotação em parâmetros de função cujo valor seria gravado em uma fila @QueueOutput do Service Bus. 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 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 a seguir mostra uma associação de saída do Service Bus em um arquivo function.json e uma função do PowerShell que usa a associaçã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 a seguir demonstra como escrever em uma fila do Service Bus em Python. O exemplo depende se você usa o modelo de programação Python v1 ou v2.

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

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

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 o atributo:

Property Description
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 aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.

Decoradores

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

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

Property Description
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 aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.

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

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.

Property Description
queueName Nome da fila.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar 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.

Property Description
nome_tópico Nome do tópico.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar 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 Description
type Deve ser definido como "serviceBus". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direção Deve ser definido como "out". Essa propriedade é definida automaticamente quando você cria o gatilho no portal do 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 aplicativo ou coleção de configurações que especifica como se conectar ao Service Bus. Consulte Conexões.
accessRights (apenas v1) Direitos de acesso para a 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 Gerenciar . Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar , defina accessRights como "ouvir". Caso contrário, o tempo de execução do Functions pode falhar ao tentar fazer operações que exigem direitos de gerenciamento. 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 Service Bus não oferece suporte a operações de gerenciamento.

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

Os seguintes tipos de parâmetros de saída são suportados por todas as modalidades C# e versões de extensão:

Tipo Description
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 mensagem adicionais. 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 você deseja que a função escreva uma única mensagem, a associação de saída do Service Bus pode se vincular aos seguintes tipos:

Tipo Description
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 você deseja que a função escreva várias mensagens, a associação de saída do Service Bus pode se vincular aos seguintes tipos:

Tipo Description
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 tipos do Azure.Messaging.ServiceBus diretamente.

No Azure Functions 1.x, o tempo de execução cria 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 tópico já deve existir; Se você especificar uma fila ou 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 Service Bus está disponível por meio do Push-OutputBinding cmdlet onde você passa argumentos que correspondem ao nome designado pelo parâmetro name da ligação no arquivo function.json .

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

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

Ligações

A connection propriedade é uma referência à configuração do ambiente que especifica como o aplicativo deve se conectar ao Service Bus. Pode especificar:

  • O nome de uma configuração de aplicativo que contém uma cadeia de conexão
  • O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade.

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.

Connection string

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.

Essa cadeia de conexão deve ser armazenada em uma configuração de aplicativo com um nome correspondente ao valor especificado pela connection propriedade da configuração de ligação.

Se o nome da configuração do aplicativo começar com "AzureWebJobs", você poderá especificar apenas o restante do nome. Por exemplo, se você definir connection como "MyServiceBus", o tempo de execução do Functions procurará uma configuração de aplicativo chamada "AzureWebJobsMyServiceBus". Se você deixar connection vazio, o tempo de execução do Functions usará a cadeia de conexão padrão do Service Bus na configuração do aplicativo chamada "AzureWebJobsServiceBus".

Conexões baseadas em identidade

Se você estiver usando a versão 5.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para fazer isso, você definiria as configurações sob um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e vinculação.

Neste modo, a extensão requer as seguintes propriedades:

Property Modelo de variável de ambiente Description Valor de exemplo
Namespace totalmente qualificado <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace O namespace do Service Bus totalmente qualificado. <service_bus_namespace.servicebus.windows.net>

Propriedades adicionais podem ser definidas para personalizar a conexão. Consulte Propriedades comuns para conexões baseadas em identidade.

Nota

Ao usar a Configuração do Aplicativo do Azure ou o Cofre da Chave 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 do para garantir que os __ nomes sejam resolvidos corretamente.

Por exemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Quando hospedadas no serviço Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. 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 do Azure, isso significa que você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem 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 a seguir mostra as funções internas recomendadas ao usar a extensão do Service Bus em operação 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 Recetor de Dados do Barramento de Serviço do Azure, Proprietário de Dados do Barramento de Serviço do Azure
Vinculação de saída Remetente de dados do Barramento de Serviço do Azure

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

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

Enlace Referência
Service Bus Códigos de erro do Service Bus
Service Bus Limites do Service Bus

Próximos passos