Compartilhar via

gatilho Barramento de Serviço do Azure para Azure Functions

Use o gatilho Barramento de Serviço para responder a mensagens de uma fila ou tópico de Barramento de Serviço. A partir da versão 3.1.0 da extensão, você pode disparar em uma fila ou tópico habilitado para sessão.

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

Barramento de Serviço decisões de dimensionamento para os planos Consumo e Premium são tomadas com base no dimensionamento baseado em destino. Para obter mais informações, confira Colocação em escala baseada em destino.

Importante

Este artigo usa guias para dar suporte a várias versões do modelo de programação Node.js. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Para obter mais detalhes sobre como o modelo v4 funciona, consulte o Azure Functions Node.js guia do desenvolvedor. Para saber mais sobre as diferenças entre os modelos v3 e a v4, consulte o Guia de migração.

Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

O modelo de programação Python v2 permite definir associações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor Python.

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

Exemplo

A função C# pode ser criada por meio de um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. O processo de trabalho isolado é necessário para dar suporte a funções C# em execução em versões LTS e não LTS .NET e no .NET Framework. As extensões para funções de processo de trabalho isoladas usam namespaces Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions. Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. As extensões para funções em processo usam namespaces Microsoft.Azure.WebJobs.Extensions.*.

Importante

O suporte terminará para o modelo em processo em 10 de novembro de 2026. É altamente recomendável migrar seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

Esse código define e inicializa o ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

Este exemplo mostra uma função C# que recebe uma única mensagem de fila Barramento de Serviço e a grava nos logs:

[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 várias mensagens de fila Barramento de Serviço em um único lote e grava 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 várias mensagens de fila Barramento de Serviço, grava-a nos logs e, em seguida, resolve 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 a seguir usa a anotação @ServiceBusQueueTrigger da biblioteca de runtime de funções Java para descrever a configuração de um gatilho de fila Barramento de Serviço. A função captura 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);
 }

Java funções também podem ser disparadas quando uma mensagem é adicionada a um tópico Barramento de Serviço. O exemplo a seguir usa @ServiceBusTopicTriggeranotação para descrever a configuração.

@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 usa o tipo SDK ServiceBusReceivedMessage obtido de ServiceBusMessageContext fornecido pelo gatilho Barramento de Serviço:

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 usando tipos de SDK, consulte o exemplo de estratégia de retirada exponential.

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

O exemplo a seguir mostra uma função Barramento de Serviço trigger TypeScript. A função lê metadados message e registra uma mensagem de fila Barramento de Serviço.

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 a seguir mostra um gatilho Barramento de Serviço A funçãoJavaScript. A função lê metadados message e registra uma mensagem de fila Barramento de Serviço.

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 a seguir mostra uma associação de gatilho Barramento de Serviço em um arquivo function.json e uma função PowerShell que usa a associação.

Aqui estão os dados de associação no arquivo function.json:

{
  "bindings": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Esta é a função que é executada quando uma mensagem de Barramento de Serviço é enviada.

param([string] $mySbMsg, $TriggerMetadata)

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

Este exemplo usa tipos de SDK para acessar diretamente o objeto ServiceBusReceivedMessage subjacente fornecido pelo gatilho Barramento de Serviço:

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 tipo e registra-as ServiceBusReceivedMessage em log.

Para obter mais exemplos usando Barramento de Serviço tipos de SDK, consulte os exemplos de ServiceBusReceivedMessage. Para obter um tutorial passo a passo sobre como incluir associações do tipo SDK em seu aplicativo de funções, siga as associações Python SDK para Barramento de Serviço Sample.

Observação

As limitações conhecidas incluem:

  • Não message há suporte para a propriedade.
  • O suporte a mensagens em lote requer a versão 4.1039 ou posterior do runtime do Functions.

Para saber mais, incluindo quais outras associações de tipo de SDK têm suporte, consulte associações de tipo SDK.

Este exemplo demonstra como ler uma mensagem de fila Barramento de Serviço por meio de um gatilho. O exemplo depende se você usa o v1 ou v2 Python modelo de programação.

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 a seguir demonstra como ler um tópico de fila Barramento de Serviço por meio 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

As bibliotecas in-process e isolated worker C# usam o atributo ServiceBusTriggerAttribute para definir o gatilho de função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia do script C# .

A tabela a seguir explica as propriedades que você pode definir usando este atributo de gatilho:

Propriedade Descrição
Nome da Fila Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
TopicName Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
SubscriptionName Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
Conexão O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.
IsBatched As mensagens são entregues em lotes. Requer um tipo de matriz ou coleção.
isSessionsEnabled true se estiver se conectando a true assinatura com conhecimento de sessão. false caso contrário, que é o valor padrão.
Mensagens de preenchimento automático true se o gatilho deve concluir automaticamente a mensagem após uma invocação 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 na autoCompleteMessages configuração em host.json.

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

Decoradores

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

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

Propriedade Descrição
arg_name O nome da variável que representa a fila ou mensagem de tópico no código de função.
queue_name Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
connection O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.

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

Anotações

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

Propriedade Descrição
nome O nome da variável que representa a fila ou mensagem de tópico no código de função.
queueName Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
nome_da_assinatura Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
conexão O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.

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

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

Confira o exemplo de gatilho para obter mais detalhes.

Configuração

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

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

Propriedade Descrição
queueName Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
nome_da_assinatura Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
conexão O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.
accessRights Direitos de acesso para o cadeia de conexão. Os valores disponíveis são manage e listen. O padrão é manage, que indica que o connection tem a permissão manage. Se você usar um cadeia de conexão que não tenha a permissão Manage, defina accessRights para "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e superior, essa propriedade não está disponível porque a versão mais recente do SDK do Barramento de Serviço não dá suporte a operações de gerenciamento.
isSessionsEnabled true se estiver se conectando a true assinatura com conhecimento de sessão. false caso contrário, que é o valor padrão.
Conclusão automática Deve ser true para funções não C#, o que significa que o gatilho deve chamar concluído automaticamente após o processamento, ou o código de função chama como concluído manualmente.

Se definido como true, o gatilho concluirá a mensagem automaticamente, se a execução da função for concluída com êxito, e abandonará a mensagem se ela falhar.

Exceções na função resultam na chamada abandonAsync de runtime em segundo plano. Se nenhuma exceção ocorrer, completeAsync será chamado em segundo plano. Essa propriedade está disponível apenas no Azure Functions 2.x e superior.

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

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como serviceBusTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal Azure.
direção Deve ser definido como "in". Essa propriedade é definida automaticamente quando você cria o gatilho no portal Azure.
nome O nome da variável que representa a fila ou mensagem de tópico no código de função.
queueName Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
nome_da_assinatura Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
conexão O nome de uma coleção de configurações ou configuração de aplicativo que especifica como se conectar a Barramento de Serviço. Confira a opção Conexões.
accessRights Direitos de acesso para o cadeia de conexão. Os valores disponíveis são manage e listen. O padrão é manage, que indica que o connection tem a permissão manage. Se você usar um cadeia de conexão que não tenha a permissão Manage, defina accessRights para "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e superior, essa propriedade não está disponível porque a versão mais recente do SDK do Barramento de Serviço não dá suporte a operações de gerenciamento.
isSessionsEnabled true se estiver se conectando a true assinatura com conhecimento de sessão. false caso contrário, que é o valor padrão.
Conclusão automática Deve ser true para funções não C#, o que significa que o gatilho deve chamar concluído automaticamente após o processamento, ou o código de função chama como concluído manualmente.

Se definido como true, o gatilho concluirá a mensagem automaticamente, se a execução da função for concluída com êxito, e abandonará a mensagem se ela falhar.

Exceções na função resultam na chamada abandonAsync de runtime em segundo plano. Se nenhuma exceção ocorrer, completeAsync será chamado em segundo plano. Essa propriedade está disponível apenas no Azure Functions 2.x e superior.

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

Consulte a Seção de exemplo para obter exemplos completos.

Uso

Os seguintes tipos de parâmetro são suportados por todas as versões de extensão e modalidades do C#:

Tipo Descrição
System.String Use quando a mensagem for de 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 básico.

Os tipos de parâmetro específicos do sistema de mensagens contêm metadados de mensagem adicionais. Os tipos específicos compatíveis com o gatilho Barramento de Serviço dependem da versão do runtime do Functions, da versão do pacote de extensão e da modalidade C# usada.

Quando você quiser que a função processe uma única mensagem, o gatilho Barramento de Serviço pode ser associado aos seguintes tipos:

Tipo Descrição
string A mensagem como uma cadeia de caracteres. Use quando a mensagem for de texto simples.
byte[] Os bytes da mensagem.
Tipos serializáveis JSON Quando um evento contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR básico (POCO).
ServiceBusReceivedMessage1 O objeto da mensagem.

Ao associar a ServiceBusReceivedMessage, você também pode incluir um parâmetro do tipo ServiceBusMessageActions1,2 para executar ações de liquidação message.

Quando você deseja que a função processe um lote de mensagens, o gatilho Barramento de Serviço pode ser associado aos seguintes tipos:

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

Ao associar a ServiceBusReceivedMessage[], você também pode incluir um parâmetro do tipo ServiceBusMessageActions1,2 para executar ações de liquidação message.

1 Para usar esses tipos, você precisa referenciar Microsoft.Azure. Functions.Worker.Extensions.ServiceBus 5.14.1 ou posterior e as dependências de comando para associações de tipo SDK.

2 Ao usar ServiceBusMessageActionso , defina a AutoCompleteMessages propriedade do atributo de gatilho como false. Isso impede que o runtime tente concluir mensagens após uma invocação de função bem-sucedida.

Quando a propriedade Connection não estiver definida, o Functions procurará uma configuração de aplicativo chamada AzureWebJobsServiceBus, que é o nome padrão do Barramento de Serviço cadeia de conexão. Você também pode definir a propriedade Connection para especificar o nome de uma configuração de aplicativo que contém o Barramento de Serviço cadeia de conexão a ser usado.

A mensagem de Barramento de Serviço de entrada está disponível por meio de um parâmetro ServiceBusQueueMessage ou ServiceBusTopicMessage.

Acesse a fila ou a mensagem de tópico como o primeiro argumento para sua função. A mensagem Barramento de Serviço é passada para a função como uma cadeia de caracteres ou objeto JSON.

A instância Barramento de Serviço está disponível por meio do parâmetro configurado na propriedade de nome do arquivo function.json.

A mensagem da fila está disponível para a função por meio de um parâmetro digitado como func.ServiceBusMessage. A mensagem Barramento de Serviço é passada para a função como uma cadeia de caracteres ou objeto JSON.

As funções também dão suporte Python associações de tipo SDK para Barramento de Serviço do Azure, o que permite que você trabalhe com dados usando esses tipos de SDK subjacentes:

Importante

O suporte para tipos de SDK Barramento de Serviço em Python está em versão prévia e só tem suporte para o modelo de programação Python v2. Para obter mais informações, consulte SDK tipos em Python.

Para ver um exemplo completo, consultea seção de exemplos.

conexões

A propriedade connection faz referência à configuração do ambiente que especifica como o aplicativo se conecta ao Barramento de Serviço. Ele pode especificar:

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

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

Dica

Use conexões de identidade gerenciada em vez de cadeias de conexão para melhorar a segurança. As cadeias de conexão incluem credenciais que podem ser expostas, enquanto as identidades gerenciadas eliminam a necessidade de gerenciar segredos.

Se você estiver usando version 5.x ou superior da extensão, em vez de usar um cadeia de conexão com um segredo, poderá fazer com que o aplicativo use uma identidade Microsoft Entra. Para usar identidades gerenciadas, defina as configurações em um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e associação.

Nesse modo, a extensão requer as seguintes configurações de aplicativo:

Configuração baseada em modelo Descrição Tipo de identidade
<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace O namespace de Barramento de Serviço totalmente qualificado. Atribuído pelo sistema ou atribuído pelo usuário
<CONNECTION_NAME_PREFIX>__credential Deve ser definido como managedidentity. Atribuído pelo usuário
<CONNECTION_NAME_PREFIX>__clientId O ID do cliente da identidade gerenciada atribuída ao usuário. Atribuído pelo usuário

O valor que você substitui <CONNECTION_NAME_PREFIX> é tratado pela extensão de associação como o nome da configuração de conexão.

Por exemplo, se a configuração de associação especificar connection = "ServiceBusConnection" com uma identidade gerenciada atribuída pelo usuário, você definirá as seguintes configurações de aplicativo:

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

Dica

Use identidades gerenciadas atribuídas pelo usuário para cenários de produção em que você precisa de controle refinado sobre permissões de identidade em vários recursos.

Você pode usar outras configurações no modelo para personalizar ainda mais a conexão. Confira Propriedades comuns para conexões baseadas em identidade.

Observação

Ao usar Configuração de Aplicativos do Azure ou Key Vault 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: ServiceBusConnection:fullyQualifiedNamespace

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

Conceder permissão para a identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços Azure, isso significa que você precisa atribuir uma função em Azure RBAC, usando funções internas ou personalizadas que forneçam essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o escopo apenas sobre os recursos que precisam ser lidos.

Será necessário criar uma atribuição de função que forneça acesso aos seus tópicos e filas em runtime. As funções de gerenciamento como a de Proprietário não são suficientes. A tabela a seguir mostra funções internas recomendadas ao usar a extensão Barramento de Serviço em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código escrito por você.

Tipo de associação Exemplo de funções internas
Gatilho1 Barramento de Serviço do Azure Data Receiver, Barramento de Serviço do Azure Data Owner
Associação de saída Barramento de Serviço do Azure Data Sender

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

Mensagens suspeitas

O tratamento de mensagens suspeitas não pode ser controlado ou configurado em Azure Functions. Barramento de Serviço manipula mensagens venenosas em si.

Comportamento de PeekLock

O runtime do Functions recebe uma mensagem no Modo PeekLock.

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

Por padrão, o runtime chama Complete a mensagem se a função for concluída com êxito ou chamadas Abandon se a função falhar. Você pode desabilitar o preenchimento automático com a autoCompleteMessages propriedade em host.json ou por meio de uma propriedade no atributo de gatilho. Você deve desabilitar o preenchimento automático se o código de função lidar com a liquidação de mensagens.

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

Metadados da mensagem

Tipos específicos de mensagens permitem recuperar facilmente metadados como propriedades do objeto. Essas propriedades dependem da versão de runtime do Functions, da versão do pacote de extensão e da modalidade de 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 remetente e destinatário específico para lógica de aplicativo.
CorrelationId string ID de correlação.
DeliveryCount Int32 Número total de entregas.
EnqueuedTime DateTime O tempo de enfileiramento no UTC.
ScheduledEnqueueTimeUtc DateTime O tempo de enfileiramento agendado no UTC.
ExpiresAt DateTime Tempo de expiração em UTC.
MessageId string Um valor definido pelo usuário que Barramento de Serviço pode usar para identificar mensagens duplicadas, se habilitado.
ReplyTo string A resposta para o endereço da fila.
Subject string O rótulo específico do aplicativo que pode ser usado no lugar da propriedade Label de metadados.
To string Enviar para o endereço.

Próximas etapas

  • Last updated on