Skip to content

Latest commit

 

History

History
392 lines (295 loc) · 16.4 KB

functions-bindings-service-bus-output.md

File metadata and controls

392 lines (295 loc) · 16.4 KB
title description author ms.assetid ms.topic ms.date ms.author ms.custom
Azure Service Bus bindings for Azure Functions
Learn to send Azure Service Bus messages from Azure Functions.
craigshoemaker
daedacf0-6546-4355-a65c-50873e74f66b
reference
02/19/2020
cshoe
tracking-python

Azure Service Bus output binding for Azure Functions

Use Azure Service Bus output binding to send queue or topic messages.

For information on setup and configuration details, see the overview.

Example

C#

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

C# Script

The following example shows a Service Bus output binding in a function.json file and a C# script function that uses the binding. The function uses a timer trigger to send a queue message every 15 seconds.

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
}

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

Here's C# script code that creates multiple messages:

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

JavaScript

The following example shows a Service Bus output binding in a function.json file and a JavaScript function that uses the binding. The function uses a timer trigger to send a queue message every 15 seconds.

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
}

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

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

Python

The following example demonstrates how to write out to a Service Bus queue in Python.

A Service Bus binding definition is defined in function.json where type is set to serviceBus.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "msg",
      "queueName": "outqueue"
    }
  ]
}

In _init_.py, you can write out a message to the queue by passing a value to the set method.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Java

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

In the Java functions runtime library, use the @QueueOutput annotation on function parameters whose value would be written to a Service Bus queue. The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

Java functions can also write to a Service Bus topic. 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();
        
    }

Attributes and annotations

C#

In C# class libraries, use the ServiceBusAttribute.

The attribute's constructor takes the name of the queue or the topic and subscription. You can also specify the connection's access rights. How to choose the access rights setting is explained in the Output - configuration section. 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)
{
    ...
}

You can set the Connection property to specify the name of an app setting that contains the Service Bus connection string to use, as shown in the following example:

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

For a complete example, see Output - example.

You can use the ServiceBusAccount attribute to specify the Service Bus account to use at class, method, or parameter level. For more information, see Trigger - attributes.

C# Script

Attributes are not supported by C# Script.

JavaScript

Attributes are not supported by JavaScript.

Python

Attributes are not supported by Python.

Java

The ServiceBusQueueOutput and ServiceBusTopicOutput annotations are available to write a message as a function output. The parameter decorated with these annotations must be declared as an OutputBinding<T> where T is the type corresponding to the message's type.

Configuration

The following table explains the binding configuration properties that you set in the function.json file and the ServiceBus attribute.

function.json property Attribute property Description
type n/a Must be set to "serviceBus". This property is set automatically when you create the trigger in the Azure portal.
direction n/a Must be set to "out". This property is set automatically when you create the trigger in the Azure portal.
name n/a The name of the variable that represents the queue or topic message in function code. Set to "$return" to reference the function return value.
queueName QueueName Name of the queue. Set only if sending queue messages, not for a topic.
topicName TopicName Name of the topic. Set only if sending topic messages, not for a queue.
connection Connection The name of an app setting that contains the Service Bus connection string to use for this binding. If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "AzureWebJobsMyServiceBus". If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

To obtain a connection string, follow the steps shown at Get the management credentials. The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRights (v1 only) Access Access rights for the connection string. Available values are manage and listen. The default is manage, which indicates that the connection has the Manage permission. If you use a connection string that does not have the Manage permission, set accessRights to "listen". Otherwise, the Functions runtime might fail trying to do operations that require manage rights. In Azure Functions version 2.x and higher, this property is not available because the latest version of the Service Bus SDK doesn't support manage operations.

[!INCLUDE app settings to local.settings.json]

Usage

In Azure Functions 1.x, the runtime creates the queue if it doesn't exist and you have set accessRights to manage. In Functions version 2.x and higher, the queue or topic must already exist; if you specify a queue or topic that doesn't exist, the function will fail.

C#

Use the following parameter types for the output binding:

  • out T paramName - T can be any JSON-serializable type. If the parameter value is null when the function exits, Functions creates the message with a null object.
  • out string - If the parameter value is null when the function exits, Functions does not create a message.
  • out byte[] - If the parameter value is null when the function exits, Functions does not create a message.
  • out BrokeredMessage - If the parameter value is null when the function exits, Functions does not create a message (for Functions 1.x)
  • out Message - If the parameter value is null when the function exits, Functions does not create a message (for Functions 2.x and higher)
  • ICollector<T> or IAsyncCollector<T> - For creating multiple messages. A message is created when you call the Add method.

When working with C# functions:

  • Async functions need a return value or IAsyncCollector instead of an out parameter.

  • To access the session ID, bind to a Message type and use the sessionId property.

C# Script

Use the following parameter types for the output binding:

  • out T paramName - T can be any JSON-serializable type. If the parameter value is null when the function exits, Functions creates the message with a null object.
  • out string - If the parameter value is null when the function exits, Functions does not create a message.
  • out byte[] - If the parameter value is null when the function exits, Functions does not create a message.
  • out BrokeredMessage - If the parameter value is null when the function exits, Functions does not create a message (for Functions 1.x)
  • out Message - If the parameter value is null when the function exits, Functions does not create a message (for Functions 2.x and higher)
  • ICollector<T> or IAsyncCollector<T> - For creating multiple messages. A message is created when you call the Add method.

When working with C# functions:

  • Async functions need a return value or IAsyncCollector instead of an out parameter.

  • To access the session ID, bind to a Message type and use the sessionId property.

JavaScript

Access the queue or topic by using context.bindings.<name from function.json>. You can assign a string, a byte array, or a JavaScript object (deserialized into JSON) to context.binding.<name>.

Python

Use the Azure Service Bus SDK rather than the built-in output binding.

Java

Use the Azure Service Bus SDK rather than the built-in output binding.

Exceptions and return codes

Binding Reference
Service Bus Service Bus Error Codes
Service Bus Service Bus Limits

host.json settings

This section describes the global configuration settings available for this binding in versions 2.x and higher. The example host.json file below contains only the settings for this binding. For more information about global configuration settings, see host.json reference for Azure Functions version.

Note

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": true,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:05:00"
            },
            "sessionHandlerOptions": {
                "autoComplete": false,
                "messageWaitTimeout": "00:00:30",
                "maxAutoRenewDuration": "00:55:00",
                "maxConcurrentSessions": 16
            }
        }
    }
}

If you have isSessionsEnabled set to true, the sessionHandlerOptions will be honored. If you have isSessionsEnabled set to false, the messageHandlerOptions will be honored.

Property Default Description
prefetchCount 0 Gets or sets the number of messages that the message receiver can simultaneously request.
maxAutoRenewDuration 00:05:00 The maximum duration within which the message lock will be renewed automatically.
autoComplete true Whether the trigger should automatically call complete after processing, or if the function code will manually call complete.
maxConcurrentCalls 16 The maximum number of concurrent calls to the callback that the message pump should initiate per scaled instance. By default, the Functions runtime processes multiple messages concurrently.
maxConcurrentSessions 2000 The maximum number of sessions that can be handled concurrently per scaled instance.

Next steps