Partilhar via

Azure Service Bus trigger for Funções do Azure

Use o gatilho Service Bus para responder a mensagens de uma fila ou tópico do Service Bus. A partir da versão 3.1.0 da extensão, você pode acionar em uma fila ou tópico habilitado para sessão.

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

As decisões de escalonamento do Service Bus para os planos Consumption e Premium são tomadas com base na escala baseada em alvos. Para obter mais informações, consulte Dimensionamento baseado em destino.

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 única mensagem de fila de Service Bus e a grava nos registos:

[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 mostra uma função C# que recebe múltiplas mensagens de fila de Service Bus num único lote e escreve cada uma nos logs:

[Function(nameof(ServiceBusReceivedMessageBatchFunction))]
public void ServiceBusReceivedMessageBatchFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", IsBatched = true)] ServiceBusReceivedMessage[] messages)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        _logger.LogInformation("Message ID: {id}", message.MessageId);
        _logger.LogInformation("Message Body: {body}", message.Body);
        _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);
    }
}

Este exemplo mostra uma função C# que recebe múltiplas mensagens de fila de Service Bus, escreve-as nos registos e depois define a mensagem como concluída:

[Function(nameof(ServiceBusMessageActionsFunction))]
public async Task ServiceBusMessageActionsFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", AutoCompleteMessages = false)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    // Complete the message
    await messageActions.CompleteMessageAsync(message);
}

A função Java seguinte utiliza a anotação @ServiceBusQueueTrigger da biblioteca de runtime de funções Java para descrever a configuração de um gatilho de fila de Service Bus. A função pega a mensagem colocada na fila e a adiciona aos logs.

@FunctionName("sbprocessor")
 public void serviceBusProcess(
    @ServiceBusQueueTrigger(name = "msg",
                             queueName = "myqueuename",
                             connection = "myconnvarname") String message,
   final ExecutionContext context
 ) {
     context.getLogger().info(message);
 }

Funções Java também podem ser ativadas quando uma mensagem é adicionada a um tópico do Service Bus. O exemplo a seguir usa a @ServiceBusTopicTrigger anotação para descrever a configuração do gatilho.

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

Este exemplo utiliza o tipo SDK ServiceBusReceivedMessage obtido a partir de ServiceBusMessageContext fornecido pelo gatilho Service Bus:

import '@azure/functions-extensions-servicebus'; // Ensure the Service Bus extension is imported
import { app, type InvocationContext } from '@azure/functions';
import { type ServiceBusMessageContext, messageBodyAsJson } from '@azure/functions-extensions-servicebus';

// This sample uses sdkBinding = true with manual message completion.
// With v0.4.0, message.body is returned as a raw Buffer instead of auto-parsed object.
export async function serviceBusQueueTrigger(
    serviceBusMessageContext: ServiceBusMessageContext,
    context: InvocationContext
): Promise<void> {
    const message = serviceBusMessageContext.messages[0];

    // v0.4.0: message.body is a Buffer — use messageBodyAsJson<T>() from the extension for one-line parsing
    const bodyData = messageBodyAsJson(message);
    context.log('Parsed message body:', bodyData);

    // Get current retry count from custom properties, default to 0
    const currentRetryCount = message.applicationProperties?.retryCnt
        ? parseInt(message.applicationProperties.retryCnt as string)
        : 0;
    context.log(`Current retry count: ${currentRetryCount}`);

    if (currentRetryCount >= 3) {
        // After 3 retries, complete the message to remove it from the queue
        context.log(`Maximum retry count (3) reached. Completing message to prevent infinite loop.`);
        await serviceBusMessageContext.actions.complete(message);
        context.log('Message completed after maximum retries');
    } else {
        // Abandon with updated retry count
        const newRetryCount = currentRetryCount + 1;
        const propertiesToModify = {
            retryCnt: newRetryCount.toString(),
            lastRetryTime: new Date().toISOString(),
            errorMessage: 'Processing failed',
        };

        context.log(`Abandoning message with retry count: ${newRetryCount}`);
        await serviceBusMessageContext.actions.abandon(message, propertiesToModify);
    }

    context.log('triggerMetadata: ', context.triggerMetadata);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'ServiceBusConnection',
    queueName: 'testqueue',
    sdkBinding: true,

Para outro exemplo de utilização de tipos SDK, veja a amostra de estratégia de recuo exponencial .

Para mais informações, consulte os tipos de SDK no artigo de referência Node.js.

O exemplo seguinte mostra um disparador Service Bus TypeScript. A função lê metadados mensagem e regista uma mensagem de Service Bus fila.

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

export async function serviceBusQueueTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Service bus queue function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
    context.log('MessageId =', context.triggerMetadata.messageId);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: serviceBusQueueTrigger1,
});

O exemplo seguinte mostra um gatilho Service Bus JavaScript. A função lê metadados mensagem e regista uma mensagem de Service Bus fila.

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

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: (message, context) => {
        context.log('Service bus queue function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
        context.log('MessageId =', context.triggerMetadata.messageId);
    },
});

O exemplo seguinte mostra uma ligação de gatilho 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": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Aqui está a função que é executada quando uma mensagem do Service Bus é enviada.

param([string] $mySbMsg, $TriggerMetadata)

Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"

Este exemplo utiliza tipos de SDK para aceder diretamente ao objeto subjacente ServiceBusReceivedMessage fornecido pelo gatilho Service Bus:

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.servicebus as servicebus

app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)

@app.service_bus_queue_trigger(arg_name="receivedmessage",
                               queue_name="QUEUE_NAME",
                               connection="SERVICEBUS_CONNECTION")
def servicebus_queue_trigger(receivedmessage: servicebus.ServiceBusReceivedMessage):
    logging.info("Python ServiceBus queue trigger processed message.")
    logging.info("Receiving: %s\n"
                 "Body: %s\n"
                 "Enqueued time: %s\n"
                 "Lock Token: %s\n"
                 "Message ID: %s\n"
                 "Sequence number: %s\n",
                 receivedmessage,
                 receivedmessage.body,
                 receivedmessage.enqueued_time_utc,
                 receivedmessage.lock_token,
                 receivedmessage.message_id,
                 receivedmessage.sequence_number)

A função lê várias propriedades do ServiceBusReceivedMessage tipo e as registra.

Para mais exemplos usando Service Bus tipos de SDK, veja as amostras ServiceBusReceivedMessage. Para um tutorial passo a passo sobre como incluir associações do tipo SDK na sua aplicação de funções, siga as ligações SDK Python para Service Bus Exemplo.

Nota

As limitações conhecidas incluem:

  • A message propriedade não é suportada.
  • O suporte a mensagens em lote requer a versão 4.1039 ou posterior do runtime Functions.

Para saber mais, incluindo quais outras associações de tipo SDK são suportadas, consulte Associações de tipo SDK.

Este exemplo demonstra como ler uma mensagem de fila do Service Bus através de um gatilho. O exemplo depende se usas o modelo de programação Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusQueueTrigger1")
@app.service_bus_queue_trigger(arg_name="msg", 
                               queue_name="<QUEUE_NAME>", 
                               connection="<CONNECTION_SETTING>")
def test_function(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message: %s',
                 msg.get_body().decode('utf-8'))

O exemplo seguinte demonstra como ler um tópico de fila de Service Bus através de um gatilho.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusTopicTrigger1")
@app.service_bus_topic_trigger(arg_name="message", 
                               topic_name="TOPIC_NAME", 
                               connection="CONNECTION_SETTING", 
                               subscription_name="SUBSCRIPTION_NAME")
def test_function(message: func.ServiceBusMessage):
    message_body = message.get_body().decode("utf-8")
    logging.info("Python ServiceBus topic trigger processed message.")
    logging.info("Message Body: " + message_body)

Atributos

Tanto in-process como isolated worker process C# utilizam o atributo ServiceBusTriggerAttribute para definir o trigger da função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

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

Propriedade Descrição
Nome da fila Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
Nome do tópico Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
Nome da Subscrição Nome da subscrição a monitorizar. Defina somente se estiver monitorando um tópico, não para uma fila.
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.
IsBatched As mensagens são entregues em lotes. Requer uma matriz ou tipo de coleção.
IsSessionsEnabled true se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. false caso contrário, que é o valor padrão.
AutoCompleteMessages true se o gatilho deve completar automaticamente a mensagem após uma chamada bem-sucedida. false se não deveria, como quando você está lidando com a liquidação de mensagens no código. Se não for definido explicitamente, o comportamento será baseado autoCompleteMessages na configuração em host.json.

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

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

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 a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
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

A anotação ServiceBusQueueTrigger permite criar uma função que é executada quando é criada uma mensagem de fila de Service Bus. As opções de configuração disponíveis incluem as seguintes propriedades:

Propriedade Descrição
Designação O nome da variável que representa a fila ou a mensagem de tópico no código da função.
queueName Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
nome_tópico Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
nome_do-assinante Nome da subscrição a monitorizar. Defina somente se estiver monitorando um 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.

A ServiceBusTopicTrigger anotação permite que você designe um tópico e uma assinatura para direcionar quais dados acionam a função.

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

Consulte o exemplo de gatilho para obter mais detalhes.

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 os app.serviceBusQueue() métodos or app.serviceBusTopic() .

Propriedade Descrição
queueName Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
nome_tópico Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
nome_do-assinante Nome da subscrição a monitorizar. Defina somente se estiver monitorando um 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.
Direitos de acesso 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 usar um cadeia de ligação que não tenha a permissão Manage, defina accessRights para "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.
isSessionsEnabled true se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. false caso contrário, que é o valor padrão.
Preenchimento automático Deve ser true para funções não-C#, o que significa que o gatilho deve chamar automaticamente complete após o processamento ou o código da função chama manualmente complete.

Quando definido como true, o gatilho conclui a mensagem automaticamente se a execução da função for concluída com êxito e abandona a mensagem caso contrário.

Exceções na função resulta na chamada abandonAsync de tempo de execução em segundo plano. Se nenhuma exceção ocorrer, então completeAsync é chamado em segundo plano. Esta propriedade está disponível apenas no Funções do Azure 2.x e versões superiores.

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 .

function.json propriedade Descrição
tipo Deve ser definido como serviceBusTrigger. Esta propriedade é definida automaticamente quando cria o gatilho no portal Azure.
direção Deve ser definido como "in". 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.
queueName Nome da fila a monitorar. Defina somente se estiver monitorando uma fila, não para um tópico.
nome_tópico Nome do tópico a monitorar. Defina somente se estiver monitorando um tópico, não para uma fila.
nome_do-assinante Nome da subscrição a monitorizar. Defina somente se estiver monitorando um 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.
Direitos de acesso 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 usar um cadeia de ligação que não tenha a permissão Manage, defina accessRights para "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.
isSessionsEnabled true se estiver se conectando a uma fila ou assinatura com reconhecimento de sessão. false caso contrário, que é o valor padrão.
Preenchimento automático Deve ser true para funções não-C#, o que significa que o gatilho deve chamar automaticamente complete após o processamento ou o código da função chama manualmente complete.

Quando definido como true, o gatilho conclui a mensagem automaticamente se a execução da função for concluída com êxito e abandona a mensagem caso contrário.

Exceções na função resulta na chamada abandonAsync de tempo de execução em segundo plano. Se nenhuma exceção ocorrer, então completeAsync é chamado em segundo plano. Esta propriedade está disponível apenas no Funções do Azure 2.x e versões superiores.

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 são suportados por todas as modalidades C# e versões de extensão:

Tipo Descrição
System.String Use quando a mensagem for texto simples.
byte[] Use para mensagens de dados binários.
Objeto Quando uma mensagem contém JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR antigo conhecido.

Os tipos de parâmetros específicos de mensagens contêm metadados de mensagem adicionais. Os tipos específicos suportados pelo disparador do Service Bus dependem da versão de execução das funções, da versão do pacote de extensão e da modalidade C# utilizada.

Quando se quer que a função processe uma única mensagem, o gatilho do Service Bus pode ser ligado 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 Quando um evento contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR (POCO) simples.
ServiceBusReceivedMessage1 O objeto message.

Ao ligar a ServiceBusReceivedMessage, pode opcionalmente incluir também um parâmetro do tipo ServiceBusMessageActions1,2 para realizar ações message settlement.

Quando se quer que a função processe um lote de mensagens, o gatilho do Service Bus pode ser ligado aos seguintes tipos:

Tipo Descrição
T[] onde T é um dos tipos de mensagem única Uma matriz de eventos do lote. Cada entrada representa um evento.

Ao ligar a ServiceBusReceivedMessage[], pode opcionalmente incluir também um parâmetro do tipo ServiceBusMessageActions1,2 para realizar ações message settlement.

1 Para usar estes tipos, precisa de consultar Microsoft.Azure. Functions.Worker.Extensions.ServiceBus 5.14.1 ou posterior e as dependências common para ligações de tipos SDK.

2 Ao usar ServiceBusMessageActions, defina a AutoCompleteMessages propriedade do atributo trigger como false. Isso impede que o tempo de execução tente concluir mensagens após uma chamada de função bem-sucedida.

Quando a propriedade Connection não está definida, Funções procura uma definição de aplicação chamada AzureWebJobsServiceBus, que é o nome padrão da Service Bus cadeia de ligação. Também pode definir a propriedade Connection para especificar o nome de uma configuração de aplicação que contenha o Service Bus cadeia de ligação a usar.

A mensagem Service Bus recebida está disponível através de um parâmetro ServiceBusQueueMessage ou ServiceBusTopicMessage.

Acesse a mensagem de fila ou tópico como o primeiro argumento para sua função. A mensagem do Service Bus é passada para a função como uma string ou objeto JSON.

A instância Service Bus está disponível através do parâmetro configurado na propriedade nome do ficheiro function.json.

A mensagem de fila está disponível para a função através de um parâmetro digitado como func.ServiceBusMessage. A mensagem do Service Bus é passada para a função como uma string ou objeto JSON.

A Functions também suporta bindings de tipos de SDK em Python para Azure Service Bus, o que permite trabalhar com dados usando estes tipos de SDK subjacentes:

Importante

O suporte para tipos de SDK Service Bus em Python está em Pré-visualização e é apenas suportado para o modelo de programação Python v2. Para mais informações, veja SDK tipos em Python.

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.

Mensagens venenosas

O tratamento de mensagens venenosas não pode ser controlado ou configurado no Funções do Azure. O Service Bus trata de mensagens de envenenamento sozinho.

Comportamento PeekLock

O tempo de execução do Functions recebe uma mensagem no modo PeekLock.

Por padrão, o tempo de execução chama Complete a mensagem se a função for concluída com êxito ou chama Abandon se a função falhar. Você pode desativar o preenchimento automático através da autoCompleteMessages propriedade em host.json.

Por padrão, o tempo de execução chama Complete a mensagem se a função for concluída com êxito ou chama Abandon se a função falhar. Você pode desabilitar a conclusão automática através da propriedade in autoCompleteMessageshost.json uma propriedade no atributo trigger. Você deve desativar o preenchimento automático se o código da função lidar com a liquidação de mensagens.

Se a função for executada por mais tempo do que o PeekLock tempo limite, o bloqueio será renovado automaticamente enquanto a função estiver em execução. O maxAutoRenewDuration é configurável no host.json, que mapeia para ServiceBusProcessor.MaxAutoLockRenewalDuration. O valor padrão dessa configuração é 5 minutos.

Metadados da mensagem

Os tipos específicos de mensagens permitem recuperar facilmente metadados como propriedades do objeto. Essas propriedades dependem da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Essas propriedades são membros da classe ServiceBusReceivedMessage .

Propriedade Tipo Descrição
ApplicationProperties ApplicationProperties Propriedades definidas pelo remetente.
ContentType string Um identificador de tipo de conteúdo utilizado pelo emissor e recetor para lógica específica do aplicativo.
CorrelationId string O ID de correlação.
DeliveryCount Int32 O número de entregas.
EnqueuedTime DateTime A hora enfileirada em UTC.
ScheduledEnqueueTimeUtc DateTime A hora enfileirada agendada em UTC.
ExpiresAt DateTime O tempo de expiração em UTC.
MessageId string Um valor definido pelo utilizador que o Service Bus pode usar para identificar mensagens duplicadas, se estiver ativado.
ReplyTo string A resposta ao endereço da fila.
Subject string O rótulo específico do aplicativo que pode ser usado no lugar da Label propriedade de metadados.
To string O endereço de envio para.

Próximos passos

  • Last updated on