aliyun-mns

aliyun-mns

阿里云 消息服务 非官方 SDK for node.js

另一个非官方 node.js SDK 请移步至 https://github.com/InCar/ali-mns

使用方法请参照 官方文档

技术支持

请发邮件至：[e-mail]

初始化

const MNS = require('aliyun-mns')
const mns = new MNS({
  accessKeyId: '[在阿里云申请的 accessKeyId]',
  secretAccessKey: '[在阿里云申请的 secretAccessKey]',
  endpoint: 'http://[账号ID].mns.[区域](-internal)(-vpc).aliyuncs.com',
  apiVersion: '2015-06-06' // 调用MNS接口的版本号，当前版本为2015-06-06
})

安装

Node.js 安装

npm install aliyun-mns

使用方法及代码示例

队列接口

在 samples/queue 目录下的代码示例，使用方法：

• 将 sample/mns.js 中需要的参数修改
• 打开需要执行的某个实例文件，如 create.js，将其中的参数改成你自己的 queue 实例参数
• 执行示例文件即可, 如:

cd samples/queue
node create

主题接口

在 samples/topic 目录下的代码示例，使用方法：

• 将 sample/mns.js 中需要的参数修改
• 打开需要执行的某个实例文件，如 create.js，将其中的参数改成你自己的 topic 实例参数
• 执行示例文件即可, 如:

cd samples/topic
node create

API

队列接口

Queue

• constructor (mns, name, options)
  • mns - [Required] - 使用自己参数初始化的 MNS 对象
  • name - [Required] - 队列名称
  • options - [Optional] - 队列属性
    • DelaySeconds - 发送到该 Queue 的所有消息默认将以DelaySeconds参数指定的秒数延后可被消费，单位为秒。0-604800秒（7天）范围内某个整数值，默认值为0
    • MaximumMessageSize - 发送到该Queue的消息体的最大长度，单位为byte。1024(1KB)-65536（64KB）范围内的某个整数值，默认值为65536（64KB）。
    • MessageRetentionPeriod - 消息在该 Queue 中最长的存活时间，从发送到该队列开始经过此参数指定的时间后，不论消息是否被取出过都将被删除，单位为秒。60 (1分钟)-1296000 (15 天)范围内某个整数值，默认值为345600 (4 天)
    • VisibilityTimeout - 消息从该 Queue 中取出后从Active状态变成Inactive状态后的持续时间，单位为秒。1-43200(12小时)范围内的某个值整数值，默认值为30（秒）
    • PollingWaitSeconds - 当 Queue 中没有消息时，针对该 Queue 的 ReceiveMessage 请求最长的等待时间，单位为秒。0-30秒范围内的某个整数值，默认值为0（秒）
• create (metaoverride, callback) - [CreateQueue] - 该接口用于创建一个新的队列。队列名称是一个不超过256个字符的字符串，必须以字母或数字为首字符，剩余部分可以包含字母、数字和横划线(-)。
  • metaoverride=true - [SetQueueAttributes] - 该接口用于修改消息队列的属性。
• delete (callback) - [DeleteQueue] - 该接口用于删除一个已创建的队列。
• get (callback) - [GetQueueAttributes] - 该接口用于获取某个已创建队列的属性，返回属性除了创建队列时设置的可设置属性外，还可以取到队列创建时间、队列属性修改最后时间以及队列中的各类消息统计数（近似值）。
• list (headers, callback) - [ListQueue] - 该接口用于列出 AccountId 下的队列列表，可分页获取数据。返回结果中只包含 QueueURL 属性，如需进一步获取消息队列的属性可以通过 GetQueueAttributes 接口（详见本文档 GetQueueAttributes 接口）获取。如果只是要获取特定前缀的队列列表，在调用此接口时指定 x-mns-prefix 参数，返回对队列名称的前缀匹配结果。
  • headers - [Optional] - 查询属性
    • x-mns-marker - 请求下一个分页的开始位置，一般从上次分页结果返回的NextMarker获取。
    • x-mns-ret-number - 单次请求结果的最大返回个数，可以取1-1000范围内的整数值，默认值为1000。
    • x-mns-prefix - 按照该前缀开头的 queueName 进行查找。

Message

• constructor (queue)
  • queue - [Required] - 队列
• send (options, callback) - [SendMessage&BatchSendMessage] - 该接口用于发送消息到指定的队列，普通消息发送到队列随即可被消费者消费。但是如果生产者发送一个消息不想马上被消费者消费（典型的使用场景为定期任务），生产者在发送消息时设置 DelaySeconds 参数就可以达到此目的。发送带 DelaySeconds 参数值大于0的消息初始状态为 Delayed，此时消息不能被消费者消费，只有等 DelaySeconds 时间后消息变成 Active 状态后才可消费。
  • options - [Required]
    • MessageBody - [Required] - 消息正文。UTF-8字符集
    • DelaySeconds - [Optional] - DelaySeconds 指定的秒数延后可被消费，单位为秒。0-604800秒（7天）范围内某个整数值，默认值为0
    • Priority - [Optional] - 指定消息的优先级权值，优先级越高的消息，越容易更早被消费。取值范围1~16（其中1为最高优先级），默认优先级为8
• receive (numOfMessages, waitseconds, callback) - [ReceiveMessage&BatchReceiveMessage] - 该接口用于消费者消费队列中的消息，ReceiveMessage 操作会将取得的消息状态变成 Inactive，Inactive 的时间长度由 Queue 属性 VisibilityTimeout 指定（详见CreateQueue接口）。 消费者在 VisibilityTimeout 时间内消费成功后需要调用 DeleteMessage 接口删除该消息，否则该消息将会重新变成为 Active 状态，此消息又可被消费者重新消费。
  • numOfMessages - [Required(Batch)] - 本次BatchReceiveMessage最多获取的消息条数
  • waitseconds - [Optional] - 本次 ReceiveMessage 请求最长的Polling等待时间，单位为秒
• delete (receiptHandle, callback) - [DeleteMessage&BatchDeleteMessage] - 该接口用于删除已经被消费过的消息，消费者需将上次消费后得到的 ReceiptHandle 作为参数来定位要删除的消息。本操作只有在 NextVisibleTime 之前执行才能成功；如果过了 NextVisibleTime，消息重新变回 Active 状态，ReceiptHandle 就会失效，删除失败，需重新消费获取新的 ReceiptHandle。
  • receiptHandle - [Required] - 上次消费后返回的消息ReceiptHandle，详见本文ReceiveMessage接口
• peek (numOfMessages, callback) - [PeekMessage&BatchPeekMessage] - 该接口用于消费者查看消息，PeekMessage 与 ReceiveMessage 不同，PeekMessage 并不会改变消息的状态，即被 PeekMessage 获取消息后消息仍然处于 Active 状态，仍然可被查看或消费；而后者操作成功后消息进入 Inactive ，在 VisibilityTimeout 的时间内不可被查看和消费。
  • numOfMessages - [Required(Batch)] - 本次 BatchPeekMessage 最多查看消息条数
• visibility (receiptHandle, visibilityTimeout, callback) - [ChangeMessageVisibility] - 该接口用于修改被消费过并且还处于的 Inactive 的消息到下次可被消费的时间，成功修改消息的 VisibilityTimeout 后，返回新的 ReceiptHandle。
  • receiptHandle - [Required] - 上次消费后返回的消息 ReceiptHandle ，详见 ReceiveMessage 接口
  • visibilityTimeout - [Required] - 从现在到下次可被用来消费的时间间隔，单位为秒
• subscribe (delay, numOfMessages, waitseconds, callback) - 该接口使用轮询的方式订阅消息队列中的消息。
  • delay - [Optional] - 一次ReceiveMessage轮询等待时间，单位为秒 - 取值范围整数值，默认值为0（秒）
  • delay - [Optional] - 一次BatchReceiveMessage最多获取的消息条数 - 取值范围1~16，默认值为16（条）
  • delay - [Optional] - 一次ReceiveMessage请求最长的Polling等待时间，单位为秒 - 取值范围0~30，默认值为30（秒）

主题接口

Topic

• constructor (mns, name, options)
  • mns - [Required] - 使用自己参数初始化的 MNS 对象
  • name - [Required] - 主题名称
  • options - [Optional] - 主题属性
    • MaximumMessageSize - 发送到该 Topic 的消息体最大长度，单位为Byte。1024(1KB) - 65536(64KB)范围内的某个整数值，默认值为65536(64KB)
• create (metaoverride, callback) - [CreateTopic] - 该接口用于创建一个新的主题。主题名称是一个不超过256个字符的字符串，必须以字母或数字为首字符，剩余部分可以包含字母、数字和横划线(-)。
  • metaoverride=true - [SetTopicAttributes] - 该接口用于修改主题的属性。
• delete (callback) - [DeleteTopic] - 该接口用于删除一个已创建的主题。
• get (callback) - [GetTopicAttributes] - 该接口用于获取某个已创建主题的属性，返回属性除创建主题时的可设置属性外，还可以获取主题的消息最长存活时间、主题创建时间等。
• list (headers, callback) - [ListTopic] - 该接口用于列出帐号下的主题列表，可分页获取数据。如果只是要获取特定的主题列表，在调用接口时指定 x-mns-prefix 参数，服务端将返回主题名称与前缀匹配的主题列表。
  • headers - [Optional] - 查询属性
    • x-mns-marker - 请求下一个分页的开始位置，一般从上次分页结果返回的NextMarker获取。
    • x-mns-ret-number - 单次请求结果的最大返回个数，可以取1-1000范围内的整数值，默认值为1000。
    • x-mns-prefix - 按照该前缀开头的 topicName 进行查找。

Message

• constructor (topic)
  • topic - [Required] - 主题
• publish (options, callback) - [PublishMessage] - 该接口用于发布者向指定的主题发布消息，消息发布到主题后随即会被推送给 Endpoint 消费。
  • options - [Required]
    • MessageBody - [Required] - 消息正文。UTF-8字符集

Subscription

• constructor (topic, name, options)
  • topic - [Required] - 主题
  • name - [Required] - 订阅名称
  • options - [Required] - 订阅属性
    • Endpoint - [Required] - 描述此次订阅中接收消息的终端地址 - 目前支持HttpEndpoint，必须以"http://"为前缀
    • NotifyStrategy - [Optional] - 描述了向 Endpoint 推送消息出现错误时的重试策略 - BACKOFF_RETRY 或者 EXPONENTIAL_DECAY_RETRY，默认为BACKOFF_RETRY，重试策略的具体描述请参考 基本概念/NotifyStrategy
    • NotifyContentFormat - [Optional] - 描述了向 Endpoint 推送的消息格式 - XML 或者 SIMPLIFIED，默认为 XML，消息格式的具体描述请参考 基本概念/NotifyContentFormat
• subscribe (metaoverride, callback) - [Subscribe] - 该接口用于订阅主题，创建 Subscription。Subscription 名称是一个不超过 256 个字符的字符串，必须以字母或者数字为首字符，剩余部分可以包含字母、数字和横华线(-)。创建Subscription 时，需要指定对应的 Endpoint，否则不合法，目前支持HttpEndpoint。
  • metaoverride=true - [SetSubscriptionAttributes] - 该接口用于修改 Subscription 的属性。
• unsubscribe (callback) - [Unsubscribe] - 该接口用于取消一个已创建的 Subscription。
• get (callback) - [GetSubscriptionAttributes] - 该接口用于获取 Subscription 的属性。
• list (headers, callback) - [ListSubscriptionByTopic] - 该接口用于列出某个主题下的 Subscription 列表，可分页获取数据。
  • headers - [Optional] - 查询属性
    • x-mns-marker - 请求下一个分页的开始位置，一般从上次分页结果返回的NextMarker获取。
    • x-mns-ret-number - 单次请求结果的最大返回个数，可以取1-1000范围内的整数值，默认值为1000。
    • x-mns-prefix - 按照该前缀开头的 subscriptionName 进行查找。

贡献者

https://github.com/wzbg/aliyun-mns

依赖

• request - Simplified HTTP request client.
• data2xml - A data to XML converter with a nice interface (for NodeJS).
• xml2json - Converts xml to json and vice-versa, using node-expat.

我们在代码中参考了 ALIYUN SDK，在此声明。

License

The MIT License (MIT)

Copyright (c) 2016