Class: ServiceBusService

ServiceBusService

The ServiceBusServices allows you to work with Windows Azure Service Bus. Service Bus provides both queues for sending and receiving messages, as well as push notifications for mobile devices.

Service Bus queues provide both standard message queue functionality as well as publish/subscribe functioanlity. For more information on Service Bus queues, as well as task focused information on using them from Node.js applications, see How to Use Service Bus Queues and How to Use Service Bus Topics/Subscriptions.

Service Bus provides push notifications through the Notification Hub. While the ServiceBusService can be used to manage Notification Hubs, you must use the NotificationHubService to send messages to mobile devices.

new ServiceBusService(configOrNamespaceOrConnectionString, accessKey, issuer, acsNamespace, host, authenticationProvider)

Creates a new ServiceBusService object.

The azure module will read the environment variables AZURE_SERVICEBUS_NAMESPACE and AZURE_SERVICEBUS_ACCESS_KEY for information required to connect to your Windows Azure Service Bus. If these environment variables are not set, you must specify the account information when creating a ServiceBusService object.

Parameters:
Name Type Argument Description
configOrNamespaceOrConnectionString string <optional>

The service bus namespace or the connection string.

accessKey string <optional>

The password. Only necessary if no connection string passed.

issuer string <optional>

The issuer.

acsNamespace string <optional>

The acs namespace. Usually the same as the sb namespace with "-sb" suffix.

host string <optional>

The host address.

authenticationProvider object <optional>

The authentication provider.

Source:

Extends

  • ServiceClient

Methods

createNotificationHub(hubPath, options, callback) → {undefined}

Creates a notification hub.

Parameters:
Name Type Argument Description
hubPath string

A string object that represents the name of the notification hub.

options object <optional>

The request options or callback function.

Properties
Name Type Argument Description
wns object <optional>

An object with the key value pairs for the WNS credentials.

apns object <optional>

An object with the key value pairs for the APNS credentials.

gcm object <optional>

An object with the key value pairs for the GCM credentials.

mpns object <optional>

An object with the key value pairs for the MPNS credentials.

callback function

error will contain information if an error occurs; otherwise result will contain the new notification hub information. response will contain information related to this operation.

Source:
Returns:
Type
undefined
Example
var azure = require('azure');
var serviceBusService = azure.createServiceBusService();
serviceBusService.createNotificationHub('hubName', function (error) {
  if (!error) {
    // Notification hub created successfully
  }
});

createQueue(queuePath, options, callback) → {undefined}

Creates a queue.

Parameters:
Name Type Argument Description
queuePath string

A string object that represents the name of the queue to delete.

options object <optional>

The request options.

Properties
Name Type Argument Description
MaxSizeInMegaBytes int <optional>

Specifies the maximum queue size in megabytes. Any attempt to enqueue a message that will cause the queue to exceed this value will fail.

DefaultMessageTimeToLive PTnHnMnS <optional>

Depending on whether DeadLettering is enabled, a message is automatically moved to the DeadLetterQueue or deleted if it has been stored in the queue for longer than the specified time. This value is overwritten by a TTL specified on the message if and only if the message TTL is smaller than the TTL set on the queue. This value is immutable after the Queue has been created.

LockDuration PTnHnMnS <optional>

Determines the amount of time in seconds in which a message should be locked for processing by a receiver. After this period, the message is unlocked and available for consumption by the next receiver. Settable only at queue creation time.

RequiresSession bool <optional>

Settable only at queue creation time. If set to true, the queue will be session-aware and only SessionReceiver will be supported. Session-aware queues are not supported through REST.

RequiresDuplicateDetection bool <optional>

Settable only at queue creation time.

DeadLetteringOnMessageExpiration bool <optional>

This field controls how the Service Bus handles a message whose TTL has expired. If it is enabled and a message expires, the Service Bus moves the message from the queue into the queue’s dead-letter sub-queue. If disabled, message will be permanently deleted from the queue. Settable only at queue creation time.

DuplicateDetectionHistoryTimeWindow bool <optional>

Specifies the time span during which the Service Bus detects message duplication.

callback function

error will contain information if an error occurs; otherwise createqueueresult will contain the new queue information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

createQueueIfNotExists(queuePath, options, callback) → {undefined}

Creates a queue if it doesn't already exists.

Parameters:
Name Type Argument Description
queuePath string

A string object that represents the name of the queue to delete.

options object <optional>

The request options.

Properties
Name Type Argument Description
MaxSizeInMegaBytes int <optional>

Specifies the maximum queue size in megabytes. Any attempt to enqueue a message that will cause the queue to exceed this value will fail.

DefaultMessageTimeToLive PTnHnMnS <optional>

Depending on whether DeadLettering is enabled, a message is automatically moved to the DeadLetterQueue or deleted if it has been stored in the queue for longer than the specified time. This value is overwritten by a TTL specified on the message if and only if the message TTL is smaller than the TTL set on the queue. This value is immutable after the Queue has been created.

LockDuration PTnHnMnS <optional>

Determines the amount of time in seconds in which a message should be locked for processing by a receiver. After this period, the message is unlocked and available for consumption by the next receiver. Settable only at queue creation time.

RequiresSession bool <optional>

Settable only at queue creation time. If set to true, the queue will be session-aware and only SessionReceiver will be supported. Session-aware queues are not supported through REST.

RequiresDuplicateDetection bool <optional>

Settable only at queue creation time.

DeadLetteringOnMessageExpiration bool <optional>

This field controls how the Service Bus handles a message whose TTL has expired. If it is enabled and a message expires, the Service Bus moves the message from the queue into the queue’s dead-letter sub-queue. If disabled, message will be permanently deleted from the queue. Settable only at queue creation time.

DuplicateDetectionHistoryTimeWindow bool <optional>

Specifies the time span during which the Service Bus detects message duplication.

callback function

error will contain information if an error occurs; otherwise queueCreated will contain the new queue information. response will contain information related to this operation.

Source:
Returns:
Type
undefined
Example
var azure = require('azure');
var serviceBusService = azure.createServiceBusService();
serviceBusService.createQueueIfNotExists('taskqueue', function(error) {
  if(!error) {
    // Queue created or exists
  }
}); 

createRule(topicPath, subscriptionPath, rulePath, options, callback) → {undefined}

Creates a rule.

Parameters:
Name Type Argument Description
topicPath string

A string object that represents the name of the topic for the subscription.

subscriptionPath string

A string object that represents the name of the subscription for which the rule will be created.

rulePath string

A string object that represents the name of the rule to be created.

options object <optional>

The request options.

Properties
Name Type Argument Description
trueFilter string <optional>

Defines the expression that the rule evaluates as a true filter.

falseFilter string <optional>

Defines the expression that the rule evaluates as a false filter.

sqlExpressionFilter string <optional>

Defines the expression that the rule evaluates. The expression string is interpreted as a SQL92 expression which must evaluate to True or False. Only one between a correlation and a sql expression can be defined.

correlationIdFilter string <optional>

Defines the expression that the rule evaluates. Only the messages whose CorrelationId match the CorrelationId set in the filter expression are allowed. Only one between a correlation and a sql expression can be defined.

sqlRuleAction string <optional>

Defines the expression that the rule evaluates. If the rule is of type SQL, the expression string is interpreted as a SQL92 expression which must evaluate to True or False. If the rule is of type CorrelationFilterExpression then only the messages whose CorrelationId match the CorrelationId set in the filter expression are allowed.

callback function

error will contain information if an error occurs; otherwise createruleresults will contain the new rule information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

createSubscription(topicPath, subscriptionPath, options, callback) → {undefined}

Creates a subscription.

Parameters:
Name Type Argument Description
topicPath string

A string object that represents the name of the topic for the subscription.

subscriptionPath string

A string object that represents the name of the subscription.

options object <optional>

The request options.

Properties
Name Type Argument Description
LockDuration PTnHnMnS <optional>

The default lock duration is applied to subscriptions that do not define a lock duration. Settable only at subscription creation time.

RequiresSession bool <optional>

Settable only at subscription creation time. If set to true, the subscription will be session-aware and only SessionReceiver will be supported. Session-aware subscription are not supported through REST.

DefaultMessageTimeToLive PTnHnMnS <optional>

Determines how long a message lives in the subscription. Based on whether dead-lettering is enabled, a message whose TTL has expired will either be moved to the subscription’s associated DeadLtterQueue or permanently deleted.

EnableDeadLetteringOnMessageExpiration bool <optional>

This field controls how the Service Bus handles a message whose TTL has expired. If it is enabled and a message expires, the Service Bus moves the message from the queue into the subscription’s dead-letter sub-queue. If disabled, message will be permanently deleted from the subscription’s main queue. Settable only at subscription creation time.

EnableDeadLetteringOnFilterEvaluationExceptions bool <optional>

Determines how the Service Bus handles a message that causes an exception during a subscription’s filter evaluation. If the value is set to true, the message that caused the exception will be moved to the subscription’s dead-letter queue. Otherwise, it will be discarded. By default this parameter is set to true, allowing the user a chance to investigate the cause of the exception. It can occur from a malformed message or some incorrect assumptions being made in the filter about the form of the message. Settable only at topic creation time.

callback function

error will contain information if an error occurs; otherwise createsubscriptionresult will contain the new subscription information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

createTopic(topic, options, callback) → {undefined}

Creates a topic.

Parameters:
Name Type Argument Description
topic TopicInfo

A Topic object that represents the topic to create.

options object <optional>

The request options.

Properties
Name Type Argument Description
MaxSizeInMegabytes int <optional>

Specifies the maximum topic size in megabytes. Any attempt to enqueue a message that will cause the topic to exceed this value will fail. All messages that are stored in the topic or any of its subscriptions count towards this value. Multiple copies of a message that reside in one or multiple subscriptions count as a single messages. For example, if message m exists once in subscription s1 and twice in subscription s2, m is counted as a single message.

DefaultMessageTimeToLive PTnHnMnS <optional>

Determines how long a message lives in the associated subscriptions. Subscriptions inherit the TTL from the topic unless they are created explicitly with a smaller TTL. Based on whether dead-lettering is enabled, a message whose TTL has expired will either be moved to the subscription’s associated DeadLtterQueue or will be permanently deleted.

RequiresDuplicateDetection bool <optional>

If enabled, the topic will detect duplicate messages within the time span specified by the DuplicateDetectionHistoryTimeWindow property. Settable only at topic creation time.

DuplicateDetectionHistoryTimeWindow PTnHnMnS <optional>

Specifies the time span during which the Service Bus will detect message duplication.

EnableBatchedOperations bool <optional>

Specifies if batched operations should be allowed.

SizeInBytes int <optional>

Specifies the topic size in bytes.

callback function

error will contain information if an error occurs; otherwise createtopicresult will contain the new topic information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

createTopicIfNotExists(topic, options, callback) → {undefined}

Creates a topic if it doesn't exists.

Parameters:
Name Type Argument Description
topic TopicInfo

A Topic object that represents the topic to create.

options object <optional>

The request options.

Properties
Name Type Argument Description
MaxSizeInMegabytes int <optional>

Specifies the maximum topic size in megabytes. Any attempt to enqueue a message that will cause the topic to exceed this value will fail. All messages that are stored in the topic or any of its subscriptions count towards this value. Multiple copies of a message that reside in one or multiple subscriptions count as a single messages. For example, if message m exists once in subscription s1 and twice in subscription s2, m is counted as a single message.

DefaultMessageTimeToLive PTnHnMnS <optional>

Determines how long a message lives in the associated subscriptions. Subscriptions inherit the TTL from the topic unless they are created explicitly with a smaller TTL. Based on whether dead-lettering is enabled, a message whose TTL has expired will either be moved to the subscription’s associated DeadLtterQueue or will be permanently deleted.

RequiresDuplicateDetection bool <optional>

If enabled, the topic will detect duplicate messages within the time span specified by the DuplicateDetectionHistoryTimeWindow property. Settable only at topic creation time.

DuplicateDetectionHistoryTimeWindow PTnHnMnS <optional>

Specifies the time span during which the Service Bus will detect message duplication.

MaxSubscriptionsPerTopic int <optional>

Specifies the maximum number of subscriptions that can be associated with the topic.

MaxSqlFiltersPerTopic int <optional>

Specifies the maximum number of SQL filter expressions (in total) that can be added to the subscriptions associated with the topic.

MaxCorrelationFiltersPerTopic int <optional>

Specifies the maximum number of correlation filter expressions (in total) that can be added to the subscriptions associated with the topic.

EnableDeadLetteringOnMessageExpiration bool <optional>

Settable only at topic creation time.

EnableDeadLetteringOnFilterEvaluationExceptions bool <optional>

Settable only at topic creation time.

callback function

error will contain information if an error occurs; otherwise topicCreated will contain the new topic information. response will contain information related to this operation.

Source:
Returns:
Type
undefined
Example
var azure = require('azure');
var serviceBusService = azure.createServiceBusService();
serviceBusService.createTopicIfNotExists('taskdiscussion', function(error) {
  if(!error) {
    // Topic exists
  }
});

deleteMessage(message, callback) → {undefined}

Deletes a message.

Parameters:
Name Type Description
message object | string

The message object or a string with the message location.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined

deleteNotificationHub(hubPath, callback) → {undefined}

Deletes a notification hub.

Parameters:
Name Type Description
hubPath string

A string object that represents the name of the notification hub.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined

deleteQueue(queuePath, callback) → {undefined}

Deletes a queue.

Parameters:
Name Type Description
queuePath string

A string object that represents the name of the queue to delete.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined

deleteRule(topicPath, subscriptionPath, rulePath, callback) → {undefined}

Deletes a rule.

Parameters:
Name Type Description
topicPath string

A string object that represents the name of the topic for the subscription.

subscriptionPath string

A string object that represents the name of the subscription for which the rule will be deleted.

rulePath string

A string object that represents the name of the rule to delete.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined

deleteSubscription(topicPath, subscriptionPath, callback) → {undefined}

Deletes a subscription.

Parameters:
Name Type Description
topicPath string

A string object that represents the name of the topic for the subscription.

subscriptionPath string

A string object that represents the name of the subscription to delete.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined

deleteTopic(topicPath, callback) → {undefined}

Deletes a topic.

Parameters:
Name Type Description
topicPath string

A String object that represents the name of the queue to delete.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined

getNotificationHub(hubPath, callback) → {undefined}

Gets a notification hub.

Parameters:
Name Type Description
hubPath string

A string object that represents the name of the notification hub.

callback function

error will contain information if an error occurs; otherwise result will contain the notification hub information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

getQueue(queuePath, callback) → {undefined}

Retrieves a queue.

Parameters:
Name Type Description
queuePath string

A string object that represents the name of the queue to retrieve.

callback function

error will contain information if an error occurs; otherwise queueresult will contain the queue information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

getRule(topicPath, subscriptionPath, rulePath, callback) → {undefined}

Retrieves a rule.

Parameters:
Name Type Description
topicPath string

A string object that represents the name of the topic for the subscription.

subscriptionPath string

A string object that represents the name of the subscription for which the rule will be retrieved.

rulePath string

A string object that represents the name of the rule to retrieve.

callback function

error will contain information if an error occurs; otherwise getruleresult will contain the rule information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

getSubscription(topicPath, subscriptionPath, callback) → {undefined}

Retrieves a subscription.

Parameters:
Name Type Description
topicPath string

A string object that represents the name of the topic for the subscription.

subscriptionPath string

A string object that represents the name of the subscription to retrieve.

callback function

error will contain information if an error occurs; otherwise getsubscriptionresult will contain the subscription information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

getTopic(topicPath, callback) → {undefined}

Retrieves a topic.

Parameters:
Name Type Description
topicPath string

A String object that represents the name of the topic to retrieve.

callback function

error will contain information if an error occurs; otherwise gettopicresult will contain the topic information. response will contain information related to this operation.

Source:
Returns:
Type
undefined

listNotificationHubs(options, callback) → {undefined}

Returns a list of notification hubs.

Parameters:
Name Type Argument Description
options object <optional>

The request options or callback function.

Properties
Name Type Argument Description
top int <optional>

The number of topics to fetch.

skip int <optional>

The number of topics to skip.

callback function

error will contain information if an error occurs; otherwise result will contain the list of notification hubs. response will contain information related to this operation.

Source:
Returns:
Type
undefined

listQueues(options, callback) → {undefined}

Returns a list of queues.

Parameters:
Name Type Argument Description
options object <optional>

The request options.

Properties
Name Type Argument Description
top int <optional>

The top clause for listing queues.

skip int <optional>

The skip clause for listing queues.

callback function

error will contain information if an error occurs; otherwise listqueueresult will contain the list of queues. response will contain information related to this operation.

Source:
Returns:
Type
undefined

listRules(topicPath, subscriptionPath, options, callback) → {undefined}

Returns a list of rules.

Parameters:
Name Type Argument Description
topicPath string

A string object that represents the name of the topic for the subscription.

subscriptionPath string

A string object that represents the name of the subscription whose rules are being retrieved.

options object <optional>

The request options.

Properties
Name Type Argument Description
top int <optional>

The number of topics to fetch.

skip int <optional>

The number of topics to skip.

callback function

error will contain information if an error occurs; otherwise listrulesresult will contain the list of rules. response will contain information related to this operation.

Source:
Returns:
Type
undefined

listSubscriptions(topicPath, options, callback) → {undefined}

Returns a list of subscriptions.

Parameters:
Name Type Argument Description
topicPath string

A string object that represents the name of the topic for the subscriptions to retrieve.

options object <optional>

The request options.

Properties
Name Type Argument Description
top int <optional>

The number of topics to fetch.

skip int <optional>

The number of topics to skip.

callback function

error will contain information if an error occurs; otherwise listsubscriptionresult will contain the list of subscriptions. response will contain information related to this operation.

Source:
Returns:
Type
undefined

listTopics(options, callback) → {undefined}

Returns a list of topics.

Parameters:
Name Type Argument Description
options object <optional>

The request options.

Properties
Name Type Argument Description
top int <optional>

The number of topics to fetch.

skip int <optional>

The number of topics to skip.

callback function

error will contain information if an error occurs; otherwise listtopicsresult will contain the list of topics. response will contain information related to this operation.

Source:
Returns:
Type
undefined

receiveQueueMessage(queuePath, options, callback) → {undefined}

Receives a queue message.

Parameters:
Name Type Argument Description
queuePath string

A string object that represents the name of the queue to which the message will be sent.

options object <optional>

The request options.

Properties
Name Type Argument Description
isPeekLock bool <optional>

Boolean value indicating if the message should be peeked or received.

timeoutIntervalInS int <optional>

The timeout interval, in seconds, to use for the request.

callback function

error will contain information if an error occurs; otherwise receivequeuemessageresult will contain the message result information. response will contain information related to this operation.

Source:
Returns:
Type
undefined
Example
var azure = require('azure');
var serviceBusService = azure.createServiceBusService();
serviceBusService.receiveQueueMessage('taskqueue', function(error, serverMessage) {
  if(!error) {
    // Process the message
  }
}); 

receiveSubscriptionMessage(topicPath, subscriptionPath, options, callback) → {undefined}

Receives a subscription message.

Parameters:
Name Type Argument Description
topicPath string

A string object that represents the name of the topic to receive.

subscriptionPath string

A string object that represents the name of the subscription from the message will be received.

options object <optional>

The request options.

Properties
Name Type Argument Description
isPeekLock bool <optional>

Boolean value indicating if the message should be peeked or received.

timeoutIntervalInS int <optional>

The timeout interval, in seconds, to use for the request.

callback function

error will contain information if an error occurs; otherwise receivetopicmessageresult will contain the message result information. response will contain information related to this operation.

Source:
Returns:
Type
undefined
Example
var azure = require('azure');
var serviceBusService = azure.createServiceBusService();
var topic = 'taskdiscussion';
var subscription = 'client1';

serviceBusService.createSubscription(topic, subscription, function(error1) {
  if(!error1) {
    // Subscription created
    serviceBusService.receiveSubscriptionMessage(topic, subscription, function(error2, serverMessage) {
      if(!error2) {
        // Process message
      }
    });
  }
}); 

sendQueueMessage(queuePath, message, callback) → {undefined}

Sends a queue message.

Parameters:
Name Type Description
queuePath string

A string object that represents the name of the queue to which the message will be sent.

message object | string

A message object that represents the message to send.

Properties
Name Type Argument Description
body string <optional>

The message's text.

customProperties object <optional>

The message's custom properties.

brokerProperties.CorrelationId string <optional>

The message's correlation identifier.

brokerProperties.SessionId string <optional>

The session identifier.

brokerProperties.MessageId string <optional>

The message's identifier.

brokerProperties.Label string <optional>

The message's lable.

brokerProperties.ReplyTo string <optional>

The message's reply to.

brokerProperties.TimeToLive string <optional>

The message's time to live.

brokerProperties.To string <optional>

The message's to.

brokerProperties.ScheduledEnqueueTimeUtc string <optional>

The message's scheduled enqueue time in UTC.

brokerProperties.ReplyToSessionId string <optional>

The message's reply to session identifier.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined
Example
var azure = require('azure');
var serviceBusService = azure.createServiceBusService();
serviceBusService.sendQueueMessage('taskqueue', 'Hello world!', function(error) {
  if(!error) {
    // Message sent
  }
}); 

sendTopicMessage(topicPath, message, callback) → {undefined}

Sends a topic message.

Parameters:
Name Type Description
topicPath string

A string object that represents the name of the topic to which the message will be sent.

message object | string

A message object that represents the message to send.

Properties
Name Type Argument Description
body string <optional>

The message's text.

customProperties object <optional>

The message's custom properties.

brokerProperties.CorrelationId string <optional>

The message's correlation identifier.

brokerProperties.SessionId string <optional>

The session identifier.

brokerProperties.MessageId string <optional>

The message's identifier.

brokerProperties.Label string <optional>

The message's lable.

brokerProperties.ReplyTo string <optional>

The message's reply to.

brokerProperties.TimeToLive string <optional>

The message's time to live.

brokerProperties.To string <optional>

The message's to.

brokerProperties.ScheduledEnqueueTimeUtc string <optional>

The message's scheduled enqueue time in UTC.

brokerProperties.ReplyToSessionId string <optional>

The message's reply to session identifier.

callback function

error will contain information if an error occurs; otherwise receivetopicmessageresult will contain the message result information. response will contain information related to this operation.

Source:
Returns:
Type
undefined
Example
var azure = require('azure');
var serviceBusService = azure.createServiceBusService();
serviceBusService.sendTopicMessage('taskdiscussion', 'Hello world!', function(error) {
  if(!error) {
    // Message sent
  }
}); 

unlockMessage(message, callback) → {undefined}

Unlocks a message.

Parameters:
Name Type Description
message object | string

The message object or a string with the message location.

callback function

error will contain information if an error occurs; otherwise response will contain information related to this operation.

Source:
Returns:
Type
undefined