Azure Service Bus is a highly-reliable cloud messaging service from Microsoft
Use the client library for Azure Service Bus in your Node.js application to
Source code | Package (npm) | API Reference Documentation | Product documentation | Samples
Install the Azure Service Bus client library using npm
npm install @azure/service-bus
Prerequisites: You must have an Azure subscription and a Service Bus Namespace to use this package. If you are using this package in a Node.js application, then use Node.js 6.x or higher.
TypeScript users need to have Node type definitions installed:
npm install @types/node
You also need to enable compilerOptions.allowSyntheticDefaultImports
in your tsconfig.json. Note that if you have enabled compilerOptions.esModuleInterop
, allowSyntheticDefaultImports
is enabled by default. See TypeScript's compiler options handbook for more information.
Interaction with Service Bus starts with an instance of the ServiceBusClient class. You can instantiate this class using one of the 3 static methods on it
name-of-service-bus-instance.servicebus.windows.net
.
If you're using an own token provider against AAD, then set the "scopes" for service-bus to be ["https://servicebus.azure.net//user_impersonation"]
to get the appropriate token.name-of-service-bus-instance.servicebus.windows.net
.Once you have initialized the ServiceBusClient class, use the below methods to create client objects for Queues, Topics and Subscriptions to interact with existing Service Bus entities. Please note that the Queues, Topics and Subscriptions should already have been created prior to using this library.
Next, using the client object created in the previous step, create a sender or a receiver based on whether you want to send or receive messages
The following sections provide code snippets that cover some of the common tasks using Azure Service Bus
Once you have created an instance of a QueueClient
or SubscriptionClient
class, create a sender
using the createSender
function. This gives you a sender which you can use to send messages.
You can also use the sendBatch method to send multiple messages using a single call.
const queueClient = serviceBusClient.createQueueClient("my-queue");
const sender = queueClient.createSender();
// Optionally, you can await on `sender.open()` if you want to front load the work of setting
// up the AMQP link to the service. If not called, the `sender` will call `open()` on your behalf
// on the first send operation.
//
// await sender.open()
await sender.send({
body: "my-message-body"
});
await sender.sendBatch([
{ body: "my-message-body-1" },
{ body: "my-message-body-2" },
{ body: "my-message-body-3" }
]);
Once you have created an instance of a QueueClient
or SubscriptionClient
class, create a receiver
using the createReceiver function.
const queueClient = serviceBusClient.createQueueClient("my-queue");
const receiver = queueClient.createReceiver(ReceiveMode.peekLock);
You can use this receiver in one of 3 ways to receive messages:
Use the receiveMessages function which returns a promise that resolves to an array of messages.
const myMessages = await receiver.receiveMessages(10);
Use the registerMessageHandler to set up
message handlers and have it running as long as you
need. When you are done, call receiver.close()
to stop receiving any more messages.
const myMessageHandler = async (message) => {
// your code here
};
const myErrorHandler = (error) => {
console.log(error);
};
receiver.registerMessageHandler(myMessageHandler, myErrorHandler);
Use the getMessageIterator to get an async iterator over messages
for await (let message of receiver.getMessageIterator()) {
// your code here
}
Once you receive a message you can call complete()
, abandon()
, defer()
or deadletter()
on it
based on how you want to settle the message. To learn more, please read Settling Received Messages
To send messages using sessions, you first need to create a session enabled Queue. You can do this
in the Azure portal. Then, use an instance of QueueClient
to create a sender
using the createSender
function. This gives you a sender which you can use to send messages.
When sending the message, set the sessionId
property in the message body to ensure your message
lands in the right session.
const queueClient = serviceBusClient.createQueueClient("my-session-queue");
const sender = queueClient.createSender();
await sender.send({
body: "my-message-body",
sessionId: "my-session"
});
To receive messages from sessions, you first need to create a session enabled Queue and send messages
to it. Then, use an instance of QueueClient
or SubscriptionClient
to create a receiver
using the createReceiver function. Note
that you will need to specify the session from which you want to receive messages.
const queueClient = serviceBusClient.createQueueClient("my-session-queue");
const receiver = queueClient.createReceiver(ReceiveMode.peekLock, { sessionId: "my-session" });
You can use this receiver in one of 3 ways to receive messages
The Service Bus library depends on the rhea-promise library for managing connections, sending and receiving messages over the AMQP protocol.
You can set the following environment variable to get the debug logs when using this library.
export DEBUG=azure*
export DEBUG=azure*,rhea*
DEBUG
environment variable as follows:export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:amqp-common:datatransformer
DEBUG
environment variable as follows:export DEBUG=azure:service-bus:error,azure-amqp-common:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow
DEBUG
environment variable as shown above and then run your test script as follows:out.log
and logging statements from the sdk go to debug.log
.node your-test-script.js > out.log 2>debug.log
out.log
by redirecting stderr to stdout (&1), and then redirect stdout to a file:node your-test-script.js >out.log 2>&1
out.log
. node your-test-script.js &> out.log
Please take a look at the samples directory for detailed examples on how to use this library to send and receive messages to/from Service Bus Queues, Topics and Subscriptions.
If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.
Generated using TypeDoc