The full API documentation is here and this client tries to stick to the API as much as possible so if you see an option in the API docs, you can use it in the methods below.
1. Install the node module:
npm install iron_mq
2. Setup your Iron.io credentials
3. Create an IronMQ Client object:
var iron_mq = require('iron_mq');
var imq = new iron_mq.Client();
Or pass in credentials:
var imq = new iron_mq.Client({token: "MY_TOKEN", project_id: "MY_PROJECT_ID", queue_name: "MY_QUEUE"});
If no queue_name
is specified it defaults to default
.
imq.queues(options, function(error, body) {});
Options:
page
: The 0-based page to view. The default is 0.per_page
: The number of queues to return per page. The default is 30, the maximum is 100.
--
You can have as many queues as you want, each with their own unique set of messages.
var queue = imq.queue("my_queue");
Note: if queue with desired name does not exist it returns fake queue. Queue will be created automatically on post of first message or queue configuration update.
--
queue.info(function(error, body) {});
--
Messages are placed on the queue in a FIFO arrangement. If a queue does not exist, it will be created upon the first posting of a message.
queue.post(messages, function(error, body) {});
// single message
queue.post("hello IronMQ!", function(error, body) {});
// with options
queue.post({body: "hello IronMQ", delay: 30}, function(error, body) {});
// or multiple messages
queue.post(["hello", "IronMQ"], function(error, body) {});
// messages with options
queue.post(
[{body: "hello", timeout: 40},
{body: "IronMQ", timeout: 80}],
function(error, body) {}
);
Required messages' parameters:
body
: The message body as a string. This does not jsonify objects.
Optional messages' parameters:
-
timeout
: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. Default is 60 seconds. Minimum is 30 seconds. Maximum is 86,400 seconds (24 hours). -
delay
: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days). -
expires_in
: How long in seconds to keep the item on the queue before it is deleted. Default is 604,800 seconds (7 days). Maximum is 2,592,000 seconds (30 days).
--
queue.get(options, function(error, body) {});
queue.get_n(options, function(error, body) {});
Options:
-
n
: The maximum number of messages to get. Default is 1. Maximum is 100. -
timeout
: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. If not set, value from POST is used. Default is 60 seconds. Minimum is 30 seconds. Maximum is 86,400 seconds (24 hours).
In get
function when n
parameter is specified and greater than 1 method returns list of messages.
Otherwise, message's object will be returned. get_n
function returns Array
of messages even if n
option
is set to 1 or omitted.
When you pop/get a message from the queue, it is no longer on the queue but it still exists within the system.
You have to explicitly delete the message or else it will go back onto the queue after the timeout
.
--
queue.msg_get(message_id, function(error, body) {});
--
Peeking at a queue returns the next messages on the queue, but it does not reserve them.
queue.peek(options, function(error, body) {});
queue.peek_n(options, function(error, body) {});
Options:
n
: The maximum number of messages to peek. Default is 1. Maximum is 100.
In peek
function when n
parameter is specified and greater than 1 method returns list of messages.
Otherwise, message's object will be returned. peek_n
function returns Array
of messages even if n
option
is set to 1 or omitted.
--
Touching a reserved message extends its timeout by the duration specified when the message was created, which is 60 seconds by default.
queue.msg_touch(message_id, function(error, body) {});
--
queue.msg_release(message_id, options, function(error, body) {});
Options:
delay
: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).
--
queue.del(message_id, function(error, body) {});
Be sure to delete a message from the queue when you're done with it.
--
queue.clear(function(error, body) {});
--
queue.del_queue(function(error, body) {});
--
IronMQ push queues allow you to setup a queue that will push to an endpoint, rather than having to poll the endpoint. Here's the announcement for an overview.
queue.update(options, function(error, body) {});
The following options are all related to Push Queues:
subscribers
: An array of subscriber hashes containing a “url” field. This set of subscribers will replace the existing subscribers. To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint. See below for example json.push_type
: Eithermulticast
to push to all subscribers orunicast
to push to one and only one subscriber. Default ismulticast
.retries
: How many times to retry on failure. Default is 3. Maximum is 100.retries_delay
: Delay between each retry in seconds. Default is 60.
Example:
queue.update(
{push_type: "multicast",
retries: 5,
subscribers: [
{url: "http://my.first.end.point/push"},
{url: "http://my.second.end.point/push"}
]},
function(error, body) {}
);
--
queue.add_subscribers({url: "http://nowhere.com"}, function(error, body) {});
queue.add_subscribers(
[{url: 'http://first.endpoint.xx/process'},
{url: 'http://second.endpoint.xx/process'}],
function(error, body) {}
);
queue.rm_subscribers({url: "http://nowhere.com"}, function(error, body) {});
queue.rm_subscribers(
[{url: 'http://first.endpoint.xx/process'},
{url: 'http://second.endpoint.xx/process'}],
function(error, body) {}
);
--
queue.add_alerts(
[
{
type: 'fixed',
direction: 'asc',
trigger: 201,
queue: 'my_queue_for_alerts',
snooze: 11
},{
type: 'fixed',
direction: 'desc',
trigger: 202,
queue: 'my_queue_for_alerts',
snooze: 12
}
],
function(error, body) {}
);
queue.update_alerts(
[
{
type: 'fixed',
direction: 'asc',
trigger: 211,
queue: 'my_queue_for_alerts',
snooze: 20
},{
type: 'fixed',
direction: 'desc',
trigger: 212,
queue: 'my_queue_for_alerts',
snooze: 21
}
],
function(error, body) {}
);
queue.delete_alerts(
[
{
id: 'xxxxxxxxxxxxxxxxxx1'
},
{
id: 'xxxxxxxxxxxxxxxxxx2'
},
],
function(error, body) {} );
queue.delete_alert_by_id(alert_id, function(error, body) {});
--
After pushing a message:
queue.msg_push_statuses(message_id, function(error, body) {});
--
queue.del_msg_push_status(message_id, subscriber_id, function(error, body) {});
--
If you want to revert you queue just update push_type
to "pull"
.
queue.update({push_type: "pull"}, function(error, body) {});
--
© 2011 - 2013 Iron.io Inc. All Rights Reserved.