title | description | services | documentationcenter | author | manager | keywords | ms.assetid | ms.service | ms.topic | ms.date | ms.author |
---|---|---|---|---|---|---|---|---|---|---|---|
Azure Service Bus bindings for Azure Functions |
Understand how to use Azure Service Bus triggers and bindings in Azure Functions. |
functions |
na |
craigshoemaker |
gwallace |
azure functions, functions, event processing, dynamic compute, serverless architecture |
daedacf0-6546-4355-a65c-50873e74f66b |
azure-functions |
reference |
04/01/2017 |
cshoe |
This article explains how to work with Azure Service Bus bindings in Azure Functions. Azure Functions supports trigger and output bindings for Service Bus queues and topics.
[!INCLUDE intro]
The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.ServiceBus NuGet package, version 2.x.
[!INCLUDE functions-package]
The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.Extensions.ServiceBus NuGet package, version 3.x. Source code for the package is in the azure-webjobs-sdk GitHub repository.
Note
Version 2.x does not create the topic or subscription configured in the ServiceBusTrigger
instance. Version 2.x is based on Microsoft.Azure.ServiceBus and does not handle queue management.
[!INCLUDE functions-package-v2]
Use the Service Bus trigger to respond to messages from a Service Bus queue or topic.
See the language-specific example:
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}");
}
This example is for Azure Functions version 1.x. To make this code work for 2.x:
- omit the access rights parameter
- change the type of the log parameter from
TraceWriter
toILogger
- change
log.Info
tolog.LogInformation
The following example shows a Service Bus trigger binding in a function.json file and a C# script function that uses the binding. The function reads message metadata and logs a Service Bus queue message.
Here's the binding data in the function.json file:
{
"bindings": [
{
"queueName": "testqueue",
"connection": "MyServiceBusConnection",
"name": "myQueueItem",
"type": "serviceBusTrigger",
"direction": "in"
}
],
"disabled": false
}
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}");
}
The following example shows a Service Bus trigger binding in a function.json file and an F# function that uses the binding. The function logs a Service Bus queue message.
Here's the binding data in the function.json file:
{
"bindings": [
{
"queueName": "testqueue",
"connection": "MyServiceBusConnection",
"name": "myQueueItem",
"type": "serviceBusTrigger",
"direction": "in"
}
],
"disabled": false
}
Here's the F# script code:
let Run(myQueueItem: string, log: ILogger) =
log.LogInformation(sprintf "F# ServiceBus queue trigger function processed message: %s" myQueueItem)
The following Java function uses the @ServiceBusQueueTrigger
annotation from the Java functions runtime library to describe the configuration for a Service Bus queue trigger. 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);
}
Java functions can also be triggered when a message is added to a Service Bus topic. 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);
}
The following example shows a Service Bus trigger binding in a function.json file and a JavaScript function that uses the binding. The function reads message metadata and logs a Service Bus queue message.
Here's the binding data in the function.json file:
{
"bindings": [
{
"queueName": "testqueue",
"connection": "MyServiceBusConnection",
"name": "myQueueItem",
"type": "serviceBusTrigger",
"direction": "in"
}
],
"disabled": false
}
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();
};
The following example demonstrates how to read a ServiceBus queue message via a trigger.
A ServiceBus binding is defined in function.json where type is set to serviceBusTrigger
.
{
"scriptFile": "__init__.py",
"bindings": [
{
"name": "msg",
"type": "serviceBusTrigger",
"direction": "in",
"queueName": "inputqueue",
"connection": "AzureServiceBusConnectionString"
}
]
}
The code in _init_.py declares a parameter as func.ServiceBusMessage
which allows you to read the queue message in your function.
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,
})
logging.info(result)
In C# class libraries, use the following attributes to configure a Service Bus trigger:
-
The attribute's constructor takes the name of the queue or the topic and subscription. In Azure Functions version 1.x, you can also specify the connection's access rights. If you don't specify access rights, the default is
Manage
. For more information, see the Trigger - configuration section.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) { ... }
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) { ... }
For a complete example, see Trigger - C# example.
-
Provides another way to specify the Service Bus account to use. The constructor takes the name of an app setting that contains a Service Bus connection string. The attribute can be applied at the parameter, method, or class level. 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) { ... }
The Service Bus account to use is determined in the following order:
- The
ServiceBusTrigger
attribute'sConnection
property. - The
ServiceBusAccount
attribute applied to the same parameter as theServiceBusTrigger
attribute. - The
ServiceBusAccount
attribute applied to the function. - The
ServiceBusAccount
attribute applied to the class. - The "AzureWebJobsServiceBus" app setting.
The following table explains the binding configuration properties that you set in the function.json file and the ServiceBusTrigger
attribute.
function.json property | Attribute property | Description |
---|---|---|
type | n/a | Must be set to "serviceBusTrigger". This property is set automatically when you create the trigger in the Azure portal. |
direction | n/a | Must be set to "in". 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 to monitor. Set only if monitoring a queue, not for a topic. |
topicName | TopicName | Name of the topic to monitor. Set only if monitoring a topic, not for a queue. |
subscriptionName | SubscriptionName | Name of the subscription to monitor. Set only if monitoring a topic, 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 | 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, this property is not available because the latest version of the Storage SDK doesn't support manage operations. |
[!INCLUDE app settings to local.settings.json]
In C# and C# script, you can use the following parameter types for the queue or topic message:
string
- If the message is text.byte[]
- Useful for binary data.- A custom type - If the message contains JSON, Azure Functions tries to deserialize the JSON data.
BrokeredMessage
- Gives you the deserialized message with the BrokeredMessage.GetBody<T>() method.
These parameters are for Azure Functions version 1.x; for 2.x, use Message
instead of BrokeredMessage
.
In JavaScript, access the queue or topic message by using context.bindings.<name from function.json>
. The Service Bus message is passed into the function as either a string or JSON object.
Poison message handling can't be controlled or configured in Azure Functions. Service Bus handles poison messages itself.
The Functions runtime receives a message in PeekLock mode. It calls Complete
on the message if the function finishes successfully, or calls Abandon
if the function fails. If the function runs longer than the PeekLock
timeout, the lock is automatically renewed as long as the function is running.
The maxAutoRenewDuration
is configurable in host.json, which maps to OnMessageOptions.MaxAutoRenewDuration. 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. For Service Bus functions you wouldn’t want to do that then, because you’d exceed the Service Bus renewal limit.
The Service Bus trigger provides several metadata properties. These properties can be used as part of binding expressions in other bindings or as parameters in your code. These are properties of the BrokeredMessage class.
Property | Type | Description |
---|---|---|
DeliveryCount |
Int32 |
The number of deliveries. |
DeadLetterSource |
string |
The dead letter source. |
ExpiresAtUtc |
DateTime |
The expiration time in UTC. |
EnqueuedTimeUtc |
DateTime |
The enqueued time in UTC. |
MessageId |
string |
A user-defined value that Service Bus can use to identify duplicate messages, if enabled. |
ContentType |
string |
A content type identifier utilized by the sender and receiver for application specific logic. |
ReplyTo |
string |
The reply to queue address. |
SequenceNumber |
Int64 |
The unique number assigned to a message by the Service Bus. |
To |
string |
The send to address. |
Label |
string |
The application specific label. |
CorrelationId |
string |
The correlation ID. |
Note
Currently, Service bus trigger that works with session enabled queues and subscriptions is in preview. Please track this item for any further updates regarding this.
See code examples that use these properties earlier in this article.
The host.json file contains settings that control Service Bus trigger behavior.
{
"serviceBus": {
"maxConcurrentCalls": 16,
"prefetchCount": 100,
"maxAutoRenewDuration": "00:05:00"
}
}
Property | Default | Description |
---|---|---|
maxConcurrentCalls | 16 | The maximum number of concurrent calls to the callback that the message pump should initiate. By default, the Functions runtime processes multiple messages concurrently. To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1. |
prefetchCount | n/a | The default PrefetchCount that will be used by the underlying MessageReceiver. |
maxAutoRenewDuration | 00:05:00 | The maximum duration within which the message lock will be renewed automatically. |
Use Azure Service Bus output binding to send queue or topic messages.
See the language-specific example:
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;
}
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 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);
}
The following example shows a Service Bus output binding in a function.json file and an F# 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 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
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;
}
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();
}
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();
};
The following example demonstrates how to write out to a ServiceBus queue in Python.
A ServiceBue 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'
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 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)
{
...
}
For a complete example, see Output - C# 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.
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 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 to monitor. 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 | 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, this property is not available because the latest version of the Storage SDK doesn't support manage operations. |
[!INCLUDE app settings to local.settings.json]
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, the queue or topic must already exist; if you specify a queue or topic that doesn't exist, the function will fail.
In C# and C# script, you can 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)ICollector<T>
orIAsyncCollector<T>
- For creating multiple messages. A message is created when you call theAdd
method.
When working with C# functions:
-
Async functions need a return value or
IAsyncCollector
instead of anout
parameter. -
To access the session ID, bind to a
Message
type and use thesessionId
property.
In 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>
.
To send a message to a session-enabled queue in non-C# languages, use the Azure Service Bus SDK rather than the built-in output binding.
Binding | Reference |
---|---|
Service Bus | Service Bus Error Codes |
Service Bus | Service Bus Limits |
This section describes the global configuration settings available for this binding in version 2.x. The example host.json file below contains only the version 2.x settings for this binding. For more information about global configuration settings in version 2.x, see host.json reference for Azure Functions version 2.x.
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": false,
"maxConcurrentCalls": 32,
"maxAutoRenewDuration": "00:55:00"
}
}
}
}
Property | Default | Description |
---|---|---|
maxAutoRenewDuration | 00:05:00 | The maximum duration within which the message lock will be renewed automatically. |
autoComplete | true | Whether the trigger should immediately mark as complete (autocomplete) or wait for processing to call complete. |
maxConcurrentCalls | 16 | The maximum number of concurrent calls to the callback that the message pump should initiate. By default, the Functions runtime processes multiple messages concurrently. To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1. |
prefetchCount | n/a | The default PrefetchCount that will be used by the underlying MessageReceiver. |
[!div class="nextstepaction"] Learn more about Azure functions triggers and bindings