Desencadenador de Azure Service Bus para Azure Functions

Artículo
10/26/2023

Utilice el desencadenador de Service Bus para responder a mensajes de una cola o tema de Service Bus. A partir de la versión 3.1.0 de la extensión, puede desencadenar en una cola o un tema habilitados para la sesión.

Para obtener información sobre los detalles de instalación y configuración, vea la información general.

Las decisiones de escalado de Service Bus para los planes Consumo y Premium se toman en función del escalado basado en el destino. Para obtener más información, consulte Escalado basado en el destino.

Importante

En este artículo se usan pestañas para admitir varias versiones del modelo de programación de Node.js. El modelo v4 está disponible de forma general y está diseñado para que los desarrolladores de JavaScript y TypeScript tengan una experiencia más flexible e intuitiva. Para más detalles acerca de cómo funciona el modelo v4, consulte la Guía para desarrolladores de Node.js de Azure Functions. Para más información sobre las diferencias entre v3 y v4, consulte la Guía de migración.

Azure Functions admite dos modelos de programación para Python. La forma en que defina los enlaces depende del modelo de programación seleccionado.

El modelo de programación de Python v2 permite definir enlaces mediante decoradores directamente en el código de función de Python. Para más información, consulte la Guía para desarrolladores de Python.

En este artículo se admiten los modelos de programación.

Ejemplo

Se puede crear una función C# mediante uno de los siguientes modos de C#:

Modelo de trabajo aislado: función compilada en C# que se ejecuta en un proceso trabajador aislado del tiempo de ejecución. Se requiere un proceso de trabajo aislado para admitir funciones de C# ejecutándose en versiones de .NET que son y no son LTS y .NET Framework. Las extensiones para las funciones de proceso de trabajo aisladas usan espacios de nombres Microsoft.Azure.Functions.Worker.Extensions.*.
Modelo en curso: función C# compilada que se ejecuta en el mismo proceso que el tiempo de ejecución de Functions. En una variación de este modelo, Functions se puede ejecutar mediante el scripting de C#, que se admite principalmente para la edición del portal de C#. Las extensiones para funciones en proceso utilizan espacios de nombres Microsoft.Azure.WebJobs.Extensions.*.

Importante

El soporte técnico del modelo en proceso finalizará el 10 de noviembre de 2026. Se recomienda encarecidamente migrar las aplicaciones al modelo de trabajo aislado para obtener soporte técnico completo.

Modelo de trabajo aislado
Modelo de proceso

Este código define e inicializa el ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

En este ejemplo se muestra una función de C# que recibe un único mensaje de cola de Service Bus y lo escribe en los registros:

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

En este ejemplo se muestra una función de C# que recibe varios mensajes de cola de Service Bus en un único lote y escribe cada uno en los registros:

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

En este ejemplo se muestra una función de C# que recibe varios mensajes de cola de Service Bus, los escribe en los registros y, a continuación, liquida el mensaje como completado:

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

En el ejemplo siguiente se muestra una función de C# que lee metadatos de mensaje y registra un mensaje de cola de Service Bus:

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
    string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    ILogger log)
{
    log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"DeliveryCount={deliveryCount}");
    log.LogInformation($"MessageId={messageId}");
}

La siguiente función de Java usa la anotación @ServiceBusQueueTrigger de la @ServiceBusQueueTrigger para describir la configuración de un desencadenador de cola de Service Bus. La función toma el mensaje colocado en la cola y lo agrega a los registros.

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

Las funciones de Java también pueden desencadenarse cuando se agrega un mensaje a un tema de Service Bus. En el ejemplo siguiente se usa la anotación @ServiceBusTopicTrigger para describir la configuración del desencadenador.

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

Model v4
Modelo V3

En el ejemplo siguiente se muestra una función TypeScript de desencadenador de Service Bus. La función lee metadatos de mensaje y registra un mensaje de cola de Service Bus.

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

Model v4
Modelo v3

En el ejemplo siguiente se muestra una función JavaScript de desencadenador de Service Bus. La función lee metadatos de mensaje y registra un mensaje de cola de Service Bus.

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

En el ejemplo siguiente se muestra un enlace de desencadenador de Service Bus en un archivo function.json y una función de JavaScript que usa el enlace. La función lee metadatos de mensaje y registra un mensaje de cola de Service Bus.

Estos son los datos de enlace del archivo function.json:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Este es el código del script de JavaScript:

module.exports = async function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.bindingData.deliveryCount);
    context.log('MessageId =', context.bindingData.messageId);
};

En el ejemplo siguiente se muestra un enlace de desencadenador de Service Bus en un archivo function.json y una función de PowerShell que usa el enlace.

Estos son los datos de enlace del archivo function.json:

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

Esta es la función que se ejecuta cuando se envía un mensaje de Service Bus.

param([string] $mySbMsg, $TriggerMetadata)

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

En el ejemplo siguiente se muestra cómo leer un mensaje de la cola de Service Bus mediante un desencadenador. El ejemplo depende de si usa el modelo de programación de Python v1 o 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'))

Un enlace de Service Bus se define en function.json, donde tipo se establece en serviceBusTrigger y la cola está definida por el queueName.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "inputqueue",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

El código de _init_.py declara un parámetro como func.ServiceBusMessage, que permite leer el mensaje de la cola en la función.

import azure.functions as func

import logging
import json

def main(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message.')

    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'expiration_time': msg.expiration_time,
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': msg.scheduled_enqueue_time,
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
        'metadata' : msg.metadata
    }, default=str)

    logging.info(result)

En el ejemplo siguiente se muestra cómo leer un tema de la cola de Service Bus mediante un desencadenador.

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)

Un enlace de Service Bus se define en function.json, donde tipo se establece en serviceBusTrigger y el tema está definido por el topicName.

{
  "scriptFile": "__init__.py",
  "bindings": [
   {
     "type": "serviceBusTrigger",
     "direction": "in",
     "name": "msg",
     "topicName": "inputtopic",
     "connection": "AzureServiceBusConnectionString"
   }
  ]
}

El código de _init_.py declara un parámetro como func.ServiceBusMessage, que permite leer el tema en la función.

import json

import azure.functions as azf


def main(msg: azf.ServiceBusMessage) -> str:
    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'delivery_count': msg.delivery_count,
        'expiration_time': (msg.expiration_time.isoformat() if
                            msg.expiration_time else None),
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': (msg.scheduled_enqueue_time.isoformat() if
                                   msg.scheduled_enqueue_time else None),
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
    })

    logging.info(result)

Atributos

Las bibliotecas de C# de procesos de trabajo aislados y en proceso usan el atributo ServiceBusTriggerAttribute para definir el desencadenador de la función. En su lugar, el script de C# usa un archivo de configuración function.json como se describe en la Guía de scripting de C#.

Modelo de trabajo aislado
Modelo de proceso

En la tabla siguiente se explican las propiedades que se pueden establecer mediante este atributo de desencadenador:

Propiedad	Descripción
QueueName	Nombre de la cola que se debe supervisar. Se establece únicamente si se supervisa una cola, no un tema.
TopicName	Nombre del tema que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
SubscriptionName	Nombre de la suscripción que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
Connection	Nombre de una configuración de aplicación o colección de parámetros que especifica cómo conectarse a Service Bus. Consulte Conexiones.
IsBatched	Los mensajes se entregan en lotes. Requiere un tipo de matriz o colección.
IsSessionsEnabled	`true` si se conecta a una cola o suscripción `true`. En caso contrario, `false`, que es el valor predeterminado.
AutoCompleteMessages	`true` si el desencadenador debe completar automáticamente el mensaje después de una invocación correcta. `false` si no debe, como cuando se controla la liquidación de mensajes en el código. Si no se establece explícitamente, el comportamiento se basará en la configuración de `host.json`.`autoCompleteMessages`

En la tabla siguiente se explican las propiedades que se pueden establecer mediante este atributo de desencadenador:

Propiedad	Descripción
QueueName	Nombre de la cola que se debe supervisar. Se establece únicamente si se supervisa una cola, no un tema.
TopicName	Nombre del tema que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
SubscriptionName	Nombre de la suscripción que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
Connection	Nombre de una configuración de aplicación o colección de parámetros que especifica cómo conectarse a Service Bus. Consulte Conexiones.
Acceder	Derechos de acceso para la cadena de conexión. Los valores disponibles son `manage` y `listen`. El valor predeterminado es `manage`, lo que indica que `connection` tiene el permiso `manage`. Si usa una cadena de conexión que no tiene el permiso Administrar, establezca `accessRights` en "listen". De lo contrario, el runtime de Functions puede intentar realizar operaciones que requieran derechos de administración y no conseguirlo. En la versión 2.x y posteriores de Azure Functions, esta propiedad no está disponible porque la versión más reciente del SDK de Service Bus no admite operaciones de administración.
IsBatched	Los mensajes se entregan en lotes. Requiere un tipo de matriz o colección.
IsSessionsEnabled	`true` si se conecta a una cola o suscripción `true`. En caso contrario, `false`, que es el valor predeterminado.
AutoComplete	`true`Si el desencadenador debe llamar automáticamente a Complete después del procesamiento o si el código de la función llamará manualmente a Complete. Si se establece en `true`, el desencadenador completa automáticamente el mensaje si la ejecución de la función se completa correctamente y abandona el mensaje en caso contrario. Cuando se establece en `false`, usted es responsable de llamar a los métodos ServiceBusReceiver para completar, abandonar o cerrar el mensaje, sesión o lote. Si se produce una excepción (y no se llama a ninguno de los métodos `ServiceBusReceiver`), se mantiene el bloqueo. Una vez que el bloqueo expira, el mensaje se vuelve a poner en cola con la `DeliveryCount` incrementada y el bloqueo se renueva automáticamente.

Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.

Elementos Decorator

Solo se aplica al modelo de programación de Python v2.

Para las funciones de Python v2 definidas mediante un decorador, se aplican las siguientes propiedades en service_bus_queue_trigger:

Propiedad	Descripción
`arg_name`	Nombre de la variable que representa el mensaje de cola o tema en el código de la función.
`queue_name`	Nombre de la cola que se debe supervisar. Se establece únicamente si se supervisa una cola, no un tema.
`connection`	Nombre de una configuración de aplicación o colección de parámetros que especifica cómo conectarse a Service Bus. Consulte Conexiones.

Para las funciones de Python definidas mediante function.json, consulte la sección Configuración.

anotaciones

La anotación ServiceBusQueueTrigger permite crear una función que se ejecuta cuando se crea un mensaje de la cola de Service Bus. Las opciones de configuración disponibles incluyen las siguientes propiedades:

Propiedad	Descripción
name	Nombre de la variable que representa el mensaje de cola o tema en el código de la función.
queueName	Nombre de la cola que se debe supervisar. Se establece únicamente si se supervisa una cola, no un tema.
topicName	Nombre del tema que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
subscriptionName	Nombre de la suscripción que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
connection	Nombre de una configuración de aplicación o colección de parámetros que especifica cómo conectarse a Service Bus. Consulte Conexiones.

La anotación ServiceBusTopicTrigger permite designar un tema y una suscripción para establecer qué datos desencadenan la función.

Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.

Consulte el ejemplo de desencadenador para más detalles.

Configuración

Solo se aplica al modelo de programación de Python v1.

Model v4
Modelo V3

En la tabla siguiente se explican las propiedades que puede establecer en el objeto pasado options a los métodos app.serviceBusQueue() o app.serviceBusTopic().

Propiedad	Descripción
queueName	Nombre de la cola que se debe supervisar. Se establece únicamente si se supervisa una cola, no un tema.
topicName	Nombre del tema que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
subscriptionName	Nombre de la suscripción que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
connection	Nombre de una configuración de aplicación o colección de parámetros que especifica cómo conectarse a Service Bus. Consulte Conexiones.
accessRights	Derechos de acceso para la cadena de conexión. Los valores disponibles son `manage` y `listen`. El valor predeterminado es `manage`, lo que indica que `connection` tiene el permiso `manage`. Si usa una cadena de conexión que no tiene el permiso Administrar, establezca `accessRights` en "listen". De lo contrario, el runtime de Functions puede intentar realizar operaciones que requieran derechos de administración y no conseguirlo. En la versión 2.x y posteriores de Azure Functions, esta propiedad no está disponible porque la versión más reciente del SDK de Service Bus no admite operaciones de administración.
isSessionsEnabled	`true` si se conecta a una cola o suscripción `true`. En caso contrario, `false`, que es el valor predeterminado.
autoComplete	Debe ser `true` para funciones distintas de C#, lo que significa que el desencadenador debe llamar automáticamente a Complete después del procesamiento, o bien el código de función llama manualmente a Complete. Cuando se establece en `true`, el desencadenador completa automáticamente el mensaje si la ejecución de la función se completa correctamente y abandona el mensaje en caso contrario. Las excepciones en la función dan como resultado las llamadas en tiempo de ejecución `abandonAsync` en segundo plano. Si no se produce ninguna excepción, se llama a `completeAsync` en segundo plano. Esta propiedad solo está disponible en la versión 2 de Azure Functions o en versiones posteriores.

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json.

Propiedad	Descripción
type	Se debe establecer en `serviceBusTrigger`. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.
direction	Debe establecerse en "in". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.
name	Nombre de la variable que representa el mensaje de cola o tema en el código de la función.
queueName	Nombre de la cola que se debe supervisar. Se establece únicamente si se supervisa una cola, no un tema.
topicName	Nombre del tema que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
subscriptionName	Nombre de la suscripción que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
connection	Nombre de una configuración de aplicación o colección de parámetros que especifica cómo conectarse a Service Bus. Consulte Conexiones.
accessRights	Derechos de acceso para la cadena de conexión. Los valores disponibles son `manage` y `listen`. El valor predeterminado es `manage`, lo que indica que `connection` tiene el permiso `manage`. Si usa una cadena de conexión que no tiene el permiso Administrar, establezca `accessRights` en "listen". De lo contrario, el runtime de Functions puede intentar realizar operaciones que requieran derechos de administración y no conseguirlo. En la versión 2.x y posteriores de Azure Functions, esta propiedad no está disponible porque la versión más reciente del SDK de Service Bus no admite operaciones de administración.
isSessionsEnabled	`true` si se conecta a una cola o suscripción `true`. En caso contrario, `false`, que es el valor predeterminado.
autoComplete	Debe ser `true` para funciones distintas de C#, lo que significa que el desencadenador debe llamar automáticamente a Complete después del procesamiento, o bien el código de función llama manualmente a Complete. Cuando se establece en `true`, el desencadenador completa automáticamente el mensaje si la ejecución de la función se completa correctamente y abandona el mensaje en caso contrario. Las excepciones en la función dan como resultado las llamadas en tiempo de ejecución `abandonAsync` en segundo plano. Si no se produce ninguna excepción, se llama a `completeAsync` en segundo plano. Esta propiedad solo está disponible en la versión 2 de Azure Functions o en versiones posteriores.

Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json.

Propiedad de function.json	Descripción
type	Se debe establecer en `serviceBusTrigger`. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.
direction	Debe establecerse en "in". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.
name	Nombre de la variable que representa el mensaje de cola o tema en el código de la función.
queueName	Nombre de la cola que se debe supervisar. Se establece únicamente si se supervisa una cola, no un tema.
topicName	Nombre del tema que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
subscriptionName	Nombre de la suscripción que se debe supervisar. Se establece únicamente si se supervisa un tema, no una cola.
connection	Nombre de una configuración de aplicación o colección de parámetros que especifica cómo conectarse a Service Bus. Consulte Conexiones.
accessRights	Derechos de acceso para la cadena de conexión. Los valores disponibles son `manage` y `listen`. El valor predeterminado es `manage`, lo que indica que `connection` tiene el permiso `manage`. Si usa una cadena de conexión que no tiene el permiso Administrar, establezca `accessRights` en "listen". De lo contrario, el runtime de Functions puede intentar realizar operaciones que requieran derechos de administración y no conseguirlo. En la versión 2.x y posteriores de Azure Functions, esta propiedad no está disponible porque la versión más reciente del SDK de Service Bus no admite operaciones de administración.
isSessionsEnabled	`true` si se conecta a una cola o suscripción `true`. En caso contrario, `false`, que es el valor predeterminado.
autoComplete	Debe ser `true` para funciones distintas de C#, lo que significa que el desencadenador debe llamar automáticamente a Complete después del procesamiento, o bien el código de función llama manualmente a Complete. Cuando se establece en `true`, el desencadenador completa automáticamente el mensaje si la ejecución de la función se completa correctamente y abandona el mensaje en caso contrario. Las excepciones en la función dan como resultado las llamadas en tiempo de ejecución `abandonAsync` en segundo plano. Si no se produce ninguna excepción, se llama a `completeAsync` en segundo plano. Esta propiedad solo está disponible en la versión 2 de Azure Functions o en versiones posteriores.

Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.

Consulte la sección de ejemplos para ver ejemplos completos.

Uso

Todas las modalidades y versiones de extensiones de C# admiten los siguientes tipos de parámetro:

Tipo	Descripción
System.String	Se usa cuando el mensaje es de texto simple.
byte[]	Se usa para los mensajes de datos binarios.
Object	Cuando un mensaje contiene JSON, Functions intenta deserializar los datos JSON en un tipo de objeto CLR antiguo conocido.

Los tipos de parámetros específicos de mensajería contienen metadatos de mensaje adicionales. Los tipos de parámetro admitidos por el desencadenador de Service Bus dependen de la versión del entorno de ejecución de Functions, la versión del paquete de extensiones y la modalidad de C# utilizada.

Use el tipo ServiceBusReceivedMessage para recibir metadatos de mensajes de colas y suscripciones de Service Bus. Para obtener más información, consulte Mensajes, cargas y serialización.

En las bibliotecas de clase de C#, el constructor del atributo toma el nombre de la cola o del tema y la suscripción.

También puede usar ServiceBusAccountAttribute para especificar la cuenta de ServiceBus que se va a usar. El constructor toma el nombre de una configuración de aplicación que contiene una cadena de conexión de Service Bus. El atributo se puede aplicar en el nivel de clase, método o parámetro. En el ejemplo siguiente se muestran el nivel de clase y de método:

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

La cuenta de Service Bus que se debe usar se determina en el orden siguiente:

La propiedad Connection del atributo ServiceBusTrigger.
El atributo ServiceBusAccount aplicado al mismo parámetro que el atributo ServiceBusTrigger.
El atributo ServiceBusAccount aplicado a la función.
El atributo ServiceBusAccount aplicado a la clase.
Configuración de aplicación AzureWebJobsServiceBus.

Use el tipo Mensaje para recibir mensajes con metadatos. Para obtener más información, consulte Mensajes, cargas y serialización.

El 30 de septiembre de 2026, retiraremos las bibliotecas del SDK de Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus y com.microsoft.azure.servicebus, que no se ajustan a las directrices del SDK de Azure. También retiraremos el soporte del protocolo SBMP, por lo que ya no podrás usar este protocolo después del 30 de septiembre de 2026. Migre a las bibliotecas más recientes del SDK de Azure, que ofrecen actualizaciones de seguridad críticas y funcionalidades mejoradas, antes de esa fecha.

Aunque las bibliotecas anteriores todavía se pueden usar después del 30 de septiembre de 2026, ya no recibirán soporte técnico oficial ni actualizaciones de Microsoft. Para obtener más información, consulte el anuncio de retirada de soporte técnico.

En las bibliotecas de clase de C#, el constructor del atributo toma el nombre de la cola o del tema y la suscripción.

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

La cuenta de Service Bus que se debe usar se determina en el orden siguiente:

La propiedad Connection del atributo ServiceBusTrigger.
El atributo ServiceBusAccount aplicado al mismo parámetro que el atributo ServiceBusTrigger.
El atributo ServiceBusAccount aplicado a la función.
El atributo ServiceBusAccount aplicado a la clase.
Configuración de aplicación AzureWebJobsServiceBus.

Los siguientes tipos de parámetro están disponibles para el mensaje de cola o tema:

BrokeredMessage: Proporciona el mensaje deserializado con el método BrokeredMessage.GetBody<T>().
MessageReceiver: Se usa para recibir y confirmar mensajes del contenedor de mensajes, lo que es necesario cuando autoComplete está establecido en false.

El 30 de septiembre de 2026, retiraremos las bibliotecas del SDK de Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus y com.microsoft.azure.servicebus, que no se ajustan a las directrices del SDK de Azure. También retiraremos el soporte del protocolo SBMP, por lo que ya no podrás usar este protocolo después del 30 de septiembre de 2026. Migre a las bibliotecas más recientes del SDK de Azure, que ofrecen actualizaciones de seguridad críticas y funcionalidades mejoradas, antes de esa fecha.

Aunque las bibliotecas anteriores todavía se pueden usar después del 30 de septiembre de 2026, ya no recibirán soporte técnico oficial ni actualizaciones de Microsoft. Para obtener más información, consulte el anuncio de retirada de soporte técnico.

En las bibliotecas de clase de C#, el constructor del atributo toma el nombre de la cola o del tema y la suscripción. En la versión 1.x de Azure Functions, también puede especificar los derechos de acceso de la conexión. Si no los especifica, el valor predeterminado es Manage.

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

La cuenta de Service Bus que se debe usar se determina en el orden siguiente:

La propiedad Connection del atributo ServiceBusTrigger.
El atributo ServiceBusAccount aplicado al mismo parámetro que el atributo ServiceBusTrigger.
El atributo ServiceBusAccount aplicado a la función.
El atributo ServiceBusAccount aplicado a la clase.
Configuración de aplicación AzureWebJobsServiceBus.

Cuando desee que la función procese un único mensaje, el desencadenador de Service Bus puede enlazarse a los siguientes tipos:

Tipo	Descripción
`string`	El mensaje como una cadena. Se usa cuando el mensaje es de texto simple.
`byte[]`	Bytes del mensaje.
Tipos serializables con JSON	Cuando un evento contenga datos JSON, Functions intentará deserializar los datos JSON en un tipo de objeto CLR sin formato (POCO).
ServiceBusReceivedMessage¹	El objeto del mensaje. Si se enlaza a `ServiceBusReceivedMessage`, también puede incluir un parámetro de tipo ServiceBusMessageActions^1,2 para realizar acciones de liquidación de mensajes.

Cuando quiera que la función procese un lote de mensajes, el desencadenador de Service Bus puede enlazarse a los siguientes tipos:

Tipo	Descripción
`T[]` donde `T` es uno de los tipos de mensaje únicos	Una matriz de eventos del lote. Cada entrada representa un evento. Si se enlaza a `ServiceBusReceivedMessage[]`, también puede incluir un parámetro de tipo ServiceBusMessageActions^1,2 para realizar acciones de liquidación de mensajes.

¹ Para utilizar estos tipos, debe hacer referencia a Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 o posterior y a las dependencias comunes para los enlaces de tipo SDK.

^{2 Al usar ServiceBusMessageActions, establezca la AutoCompleteMessages propiedad del atributo trigger en false.} Esto impide que el tiempo de ejecución intente completar los mensajes después de una invocación de función correcta.

Cuando la propiedad Connection no está definida, Functions busca una configuración de aplicación denominada AzureWebJobsServiceBus, que es el nombre predeterminado de la cadena de conexión de Service Bus. También puede establecer la propiedad Connection para especificar el nombre de una configuración de aplicación que contiene la cadena de conexión de Service Bus que se va a usar.

El mensaje de Service Bus entrante está disponible mediante un parámetro ServiceBusQueueMessage o ServiceBusTopicMessage.

Model v4
Modelo V3

Acceda al mensaje de cola o tema como primer argumento de la función. El mensaje de Service Bus se pasa a la función como una cadena o como un objeto JSON.

La instancia de Service Bus está disponible mediante el parámetro configurado en la propiedad function.json de la propiedad del nombre de archivo.

El mensaje de cola está disponible para la función mediante un parámetro de tipo func.ServiceBusMessage. El mensaje de Service Bus se pasa a la función como una cadena o como un objeto JSON.

Para obtener un ejemplo completo, consulte la sección de ejemplos.

Conexiones

La propiedad connection es una referencia a la configuración del entorno que especifica cómo se debe conectar la aplicación a Service Bus. Puede especificar lo siguiente:

El nombre de una configuración de la aplicación que contiene una cadena de conexión.
El nombre de un prefijo compartido para varias configuraciones de la aplicación que juntas definen una conexión basada en identidad.

Si el valor configurado es tanto una coincidencia exacta de una única configuración como una coincidencia de prefijo de otras configuraciones, se usa la coincidencia exacta.

Cadena de conexión

Para obtener la cadena de conexión, siga los pasos mostrados en Obtención de las credenciales de administración. La cadena de conexión debe ser para un espacio de nombres de Service Bus y no estar limitada a una cola o un tema concretos.

La cadena de conexión debe almacenarse en una configuración de la aplicación con un nombre que coincida con el valor especificado por la propiedad connection de la configuración de enlace.

Si el nombre de la configuración de aplicación comienza con "AzureWebJobs", puede especificar solo el resto del nombre. Por ejemplo, si establece connection en "MyServiceBus", el entorno de ejecución de Functions busca una configuración de aplicación llamada "AzureWebJobsMyServiceBus". Si deja el valor de connection vacío, el entorno de ejecución de Functions usa la cadena de conexión de Service Bus predeterminada en la configuración de aplicación que se denomina "AzureWebJobsServiceBus".

Conexiones basadas en identidades

Si usa versión 5.x o posterior de la extensión, en lugar de usar una cadena de conexión con un secreto, puede hacer que la aplicación use una Identidad de Microsoft Entra. Para ello, definiría la configuración con un prefijo común que se asigne a la propiedad connection en la configuración de desencadenador y enlace.

En este modo, la extensión requiere las siguientes propiedades:

Propiedad	Plantilla de variable de entorno	Descripción	Valor de ejemplo
Espacio de nombres completo	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	Espacio de nombres completo de Service Bus.	<service_bus_namespace>.servicebus.windows.net

Se pueden establecer propiedades adicionales para personalizar la conexión. Consulte Propiedades comunes para conexiones basadas en identidades.

Nota

Al usar Azure App Configuration o Key Vault para proporcionar la configuración de las conexiones de identidad administrada, los nombres de configuración deben usar un separador de clave válido, como : o / en lugar de __ para asegurarse de que los nombres se resuelven correctamente.

Por ejemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Cuando se hospeda en el servicio de Azure Functions, las conexiones basadas en identidades usan una identidad administrada. La identidad asignada por el sistema se usa de manera predeterminada, aunque se puede especificar una identidad asignada por el usuario con las propiedades credential y clientID. Tenga en cuenta que no se admite la configuración de una identidad asignada por el usuario con un identificador de recurso. Cuando se ejecuta en otros contextos, como el de desarrollo local, se usa en su lugar la identidad del desarrollador, aunque se puede personalizar. Consulte Desarrollo local con conexiones basadas en identidades.

Concesión de permiso a la identidad

Cualquier identidad que se utilice debe tener permisos para realizar las acciones previstas. Para la mayoría de los servicios de Azure, esto significa que debe asignar un rol en Azure RBAC mediante roles integrados o personalizados que proporcionen esos permisos.

Importante

Es posible que el servicio de destino muestre algunos permisos que no son necesarios para todos los contextos. Siempre que sea posible, respete el principio de privilegios mínimos y conceda solo los privilegios necesarios a la identidad. Por ejemplo, si la aplicación solo necesita poder leer desde un origen de datos, use un rol que solo tenga permiso de lectura. Sería inadecuado asignar un rol que también permita escribir en ese servicio, ya que sería un permiso excesivo para una operación de lectura. De forma similar, le interesa asegurarse de que la asignación de roles esté limitada solo a los recursos que se deben leer.

Tendrá que crear una asignación de roles que proporcione acceso a los temas y las colas en tiempo de ejecución. Los roles de administración, como Propietario, no son suficientes. En la tabla siguiente, se muestran los roles integrados que se recomiendan al usar la extensión de Service Bus en las operaciones normales. Puede que la aplicación precise permisos adicionales en función del código que escriba.

Tipo de enlace	Roles integrados de ejemplo
Desencadenador¹	Receptor de los datos de Azure Service Bus, Propietario de los datos de Azure Service Bus
Enlace de salida	Emisor de datos de Azure Service Bus

¹ Para desencadenar a partir de temas de Service Bus, la asignación de roles debe tener un ámbito efectivo en el recurso de suscripción a Service Bus. Si solo se incluye el tema, se producirá un error. Algunos clientes, como Azure Portal, no exponen el recurso de suscripción a Service Bus como ámbito para la asignación de roles. En tales casos, se podrá usar la CLI de Azure en su lugar. Para obtener más información, consulte Roles integrados de Azure para Azure Service Bus.

Mensajes dudosos

El control de mensajes dudosos no se puede controlar ni configurar en Azure Functions. Service Bus controla este tipo de mensajes.

Comportamiento de PeekLock

El entorno de ejecución de Functions recibe un mensaje en modo PeekLock.

De forma predeterminada, el tiempo de ejecución llama Complete al mensaje si la función finaliza correctamente o llama Abandon a si se produce un error en la función. Puede deshabilitar la finalización automática a través de con la autoCompleteMessages propiedad en host.jsono a través de una propiedad en el atributo trigger. Debe deshabilitar la finalización automática si el código de función controla la liquidación de mensajes.

Si la ejecución de la función dura más que el tiempo de espera de PeekLock, el bloqueo se renovará automáticamente siempre que la función esté en ejecución. El maxAutoRenewDuration se puede configurar en host.json, que se asigna a ServiceBusProcessor.MaxAutoLockRenewalDuration. El valor predeterminado de este ajuste es de 5 minutos.

Metadatos del mensaje

Los tipos específicos de mensajería permiten recuperar fácilmente los metadatos como propiedades del objeto. Estas propiedades dependen de la versión de Functions Runtime, la versión del paquete de extensión y la modalidad de C# usada.

Estas propiedades forman parte de la clase ServiceBusReceivedMessage.

Propiedad	Tipo	Descripción
`ApplicationProperties`	`ApplicationProperties`	Propiedades establecidas por el remitente.
`ContentType`	`string`	Un identificador de tipo de contenido que usa el remitente y el receptor para la lógica específica de la aplicación.
`CorrelationId`	`string`	Identificador de correlación.
`DeliveryCount`	`Int32`	Número total de entregas.
`EnqueuedTime`	`DateTime`	Hora de puesta en la cola en UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	Hora programada de puesta en la cola en UTC.
`ExpiresAt`	`DateTime`	Hora de expiración en UTC.
`MessageId`	`string`	Se trata de un valor definido por el usuario que Service Bus puede utilizar para identificar mensajes duplicados, si está habilitado.
`ReplyTo`	`string`	La respuesta a la dirección de cola.
`Subject`	`string`	Etiqueta específica de la aplicación, que se puede usar en lugar de la propiedad de metadatos `Label`.
`To`	`string`	Dirección de envío.

Estas propiedades forman parte de la clase Message.

El 30 de septiembre de 2026, retiraremos las bibliotecas del SDK de Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus y com.microsoft.azure.servicebus, que no se ajustan a las directrices del SDK de Azure. También retiraremos el soporte del protocolo SBMP, por lo que ya no podrás usar este protocolo después del 30 de septiembre de 2026. Migre a las bibliotecas más recientes del SDK de Azure, que ofrecen actualizaciones de seguridad críticas y funcionalidades mejoradas, antes de esa fecha.

Aunque las bibliotecas anteriores todavía se pueden usar después del 30 de septiembre de 2026, ya no recibirán soporte técnico oficial ni actualizaciones de Microsoft. Para obtener más información, consulte el anuncio de retirada de soporte técnico.

Propiedad	Tipo	Descripción
`ContentType`	`string`	Un identificador de tipo de contenido que usa el remitente y el receptor para la lógica específica de la aplicación.
`CorrelationId`	`string`	Identificador de correlación.
`DeliveryCount`	`Int32`	Número total de entregas.
`ScheduledEnqueueTimeUtc`	`DateTime`	Hora programada de puesta en la cola en UTC.
`ExpiresAtUtc`	`DateTime`	Hora de expiración en UTC.
`Label`	`string`	Etiqueta específica de la aplicación.
`MessageId`	`string`	Se trata de un valor definido por el usuario que Service Bus puede utilizar para identificar mensajes duplicados, si está habilitado.
`ReplyTo`	`string`	La respuesta a la dirección de cola.
`To`	`string`	Dirección de envío.
`UserProperties`	`IDictionary<string, object>`	Propiedades establecidas por el remitente.

Estas propiedades son miembros de las clases BrokeredMessage y MessageReceiver.

El 30 de septiembre de 2026, retiraremos las bibliotecas del SDK de Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus y com.microsoft.azure.servicebus, que no se ajustan a las directrices del SDK de Azure. También retiraremos el soporte del protocolo SBMP, por lo que ya no podrás usar este protocolo después del 30 de septiembre de 2026. Migre a las bibliotecas más recientes del SDK de Azure, que ofrecen actualizaciones de seguridad críticas y funcionalidades mejoradas, antes de esa fecha.

Aunque las bibliotecas anteriores todavía se pueden usar después del 30 de septiembre de 2026, ya no recibirán soporte técnico oficial ni actualizaciones de Microsoft. Para obtener más información, consulte el anuncio de retirada de soporte técnico.

Propiedad	Tipo	Descripción
`ContentType`	`string`	Un identificador de tipo de contenido que usa el remitente y el receptor para la lógica específica de la aplicación.
`CorrelationId`	`string`	Identificador de correlación.
`DeadLetterSource`	`string`	Origen de los mensajes fallidos.
`DeliveryCount`	`Int32`	Número total de entregas.
`EnqueuedTimeUtc`	`DateTime`	Hora de puesta en la cola en UTC.
`ExpiresAtUtc`	`DateTime`	Hora de expiración en UTC.
`Label`	`string`	Etiqueta específica de la aplicación.
`MessageId`	`string`	Se trata de un valor definido por el usuario que Service Bus puede utilizar para identificar mensajes duplicados, si está habilitado.
`MessageReceiver`	`MessageReceiver`	Receptor de mensajes de Service Bus. Se puede usar para abandonar o completar el mensaje, o bien para colocarlo en la cola mensajes fallidos.
`MessageSession`	`MessageSession`	Receptor de mensajes específico para las colas y los temas habilitados para la sesión.
`ReplyTo`	`string`	La respuesta a la dirección de cola.
`SequenceNumber`	`long`	El número único que Service Bus asigna a un mensaje.
`To`	`string`	Dirección de envío.
`UserProperties`	`IDictionary<string, object>`	Propiedades establecidas por el remitente.

Estas propiedades forman parte de la clase ServiceBusReceivedMessage.

Propiedad	Tipo	Descripción
`ApplicationProperties`	`ApplicationProperties`	Propiedades establecidas por el remitente.
`ContentType`	`string`	Un identificador de tipo de contenido que usa el remitente y el receptor para la lógica específica de la aplicación.
`CorrelationId`	`string`	Identificador de correlación.
`DeliveryCount`	`Int32`	Número total de entregas.
`EnqueuedTime`	`DateTime`	Hora de puesta en la cola en UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	Hora programada de puesta en la cola en UTC.
`ExpiresAt`	`DateTime`	Hora de expiración en UTC.
`MessageId`	`string`	Se trata de un valor definido por el usuario que Service Bus puede utilizar para identificar mensajes duplicados, si está habilitado.
`ReplyTo`	`string`	La respuesta a la dirección de cola.
`Subject`	`string`	Etiqueta específica de la aplicación, que se puede usar en lugar de la propiedad de metadatos `Label`.
`To`	`string`	Dirección de envío.

Pasos siguientes

Envío de mensajes de Azure Service Bus desde Azure Functions (enlace de salida)

Compartir a través de

Desencadenador de Azure Service Bus para Azure Functions

Ejemplo

Atributos

Elementos Decorator

anotaciones

Configuración

Uso

Conexiones

Cadena de conexión

Conexiones basadas en identidades

Concesión de permiso a la identidad

Mensajes dudosos

Comportamiento de PeekLock

Metadatos del mensaje

Pasos siguientes

Comentarios

Recursos adicionales