The nodejs sdk for aliyun mns service
Ali MNS service is a MQ(message queue) service provided by AliYun. The world largest online sales website www.taobao.com is heavily relying on it.
You can visit http://www.aliyun.com/product/mns for more details.
The original Ali-MQS service has been upgraded and changed it's name to Ali-MNS since June, 2015. Go to Migrate part for the old version informations.
Use 'npm install ali-mns' to install the package.
var AliMNS = require("ali-mns");
var account = new AliMNS.Account("<your-account-id>", "<your-key-id>", "<your-key-secret>");
var mq = new AliMNS.MQ("<your-mq-name>", account, "hangzhou");
// send message
mq.sendP("Hello ali-mns").then(console.log, console.error);
The ali-mns use the promise pattern. Any functions suffix with 'P' indicate a promise object will be returned from it.
Most source files are written in typescript instead of javascript. Visit http://www.typescriptlang.org/ for more information about typescript.
If you interest in source file, visit GitHub https://github.com/InCar/ali-mns
Please use 'grunt' to compile ts files into a single index.js file after downloading source files.
If you only want to use it, forget this.
The Account class store your ali account information. Construct an account object is simple:
accountId: String, ali account id.
keyId: String, ali key id.
keySecret: String, ali key secret.
var AliMNS = require("ali-mns");
var account = new AliMNS.Account("<your-owner-id>", "<your-key-id>", "<your-key-secret>");
The account object is usually passed as an argument for other class such as MNS, MQ
Follow this link to find yours
Return the ali account id.
Same as account.getAccountId(). For compatible v1.x.
Return the ali key id.
The MNS operate the mns queue.
account: An account object.
region: String, optional. It can be "hangzhou", "beijing" or "qingdao", the 3 data center that provide mns service. Default is "hangzhou". It can also be internal address "hangzhou-internal", "beijing-internal" or "qingdao-internal".
var AliMNS = require("ali-mns");
var account = new AliMNS.Account("<your-account-id>", "<your-key-id>", "<your-key-secret>");
var mns = new AliMNS.MNS(account, "hangzhou");
Same as MNS. For compatible v1.x.
List all of the queue in a data center.
prefix: String, optional. Return only mq with the prefix.
pageSize: number, optional. How many mns will be returned in a page, 1~1000, default is 1000.
pageMarker: String, optional. Request the next page, the value is returned in last call.
mns.listP("my", 20).then(function(data){
console.log(data);
return mns.listP("my", 20, data.Queues.NextMarker);
}).then(function(dataP2){
console.log(dataP2);
}, console.error);
mns.createP(name:string, options?:any)
Create a mq.
name: String. The queue name.
options: optional. The queue attributes.
options.DelaySeconds: number. How many seconds will the messages be visible after sent. 0~604800(7days), default is 0.
options.MaximumMessageSize: number. How many bytes could the message be. 1024(1k)~65536, default is 65536(64k).
options.MessageRetentionPeriod: number. How many seconds will the messages live, 60~1296000(15days), default is 345600(4days).
optiions.VisibilityTimeout: number. How many seconds will the message keep invisible after be received, 1~43200(12hours), default is 30.
options.PollingWaitSeconds: numer. How many seconds will the receive request wait for if mq is empty. 0~30, default is 0.
mns.createP("myAliMQ", {
DelaySeconds: 0,
MaximumMessageSize: 65536,
MessageRetentionPeriod: 345600,
VisibilityTimeout: 30,
PollingWaitSeconds: 0
}).then(console.log, console.error);
If a mq with same name exists, calling createP will succeed only when all of the mq attributes are all same. Any mismatched attributes will cause an "QueueAlreadyExist" failure.
Delete an mq.
name: String. The queue name.
mns.deleteP("myAliMQ").then(console.log, console.error);;
The MQ operate the message in a queue.
name: String. The name of mq.
account: An account object.
region: String, optional. It can be "hangzhou", "beijing" or "qingdao", the 3 data center that provide mns service. Default is "hangzhou". It can also be internal address "hangzhou-internal", "beijing-internal" or "qingdao-internal".
var AliMNS = require("ali-mns");
var account = new AliMNS.Account("<your-owner-id>", "<your-key-id>", "<your-key-secret>");
var mq = new AliMNS.MQ("myAliMQ", account, "hangzhou");
Gets the name of mq.
Gets the account of mq.
Gets the region of mq.
Send a message to the queue.
message: String. The content that sent to queue.
priority: number, optional. 1(lowest)~16(highest), default is 8.
delaySeconds: number, optional. How many seconds will the messages be visible after sent. 0~604800(7days), default is 0. This argument is prior to the options.DelaySeconds in attributes of message queue.
mq.sendP("Hello Ali-MNS", 8, 0).then(console.log, console.error);
Gets or sets the tolerance seconds for mq.recvP method.
value: number. Default is 5, in seconds. How long will mq.recvP wait before timeout. Due to network lag, the return of mq.recvP method may be later than expected.
Receive a message from queue. This will change the message to invisible for a while.
waitSeconds: number. optional. The max seconds to wait if queue is empty, after that an error MessageNotExist will be returned.
mq.recvP(5).then(console.log, console.error);
This method will wait waitSeconds + getRecvTolerance()
totally if queue is empty.
Peek a message. This will not change the message to invisible.
mq.peekP(5).then(console.log, console.error);
Delete a message from queue. A message will be invisible for a short time after received. A message must be deleted after processed, otherwise it can be received again.
receiptHandle: String. Return by mq.recvP or mq.notifyRecv.
mq.recvP(5).then(function(data){
return mq.deleteP(data.Message.ReceiptHandle);
}).then(console.log, console.error);
Reserve a received message.
receiptHandle: String. Return by mq.recvP or mq.notifyRecv.
reserveSeconds: number. How long will the message be reserved, in seconds. 1~43200(12hours).
mq.recvP().then(function(data){
return mq.reserveP(data.Message.ReceiptHandle, 120);
}).then(function(dataReserved){
return mq.deleteP(dataReserved.ChangeVisibility.ReceiptHandle);
});
If you need more time to process the message after received, you can reserve it for a longer time. The message will continue to keep invisible for reserveSeconds from now. Set a shorter time is also possible. If succeed, a new receiptHandle will be returned to replace the old one, further mq.deleteP or mq.reserveP should use the newer. And the newer receiptHandle will expired after reserveSeconds past.
Register a callback function to receive messages.
cb: The callback function will be called once for each received message. And if the callback function return true, the message received will be delete automatically, while you should delete the message manually, if return false.
waitSeconds: number, optional. 1~30. The max seconds to wait in a polling loop, default is 5. At the begin of a polling loop, it will check if mq.notifyStopP has been called, So the bigger number will cause a slowly mq.notifyStopP. Set waitSeconds to 0 ,will actually use the default value 5 seconds instead.
mq.notifyRecv(function(err, message){
console.log(message);
if(err && err.message === "NetworkBroken"){
// Best to restart the process when this occurs
throw err;
}
return true; // this will cause message to be deleted automatically
});
Both callback functions will work if you call notifyRecv twice for 2 different callback functions. But each received message only will trigger one of them only.
Stop mq.notifyRecv working. The promise object returned will not be resolved until the receiving loop stopped actually. The max time wait for notifyRecv() stop is determined by waitSeconds passed to mq.notifyRecv.
mq.notifyStopP().then(console.log, console.error);
Get the attributes of the mq.
mq.getAttrsP().then(console.log, console.error);
Modify the attributes of mq.
options: the queue attributes. See the options of mns.createP.
mq.setAttrsP({
DelaySeconds: 0,
MaximumMessageSize: 65536,
MessageRetentionPeriod: 345600,
VisibilityTimeout: 30,
PollingWaitSeconds: 0
}).then(console.log, console.error);
A simple message define, used in MQBatch.
msg: string. The content of message.
priority: number, optional. 1(lowest)~16(highest), default is 8.
delaySeconds: number, optional. How many seconds will the messages be visible after sent. 0~604800(7days), default is 0. This argument is prior to the options.DelaySeconds in attributes of message queue.
var msg = new AliMNS.Msg("Make a test");
Return the content of message.
Return the priority of message.
Return the delay seconds of message.
Provide the batch process model introduced in a new edtion of Ali-MNS service in June, 2015.
It derives from MQ, so all methods in MQ are avaiable in MQBatch too. For example, you can
use mqBatch.setRecvTolerance(1.2)
to adjust the timeout behavior of mqBatch.recvP().
var mqBatch = new AliMNS.MQBatch(aliCfg.mqName, account, aliCfg.region);
Send a message or batch send messages to the queue.
msg: String or an array of Msg. The message(s) up to 16 that sent to queue.
priority: number, optional. Only valid when msg
is a string, 1(lowest)~16(highest), default is 8.
delaySeconds: number, optional. Only valid when msg
is a string. How many seconds will the messages be visible after sent. 0~604800(7days), default is 0.
This argument is prior to the options.DelaySeconds in attributes of message queue.
If msg
is an array of Msg
, use the priority & delaySeconds properties of Msg
, and ignore the 2nd and 3rd arguments.
var msgs = [];
for(var i=0;i<5;i++){
var msg = new AliMNS.Msg("BatchSend" + i, 8, 0);
msgs.push(msg);
}
mqBatch.sendP(msgs);
Receive a message or batch receive messages from queue. This will change the messages to invisible for a while.
waitSeconds: number. optional. The max seconds to wait if queue is empty, after that an error MessageNotExist will be returned.
numOfMessages: number. optional. The max number of message can be received in a batch, can be 1~16, default is 16.
mqBatch.recvP(5, 16).then(console.log, console.error);
Peek message(s). This will not change the message to invisible.
numOfMessages: number. optional. The max number of message can be peeked in a batch, can be 1~16, default is 16.
mqBatch.peekP(5, 16).then(console.log, console.error);
Delete a message or messages from queue. Messages will be invisible for a short time after received. Messages must be deleted after processed, otherwise it can be received again.
receiptHandle: String or an array of string. Return by mq.recvP mq.notifyRecv or mqBatch.recvP mqBatch.notifyRecv.
var rhsToDel = [];
mqBatch.recvP(5, 16).then(function(dataRecv){
for(var i=0;i<dataRecv.Messages.Message.length;i++){
rhsToDel.push(dataRecv.Messages.Message[i].ReceiptHandle);
}
}).then(function(){
return mqBatch.deleteP(rhsToDel);
}).then(console.log, console.error);
Register a callback function to receive messages in batch mode.
numOfMessages: number. optional. The max number of message can be received in a batch, can be 1~16, default is 16.
All other arguments are same as mq.notifyRecv.
Set the environment variable DEBUG to "ali-mns" to enable the debug trace output.
# linux bash
export DEBUG=ali-mns
# windows
set DEBUG=ali-mns
- 1.The ali-mns is fully compatible with ali-mqs, simply replace the ali-mqs package to ali-mns.
// var AliMQS = require('ali-mqs');
var AliMQS = require('ali-mns');
- 2.Optional. Change the ownerId to accountId Ali-Yun upgrade their account system, and recommend to use the newer account id instead of owner id. But the old owner id is still available for now.
var AliMQS = require("ali-mns");
// var account = new AliMNS.Account("hl35yqoedp", "<your-key-id>", "<your-key-secret>");
var account = new AliMNS.Account("1786090012649663", "<your-key-id>", "<your-key-secret>");
ownerId is mixed with number and letter
accountId is a 16-digits number, follow this link to find your accountId.
In GitHub, An branch v1.x keeps tracking for the old mqs services. And use `npm install ali-mqs' to install the ali-mqs package for v1.x.
Create 20 queues, then send 2000 messages to them randomly.
It is about 10 times slower in serial mode than in batch mode.
1st - Serial Mode(batch_size=1)
// 20 queues 2000 messages batch_size=1
AliMNS-performance
concurrent-queues
√ #BatchSend (3547ms)
√ #recvP (21605ms)
√ #stopRecv (6075ms)
2nd - Batch Mode(Batch_size=16)
// 20 queues 2000 messages batch_size=16
AliMNS-performance
concurrent-queues
√ #BatchSend (3472ms)
√ #recvP (2125ms)
√ #stopRecv (6044ms)
The testing code is in $/test/performance.js and a test log sample is in $/test/performance.log
Needs mocha module to run the test.
Set environment variable DEBUG to ali-mns.test to turn on output trace(will slow down the test).
MIT