Enlaces de Azure Service Bus en Azure FunctionsAzure Service Bus bindings for Azure Functions

En este artículo se explica cómo trabajar con enlaces de Azure Service Bus en Azure Functions.This article explains how to work with Azure Service Bus bindings in Azure Functions. Azure Functions admite enlaces de desencadenador y salida para colas y temas de Service Bus.Azure Functions supports trigger and output bindings for Service Bus queues and topics.

Esta es la información de referencia para desarrolladores de Azure Functions.This is reference information for Azure Functions developers. Si está familiarizado con Azure Functions, comience con los siguientes recursos:If you're new to Azure Functions, start with the following resources:

Paquetes: Functions 1.xPackages - Functions 1.x

Los enlaces de Service Bus se proporcionan en el paquete NuGet Microsoft.Azure.WebJobs.ServiceBus, versión 2.x.The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.ServiceBus NuGet package, version 2.x.

En la siguiente tabla se explica cómo agregar compatibilidad para este enlace en cada entorno de desarrollo.The following table tells how to add support for this binding in each development environment.

Entorno de desarrolloDevelopment environment Para agregar compatibilidad enTo add support in
Functions 1.xFunctions 1.x
Desarrollo local: biblioteca de clases C#Local development - C# class library Instalación del paqueteInstall the package
Desarrollo local: script de C#, JavaScript, F#Local development - C# script, JavaScript, F# AutomáticoAutomatic
Desarrollo con PortalPortal development AutomáticoAutomatic

Paquetes: Functions 2.xPackages - Functions 2.x

Los enlaces de Service Bus se proporcionan en el paquete NuGet Microsoft.Azure.WebJobs.Extensions.ServiceBus, versión 3.x.The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.Extensions.ServiceBus NuGet package, version 3.x. El código fuente del paquete se encuentra en el repositorio azure-webjobs-sdk de GitHub.Source code for the package is in the azure-webjobs-sdk GitHub repository.

En la siguiente tabla se explica cómo agregar compatibilidad para este enlace en cada entorno de desarrollo.The following table tells how to add support for this binding in each development environment.

Entorno de desarrolloDevelopment environment Para agregar compatibilidad enTo add support in
Functions 2.xFunctions 2.x
Desarrollo local: biblioteca de clases C#Local development - C# class library Instalación del paqueteInstall the package
Desarrollo local: script de C#, JavaScript, F#, Java y PythonLocal development - C# script, JavaScript, F#, Java and Python Registro de la extensiónRegister the extension
Desarrollo con PortalPortal development Instalación al agregar el enlace de salidaInstall when adding output binding

Para saber cómo actualizar las extensiones de enlace existentes en el portal sin tener que volver a publicar su proyecto de aplicación de función, consulte Actualización de las extensiones.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

DesencadenadorTrigger

Utilice el desencadenador de Service Bus para responder a mensajes de una cola o tema de Service Bus.Use the Service Bus trigger to respond to messages from a Service Bus queue or topic.

Desencadenador: ejemploTrigger - example

Vea el ejemplo específico del lenguaje:See the language-specific example:

Desencadenador: ejemplo de C#Trigger - C# example

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:The following example shows a C# function that reads message metadata and logs a Service Bus queue message:

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", AccessRights.Manage, 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}");
}

Este ejemplo va dirigido a Azure Functions 1.x.This example is for Azure Functions version 1.x. Para que este código funcione con 2.x:To make this code work for 2.x:

Desencadenador: ejemplo de script de C#Trigger - C# script example

En el ejemplo siguiente se muestra un enlace de desencadenador de Service Bus en un archivo function.json y una función de script de C# que usa el enlace.The following example shows a Service Bus trigger binding in a function.json file and a C# script function that uses the binding. La función lee metadatos de mensaje y registra un mensaje de cola de Service Bus.The function reads message metadata and logs a Service Bus queue message.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

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

Este es el código de script de C#:Here's the C# script code:

using System;

public static void Run(string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    TraceWriter log)
{
    log.Info($"C# ServiceBus queue trigger function processed message: {myQueueItem}");

    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"DeliveryCount={deliveryCount}");
    log.Info($"MessageId={messageId}");
}

Desencadenador: ejemplo de F#Trigger - F# example

En el ejemplo siguiente se muestra un enlace de desencadenador de Service Bus en un archivo function.json y una función de F# que usa el enlace.The following example shows a Service Bus trigger binding in a function.json file and an F# function that uses the binding. La función registra un mensaje de cola de Service Bus.The function logs a Service Bus queue message.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

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

Este es el código del script de F#:Here's the F# script code:

let Run(myQueueItem: string, log: ILogger) =
    log.LogInformation(sprintf "F# ServiceBus queue trigger function processed message: %s" myQueueItem)

Desencadenador: ejemplo de JavaTrigger - Java example

La siguiente función de Java usa la @ServiceBusQueueTrigger anotación desde el Java funciones de biblioteca en tiempo de ejecución para describir la configuración de un desencadenador de cola de Service Bus.The following Java function uses the @ServiceBusQueueTrigger annotation from the Java functions runtime library to describe the configuration for a Service Bus queue trigger. La función toma el mensaje colocado en la cola y lo agrega a los registros.The function grabs the message placed on the queue and adds it to the logs.

@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 activarse cuando se agrega un mensaje a un tema de Service Bus.Java functions can also be triggered when a message is added to a Service Bus topic. En el ejemplo siguiente se usa el @ServiceBusTopicTrigger anotación para describir la configuración del desencadenador.The following example uses the @ServiceBusTopicTrigger annotation to describe the trigger configuration.

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

Desencadenador: ejemplo de JavaScriptTrigger - JavaScript example

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.The following example shows a Service Bus trigger binding in a function.json file and a JavaScript function that uses the binding. La función lee metadatos de mensaje y registra un mensaje de cola de Service Bus.The function reads message metadata and logs a Service Bus queue message.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

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

Este es el código del script de JavaScript:Here's the JavaScript script code:

module.exports = 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);
    context.done();
};

Desencadenador: atributosTrigger - attributes

Para las bibliotecas de clases de C#, utilice los siguientes atributos para configurar un desencadenador de Service Bus:In C# class libraries, use the following attributes to configure a Service Bus trigger:

  • ServiceBusTriggerAttributeServiceBusTriggerAttribute

    El constructor del atributo toma el nombre de la cola o del tema y la suscripción.The attribute's constructor takes the name of the queue or the topic and subscription. En la versión 1.x de Azure Functions, también puede especificar los derechos de acceso de la conexión.In Azure Functions version 1.x, you can also specify the connection's access rights. Si no los especifica, el valor predeterminado es Manage.If you don't specify access rights, the default is Manage. Para más información, consulte la sección Desencadenador: configuración.For more information, see the Trigger - configuration section.

    A continuación, tiene un ejemplo que muestra el atributo que se usa con un parámetro de cadena:Here's an example that shows the attribute used with a string parameter:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue")] string myQueueItem, ILogger log)
    {
        ...
    }
    

    Puede establecer la propiedad Connection para especificar la cuenta de Service Bus que se usará, tal como se muestra en el ejemplo siguiente:You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
        string myQueueItem, ILogger log)
    {
        ...
    }
    

    Para un ejemplo completo, consulte Desencadenador: ejemplo de C#.For a complete example, see Trigger - C# example.

  • ServiceBusAccountAttributeServiceBusAccountAttribute

    Proporciona otra manera de especificar la cuenta de Service Bus que se debe usar.Provides another way to specify the Service Bus account to use. El constructor toma el nombre de una configuración de aplicación que contiene una cadena de conexión de Service Bus.The constructor takes the name of an app setting that contains a Service Bus connection string. El atributo se puede aplicar en el nivel de clase, método o parámetro.The attribute can be applied at the parameter, method, or class level. En el ejemplo siguiente se muestran el nivel de clase y de método:The following example shows class level and method level:

    [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:The Service Bus account to use is determined in the following order:

  • La propiedad Connection del atributo ServiceBusTrigger.The ServiceBusTrigger attribute's Connection property.
  • El atributo ServiceBusAccount aplicado al mismo parámetro que el atributo ServiceBusTrigger.The ServiceBusAccount attribute applied to the same parameter as the ServiceBusTrigger attribute.
  • El atributo ServiceBusAccount aplicado a la función.The ServiceBusAccount attribute applied to the function.
  • El atributo ServiceBusAccount aplicado a la clase.The ServiceBusAccount attribute applied to the class.
  • La configuración de aplicación "AzureWebJobsServiceBus".The "AzureWebJobsServiceBus" app setting.

Desencadenador: configuraciónTrigger - configuration

En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json y el atributo ServiceBusTrigger.The following table explains the binding configuration properties that you set in the function.json file and the ServiceBusTrigger attribute.

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DESCRIPCIÓNDescription
typetype N/Dn/a Debe establecerse en "serviceBusTrigger".Must be set to "serviceBusTrigger". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
directiondirection N/Dn/a Debe establecerse en "in".Must be set to "in". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
namename N/Dn/a Nombre de la variable que representa el mensaje de cola o tema en el código de la función.The name of the variable that represents the queue or topic message in function code. Se establece en "$return" para hacer referencia al valor devuelto de la función.Set to "$return" to reference the function return value.
queueNamequeueName QueueNameQueueName Nombre de la cola que se debe supervisar.Name of the queue to monitor. Se establece únicamente si se supervisa una cola, no un tema.Set only if monitoring a queue, not for a topic.
topicNametopicName TopicNameTopicName Nombre del tema que se debe supervisar.Name of the topic to monitor. Se establece únicamente si se supervisa un tema, no una cola.Set only if monitoring a topic, not for a queue.
subscriptionNamesubscriptionName SubscriptionNameSubscriptionName Nombre de la suscripción que se debe supervisar.Name of the subscription to monitor. Se establece únicamente si se supervisa un tema, no una cola.Set only if monitoring a topic, not for a queue.
conexiónconnection ConnectionConnection Nombre de una configuración de aplicación que contiene la cadena de conexión de Service Bus que se usará para este enlace.The name of an app setting that contains the Service Bus connection string to use for this binding. Si el nombre de la configuración de aplicación comienza con "AzureWebJobs", puede especificar solo el resto del nombre.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. Por ejemplo, si establece connection en "MyServiceBus", el entorno de ejecución de Functions busca una configuración de aplicación denominada "AzureWebJobsMyServiceBus".For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "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".If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

Para obtener la cadena de conexión, siga los pasos mostrados en Obtención de las credenciales de administración.To obtain a connection string, follow the steps shown at Get the management credentials. 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.The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRightsaccessRights AccederAccess Derechos de acceso para la cadena de conexión.Access rights for the connection string. Los valores disponibles son manage y listen.Available values are manage and listen. El valor predeterminado es manage, lo que indica que connection tiene el permiso Administrar.The default is manage, which indicates that the connection has the Manage permission. Si usa una cadena de conexión que no tiene el permiso Administrar, establezca accessRights en "listen".If you use a connection string that does not have the Manage permission, set accessRights to "listen". De lo contrario, el runtime de Functions puede intentar realizar operaciones que requieran derechos de administración y no conseguirlo.Otherwise, the Functions runtime might fail trying to do operations that require manage rights. En la versión 2.x de Azure Functions, esta propiedad no está disponible porque la versión más reciente del SDK de Storage no admite las operaciones de administración.In Azure Functions version 2.x, this property is not available because the latest version of the Storage SDK doesn't support manage operations.

Cuando desarrolla localmente, la configuración de aplicación pasa al archivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Desencadenador: usoTrigger - usage

En C# y el script de C#, puede usar los tipos de parámetros siguientes para el mensaje de cola o tema:In C# and C# script, you can use the following parameter types for the queue or topic message:

  • string: si el mensaje es texto.string - If the message is text.
  • byte[]: útil para datos binarios.byte[] - Useful for binary data.
  • Un tipo personalizado: si el mensaje contiene el archivo JSON, Azure Functions intenta deserializar los datos JSON.A custom type - If the message contains JSON, Azure Functions tries to deserialize the JSON data.
  • BrokeredMessage: proporciona el mensaje deserializado con el método BrokeredMessage.GetBody().BrokeredMessage - Gives you the deserialized message with the BrokeredMessage.GetBody() method.

Estos parámetros son para la versión de Azure Functions 1.x; para 2.x, use Message en lugar de BrokeredMessage.These parameters are for Azure Functions version 1.x; for 2.x, use Message instead of BrokeredMessage.

En JavaScript, puede obtener acceso al mensaje de cola o tema mediante el uso de context.bindings.<name from function.json>.In JavaScript, access the queue or topic message by using context.bindings.<name from function.json>. El mensaje de Service Bus se pasa a la función como una cadena o como un objeto JSON.The Service Bus message is passed into the function as either a string or JSON object.

Desencadenador: mensajes dudososTrigger - poison messages

El control de mensajes dudosos no se puede controlar ni configurar en Azure Functions.Poison message handling can't be controlled or configured in Azure Functions. Service Bus controla este tipo de mensajes.Service Bus handles poison messages itself.

Desencadenador: comportamiento de PeekLockTrigger - PeekLock behavior

El entorno de ejecución de Functions recibe un mensaje en modo PeekLock.The Functions runtime receives a message in PeekLock mode. Llama a Complete en el mensaje si la función finaliza correctamente, o llama a Abandon si se produce un error en la función.It calls Complete on the message if the function finishes successfully, or calls Abandon if the function fails. 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.If the function runs longer than the PeekLock timeout, the lock is automatically renewed as long as the function is running.

El maxAutoRenewDuration se puede configurar en host.json, que se asigna a OnMessageOptions.MaxAutoRenewDuration.The maxAutoRenewDuration is configurable in host.json, which maps to OnMessageOptions.MaxAutoRenewDuration. El valor predeterminado de esta opción es de 5 minutos según la documentación de Service Bus, aunque que puede aumentar el límite de tiempo de Functions desde el valor predeterminado de 5 minutos a 10 minutos.The maximum allowed for this setting is 5 minutes according to the Service Bus documentation, whereas you can increase the Functions time limit from the default of 5 minutes to 10 minutes. Sin embargo puede que no quiera hacer eso con las funciones de Service Bus, ya que podría superar el límite de renovación de este.For Service Bus functions you wouldn’t want to do that then, because you’d exceed the Service Bus renewal limit.

Desencadenador: metadatos del mensajeTrigger - message metadata

El desencadenador de Service Bus proporciona varias propiedades de metadatos.The Service Bus trigger provides several metadata properties. Estas propiedades pueden usarse como parte de expresiones de enlace en otros enlaces o como parámetros del código.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Estas son propiedades de la clase BrokeredMessage.These are properties of the BrokeredMessage class.

PropiedadProperty EscribaType DESCRIPCIÓNDescription
DeliveryCount Int32 Número total de entregas.The number of deliveries.
DeadLetterSource string Origen de los mensajes fallidos.The dead letter source.
ExpiresAtUtc DateTime Hora de expiración en UTC.The expiration time in UTC.
EnqueuedTimeUtc DateTime Hora de puesta en la cola en UTC.The enqueued time in UTC.
MessageId string Se trata de un valor definido por el usuario que Service Bus puede utilizar para identificar mensajes duplicados, si está habilitado.A user-defined value that Service Bus can use to identify duplicate messages, if enabled.
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.A content type identifier utilized by the sender and receiver for application specific logic.
ReplyTo string La respuesta a la dirección de cola.The reply to queue address.
SequenceNumber Int64 El número único que Service Bus asigna a un mensaje.The unique number assigned to a message by the Service Bus.
To string Dirección de envío.The send to address.
Label string Etiqueta específica de la aplicación.The application specific label.
CorrelationId string Identificador de correlación.The correlation ID.

Nota

Actualmente, el desencadenador de bus de servicio que funciona con las suscripciones y colas de la sesión habilitada está en versión preliminar.Currently, Service bus trigger that works with session enabled queues and subscriptions is in preview. Realiza un seguimiento de este elemento para las actualizaciones con respecto a esto.Please track this item for any further updates regarding this.

Consulte los ejemplos de código que utilizan estas propiedades más arriba en este artículo.See code examples that use these properties earlier in this article.

Desencadenador: propiedades de host.jsonTrigger - host.json properties

El archivo host.json contiene opciones de configuración que controlan el comportamiento de desencadenador de Service Bus.The host.json file contains settings that control Service Bus trigger behavior.

{
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "maxAutoRenewDuration": "00:05:00"
    }
}
PropiedadProperty Valor predeterminadoDefault DESCRIPCIÓNDescription
maxConcurrentCallsmaxConcurrentCalls 1616 Número máximo de llamadas simultáneas a la devolución de llamada que el bombeo de mensajes debe iniciar.The maximum number of concurrent calls to the callback that the message pump should initiate. De forma predeterminada, el entorno de ejecución de Functions procesa simultáneamente varios mensajes.By default, the Functions runtime processes multiple messages concurrently. Para indicar al entorno de ejecución que procese solo los mensajes de una única cola o tema, establezca maxConcurrentCalls en 1.To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1.
prefetchCountprefetchCount N/Dn/a Valor predeterminado de PrefetchCount que utilizará el receptor de mensajes subyacente.The default PrefetchCount that will be used by the underlying MessageReceiver.
maxAutoRenewDurationmaxAutoRenewDuration 00:05:0000:05:00 Duración máxima dentro de la cual el bloqueo de mensajes se renovará automáticamente.The maximum duration within which the message lock will be renewed automatically.

SalidaOutput

Use el enlace de salida de Azure Service Bus para enviar mensajes de cola o tema.Use Azure Service Bus output binding to send queue or topic messages.

Salida: ejemploOutput - example

Vea el ejemplo específico del lenguaje:See the language-specific example:

Salida: ejemplo de C#Output - C# example

En el ejemplo siguiente se muestra una función de C# que envía un mensaje de cola de Service Bus:The following example shows a C# function that sends a Service Bus queue message:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string ServiceBusOutput([HttpTrigger] dynamic input, ILogger log)
{
    log.LogInformation($"C# function processed: {input.Text}");
    return input.Text;
}

Salida: ejemplo de script de C#Output - C# script example

En el ejemplo siguiente se muestra un enlace de salida de Service Bus en un archivo function.json y una función de script de C# que usa el enlace.The following example shows a Service Bus output binding in a function.json file and a C# script function that uses the binding. La función usa un desencadenador de temporizador para enviar un mensaje de cola cada 15 segundos.The function uses a timer trigger to send a queue message every 15 seconds.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Este es el código de script de C# que crea un único mensaje:Here's C# script code that creates a single message:

public static void Run(TimerInfo myTimer, ILogger log, out string outputSbQueue)
{
    string message = $"Service Bus queue message created at: {DateTime.Now}";
    log.LogInformation(message); 
    outputSbQueue = message;
}

Este es el código de script de C# que crea varios mensajes:Here's C# script code that creates multiple messages:

public static void Run(TimerInfo myTimer, ILogger log, ICollector<string> outputSbQueue)
{
    string message = $"Service Bus queue messages created at: {DateTime.Now}";
    log.LogInformation(message); 
    outputSbQueue.Add("1 " + message);
    outputSbQueue.Add("2 " + message);
}

Salida: ejemplo de F#Output - F# example

En el ejemplo siguiente se muestra un enlace de salida de Service Bus en un archivo function.json y una función de script de F# que usa el enlace.The following example shows a Service Bus output binding in a function.json file and an F# script function that uses the binding. La función usa un desencadenador de temporizador para enviar un mensaje de cola cada 15 segundos.The function uses a timer trigger to send a queue message every 15 seconds.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Este es el código de script de F# que crea un único mensaje:Here's F# script code that creates a single message:

let Run(myTimer: TimerInfo, log: ILogger, outputSbQueue: byref<string>) =
    let message = sprintf "Service Bus queue message created at: %s" (DateTime.Now.ToString())
    log.LogInformation(message)
    outputSbQueue = message

Salida: ejemplo de JavaOutput - Java example

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.The following example shows a Java function that sends a message to a Service Bus queue myqueue when triggered by a HTTP request.

@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.In the Java functions runtime library, use the @QueueOutput annotation on function parameters whose value would be written to a Service Bus queue. El parámetro type debe ser OutputBinding<T>, donde T es cualquier tipo nativo de Java de un POJO.The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

También pueden escribir funciones de Java a un tema de Service Bus.Java functions can also write to a Service Bus topic. En el ejemplo siguiente se usa el @ServiceBusTopicOutput anotación para describir la configuración para el enlace de salida.The following example uses the @ServiceBusTopicOutput annotation to describe the configuration for the output binding.

@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();
        
    }

Salida: ejemplo de JavaScriptOutput - JavaScript example

En el ejemplo siguiente se muestra un enlace de salida de Service Bus en un archivo function.json y una función de JavaScript que usa el enlace.The following example shows a Service Bus output binding in a function.json file and a JavaScript function that uses the binding. La función usa un desencadenador de temporizador para enviar un mensaje de cola cada 15 segundos.The function uses a timer trigger to send a queue message every 15 seconds.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Este es el código de script de JavaScript que crea un único mensaje:Here's JavaScript script code that creates a single message:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = message;
    context.done();
};

Este es el código de script de JavaScript que crea varios mensajes:Here's JavaScript script code that creates multiple messages:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = [];
    context.bindings.outputSbQueue.push("1 " + message);
    context.bindings.outputSbQueue.push("2 " + message);
    context.done();
};

Salida: atributosOutput - attributes

En las bibliotecas de clases de C#, use el atributo ServiceBusAttribute.In C# class libraries, use the ServiceBusAttribute.

El constructor del atributo toma el nombre de la cola o del tema y la suscripción.The attribute's constructor takes the name of the queue or the topic and subscription. También puede especificar los derechos de acceso de la conexión.You can also specify the connection's access rights. En la sección Salida: configuración se explica cómo elegir la configuración de derechos de acceso.How to choose the access rights setting is explained in the Output - configuration section. Este es un ejemplo que muestra el atributo aplicado al valor devuelto de la función:Here's an example that shows the attribute applied to the return value of the function:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

Puede establecer la propiedad Connection para especificar la cuenta de Service Bus que se usará, tal como se muestra en el ejemplo siguiente:You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

Para obtener un ejemplo completo, consulte Salida: ejemplo de C#.For a complete example, see Output - C# example.

Puede usar el atributo ServiceBusAccount para especificar la cuenta de Service Bus en el nivel de clase, método o parámetro.You can use the ServiceBusAccount attribute to specify the Service Bus account to use at class, method, or parameter level. Para obtener más información, consulte Desencadenador: atributos.For more information, see Trigger - attributes.

Salida: configuraciónOutput - configuration

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.The following table explains the binding configuration properties that you set in the function.json file and the ServiceBus attribute.

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DESCRIPCIÓNDescription
typetype N/Dn/a Debe establecerse en "serviceBus".Must be set to "serviceBus". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
directiondirection N/Dn/a Debe establecerse en "out".Must be set to "out". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
namename N/Dn/a Nombre de la variable que representa la cola o el tema en el código de la función.The name of the variable that represents the queue or topic in function code. Se establece en "$return" para hacer referencia al valor devuelto de la función.Set to "$return" to reference the function return value.
queueNamequeueName QueueNameQueueName Nombre de la cola.Name of the queue. Se establece únicamente si se envían mensajes de cola, no de tema.Set only if sending queue messages, not for a topic.
topicNametopicName TopicNameTopicName Nombre del tema que se debe supervisar.Name of the topic to monitor. Se establece únicamente si se envían mensajes de tema, no de cola.Set only if sending topic messages, not for a queue.
conexiónconnection ConnectionConnection Nombre de una configuración de aplicación que contiene la cadena de conexión de Service Bus que se usará para este enlace.The name of an app setting that contains the Service Bus connection string to use for this binding. Si el nombre de la configuración de aplicación comienza con "AzureWebJobs", puede especificar solo el resto del nombre.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. Por ejemplo, si establece connection en "MyServiceBus", el entorno de ejecución de Functions busca una configuración de aplicación denominada "AzureWebJobsMyServiceBus".For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "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".If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

Para obtener la cadena de conexión, siga los pasos mostrados en Obtención de las credenciales de administración.To obtain a connection string, follow the steps shown at Get the management credentials. 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.The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRightsaccessRights AccederAccess Derechos de acceso para la cadena de conexión.Access rights for the connection string. Los valores disponibles son manage y listen.Available values are manage and listen. El valor predeterminado es manage, lo que indica que connection tiene el permiso Administrar.The default is manage, which indicates that the connection has the Manage permission. Si usa una cadena de conexión que no tiene el permiso Administrar, establezca accessRights en "listen".If you use a connection string that does not have the Manage permission, set accessRights to "listen". De lo contrario, el runtime de Functions puede intentar realizar operaciones que requieran derechos de administración y no conseguirlo.Otherwise, the Functions runtime might fail trying to do operations that require manage rights. En la versión 2.x de Azure Functions, esta propiedad no está disponible porque la versión más reciente del SDK de Storage no admite las operaciones de administración.In Azure Functions version 2.x, this property is not available because the latest version of the Storage SDK doesn't support manage operations.

Cuando desarrolla localmente, la configuración de aplicación pasa al archivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Uso de salidasOutput - usage

En Azure Functions 1.x, el entorno de ejecución crea la cola si no existe y se estableció accessRights en manage.In Azure Functions 1.x, the runtime creates the queue if it doesn't exist and you have set accessRights to manage. En la versión 2.x de Functions, ya debe existir la cola o el tema. Si especifica una cola o un tema que no existe, la función generará un error.In Functions version 2.x, the queue or topic must already exist; if you specify a queue or topic that doesn't exist, the function will fail.

En C# y el script de C#, puede usar los tipos de parámetros siguientes para el enlace de salida:In C# and C# script, you can use the following parameter types for the output binding:

  • out T paramName - T puede ser cualquier tipo que se pueda serializar con JSON.out T paramName - T can be any JSON-serializable type. Si el valor del parámetro es null cuando finaliza la función, Functions crea el mensaje con un objeto null.If the parameter value is null when the function exits, Functions creates the message with a null object.
  • out string: si el valor del parámetro es null cuando finaliza la función, Functions no crea ningún mensaje.out string - If the parameter value is null when the function exits, Functions does not create a message.
  • out byte[]: si el valor del parámetro es null cuando finaliza la función, Functions no crea ningún mensaje.out byte[] - If the parameter value is null when the function exits, Functions does not create a message.
  • out BrokeredMessage: si el valor del parámetro es null cuando finaliza la función, Functions no crea ningún mensaje.out BrokeredMessage - If the parameter value is null when the function exits, Functions does not create a message.
  • ICollector<T> o IAsyncCollector<T>: para crear varios mensajes.ICollector<T> or IAsyncCollector<T> - For creating multiple messages. Se crea un mensaje al llamar al método Add .A message is created when you call the Add method.

En las funciones asincrónicas, use el valor devuelto o IAsyncCollector en lugar de un parámetro out.In async functions, use the return value or IAsyncCollector instead of an out parameter.

Estos parámetros son para la versión de Azure Functions 1.x; para 2.x, use Message en lugar de BrokeredMessage.These parameters are for Azure Functions version 1.x; for 2.x, use Message instead of BrokeredMessage.

En JavaScript, puede obtener acceso a la cola o al tema mediante el uso de context.bindings.<name from function.json>.In JavaScript, access the queue or topic by using context.bindings.<name from function.json>. Puede asignar una cadena, una matriz de bytes o un objeto de JavaScript (deserializado en JSON) a context.binding.<name>.You can assign a string, a byte array, or a Javascript object (deserialized into JSON) to context.binding.<name>.

Excepciones y códigos de retornoExceptions and return codes

EnlaceBinding ReferenciaReference
Azure Service BusService Bus Códigos de error de Service BusService Bus Error Codes
Azure Service BusService Bus Límites de Service BusService Bus Limits

configuración de host.jsonhost.json settings

En esta sección se describen las opciones de configuración globales disponibles para este enlace en la versión 2.x.This section describes the global configuration settings available for this binding in version 2.x. El siguiente archivo host.json de ejemplo contiene solo la configuración de la versión 2.x para este enlace.The example host.json file below contains only the version 2.x settings for this binding. Para obtener más información acerca de las opciones de configuración globales de la versión 2.x, consulte la referencia de host.json para Azure Functions, versión 2.x.For more information about global configuration settings in version 2.x, see host.json reference for Azure Functions version 2.x.

Nota

Para obtener una referencia de host.json en Functions 1.x, consulte la referencia de host.json para Azure Functions, versión 1.x.For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "prefetchCount": 100,
            "messageHandlerOptions": {
                "autoComplete": false,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:55:00"
            }
        }
    }
}
PropiedadProperty Valor predeterminadoDefault DESCRIPCIÓNDescription
maxAutoRenewDurationmaxAutoRenewDuration 00:05:0000:05:00 Duración máxima dentro de la cual el bloqueo de mensajes se renovará automáticamente.The maximum duration within which the message lock will be renewed automatically.
autoCompleteautoComplete truetrue Si el desencadenador debe marcar inmediatamente como completado (autocompletar) o esperar a que se complete el procesamiento de la llamada.Whether the trigger should immediately mark as complete (autocomplete) or wait for processing to call complete.
maxConcurrentCallsmaxConcurrentCalls 1616 Número máximo de llamadas simultáneas a la devolución de llamada que el bombeo de mensajes debe iniciar.The maximum number of concurrent calls to the callback that the message pump should initiate. De forma predeterminada, el entorno de ejecución de Functions procesa simultáneamente varios mensajes.By default, the Functions runtime processes multiple messages concurrently. Para indicar al entorno de ejecución que procese solo los mensajes de una única cola o tema, establezca maxConcurrentCalls en 1.To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1.
prefetchCountprefetchCount N/Dn/a Valor predeterminado de PrefetchCount que utilizará el receptor de mensajes subyacente.The default PrefetchCount that will be used by the underlying MessageReceiver.

Pasos siguientesNext steps