Enlace de salida de Azure Service Bus para Azure Functions

  • Artículo

Use el enlace de salida de Azure Service Bus para enviar mensajes de cola o tema.

Para obtener información sobre los detalles de instalación y configuración, consulte Introducción.

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

La compatibilidad finalizará para el modelo en proceso el 10 de noviembre de 2026. Se recomienda encarecidamente migrar las aplicaciones al modelo de trabajo aislado para obtener compatibilidad completa.

Este código define e inicializa el ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

Este ejemplo muestra una función C# que recibe un mensaje y lo escribe en una segunda cola:

[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 usa un desencadenador HTTP con un OutputType objeto para enviar una respuesta HTTP y escribir el mensaje de salida.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

Este código define el tipo OutputTypede salida múltiple , que incluye la definición de enlace de salida de Service Bus en OutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

En el ejemplo siguiente se muestra una función de Java que envía un mensaje a una cola de Service Bus myqueue cuando una solicitud HTTP la desencadena.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @QueueOutput en los parámetros de función cuyo valor se escribiría en una cola de Service Bus. El tipo de parámetro debe ser OutputBinding<T>, donde T es cualquier tipo nativo de Java de un POJO.

Las funciones de Java también pueden escribir en un tema de Service Bus. En el ejemplo siguiente se usa la anotación @ServiceBusTopicOutput para describir la configuración del enlace de salida.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

En el ejemplo siguiente se muestra una función TypeScript desencadenada por el temporizador que envía un mensaje en cola cada 5 minutos.

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

Para generar varios mensajes, devuelva una matriz en lugar de un solo objeto. Por ejemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

En el ejemplo siguiente se muestra una función TypeScript desencadenada por el temporizador que envía un mensaje en cola cada 5 minutos.

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

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Para generar varios mensajes, devuelva una matriz en lugar de un solo objeto. Por ejemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

En el ejemplo siguiente se muestra un enlace de salida 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": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Este es el PowerShell que crea un mensaje como salida de la función.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

En el ejemplo siguiente se muestra cómo escribir en una cola de Service Bus en Python. 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.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

Atributos

Las bibliotecas de C# en proceso y de proceso de trabajo aislado usan atributos para definir el enlace de salida. 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#.

En las bibliotecas de clase C#, use ServiceBusOutputAttribute para definir la cola o el tema escrito en la salida.

En la tabla siguiente se explican las propiedades que se pueden establecer mediante el atributo:

Propiedad Descripción
EntityType Establece el tipo de entidad para Queue enviar mensajes a una cola o Topic al enviar mensajes a un tema.
QueueOrTopicName Nombre del tema o de la cola a la que se van a enviar mensajes. Use EntityType para establecer el tipo de destino.
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.

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

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. Se establece únicamente si se envían mensajes de cola, no de tema.
topic_name Nombre del tema. Se establece únicamente si se envían mensajes de tema, no de 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.

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

anotaciones

Las anotaciones ServiceBusQueueOutput y ServiceBusTopicOutput están disponibles para escribir un mensaje como salida de la función. El parámetro decorado con estas anotaciones se debe declarar como OutputBinding<T>, donde T es el tipo correspondiente al tipo del mensaje.

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

Configuración

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

En la tabla siguiente se explican las propiedades que puede establecer en el objeto options que se pasa al métodooutput.serviceBusQueue().

Propiedad Descripción
queueName Nombre de la 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.

En la tabla siguiente se explican las propiedades que puede establecer en el objeto options que se pasa al métodooutput.serviceBusTopic().

Propiedad Descripción
topicName Nombre del 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.

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 definen en el archivo function.json y el atributo ServiceBus.

Propiedad de function.json Descripción
type Debe establecerse en "serviceBus". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.
direction Debe establecerse en "out". 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. Se establece en "$return" para hacer referencia al valor devuelto de la función.
queueName Nombre de la cola. Se establece únicamente si se envían mensajes de cola, no de tema.
topicName Nombre del tema. Se establece únicamente si se envían mensajes de tema, no de 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 (solo v1) 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.

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 de salida:

Tipo Descripción
System.String Se usa cuando el mensaje a escribir es de texto simple. Si el valor del parámetro es null cuando finaliza la función, Functions no crea ningún mensaje.
byte[] Se usa para escribir mensajes de datos binarios. Si el valor del parámetro es null cuando finaliza la función, Functions no crea ningún mensaje.
Object Cuando un mensaje contiene JSON, Functions serializa el objeto en una carga de mensaje JSON. Si el valor del parámetro es null cuando finaliza la función, Functions crea un mensaje con un objeto null.

Los tipos de parámetros específicos de mensajería contienen metadatos de mensaje adicionales. Los tipos de parámetro admitidos por el enlace de salida dependen de la versión de Functions Runtime, la versión del paquete de extensión y la modalidad de C# utilizada.

Cuando quiera que la función escriba un único mensaje, el enlace de salida 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 Un objeto que representa el mensaje. Functions intenta serializar un tipo de objetivo CLR (POCO) convencional en datos JSON.

Cuando quiera que la función escriba varios mensajes, el enlace de salida 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 que contiene varios mensajes. Cada entrada representa un mensaje.

Para otros escenarios de salida, cree y use tipos de Azure.Messaging.ServiceBus directamente.

En Azure Functions 1.x, el entorno de ejecución crea la cola si no existe y se estableció accessRights en manage. En la versión 2.x y posteriores de Azure Functions, ya debe existir la cola o el tema. Si especifica una cola o un tema que no existe, la función genera un error.

Use el SDK de Azure Service Bus en lugar del enlace de salida integrado.

Acceda al mensaje de salida devolviendo el valor directamente o mediante context.extraOutputs.set().

La salida a Service Bus está disponible a través del cmdlet Push-OutputBinding, donde se pasan argumentos que coinciden con el nombre designado por el parámetro de nombre del enlace en el archivo Push-OutputBinding.

Use el SDK de Azure Service Bus en lugar del enlace de salida integrado.

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:

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
Desencadenador1 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

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

Excepciones y códigos de retorno

Enlace Referencia
Azure Service Bus Códigos de error de Service Bus
Azure Service Bus Límites de Service Bus

Pasos siguientes