API 文档

Notice 介绍

目前 Notice 的通知服务支持 邮件, 微信 两种方式.

用户只需要配置好相应的联系人, 就可以调用 Notice 的 API 接口, 发送通知信息.

邮件通知:

用户可以通过调用 API 来发送邮件通知. 邮件标题, 邮件内容均由用户自行定义.

为避免邮件量过大被进入垃圾箱或者拒收, 请将邮件中的发件人/发件域加入可信任列表/白名单.

微信通知

用户可以通过调用 API 来发送微信通知.

微信通知的模板内容如下:

事件提醒:

%subject%
事件类型: %param1%
事件时间: %param2%
%content%

相应的请求参数如下:

param = {
    'accessKey' : accessKey,
    'nickNames' : 'ben;joe',
    'subject'   : '服务器负载警告(灾难)',
    'param1'    : '灾难级别',
    'param2'    : '2015-08-01 12:00:23',
    'content'   : 'host: 192.168.1.2, load:10',
}

微信通知的截图如下:

---

API 验证机制

Notice 使用数字签名的 API 验证模式.

调用 API 时, 用户不需要把密码 ( secretKey ) 作为参数明文传输, 而是将数字签名 ( signature ) 作为参数传输给服务器. 服务器端会验证此 signature 的正确性.

生成数字签名 ( signature ) 的方法:

1. 将实际调用API的参数以字母升序(A-Z)排列, 不包括 secretKey 和 signature 字段本身
2. 按照排列之后的顺序, 以 'key=value' + '&' + 'key=value' 的方式连接所有参数, 得到字符串 param_str
3. 以 secretKey + '&' + param_str + '&' + secretKey 的方式得到字符串 sign_str
4. 计算 sign_str 的MD5值 (32位, 不区分大小写), 得到 signature

提示:
1. 生成签名时, 参数不要使用 'urlencode'. 在调用 api 时, 才需要对参数做 'urlencode'
2. '&' 是代码中使用的连接符, '+'是文档显示之用

下面提供了一个代码示例 ( python ):

# -*- coding: utf-8 -*-
import hashlib

accessKey = '123456789'
secretKey = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

param = {
    'accessKey' : accessKey,
    'nickNames' : 'ben;joe',
    'subject'   : '服务器负载警告(灾难)',
    'param1'    : '灾难级别',
    'param2'    : '2015-08-01 12:00:23',
    'content'   : 'host: 192.168.1.2, load:10',
}

param_keys = list(param.keys())
param_keys.sort()

param_str = ''

for key in param_keys:
    param_str += key + '=' + str(param[key]) + '&'

param_str = param_str[:-1]

sign_str = secretKey + '&' + param_str + '&' + secretKey 
signature = hashlib.md5(sign_str).hexdigest()

---

API 返回码

API 返回的结果是 JSON 格式, 示例如下:

# 请求成功
{
    "message":"请求成功",
    "info":{},
    "result":true,
    "statusCode":200
}

# 参数nickNames为空
{
    "message":"参数nickNames为空",
    "info":{},
    "result":false,
    "statusCode":406
}

# 部分成功
{
    "message":"部分成功",
    "info":{
            "successCount":2,
            "failedCount":1,
            "items":[{"errors":{"c":"昵称对应的联系人不存在"}}]
            },
    "result":true,
    "statusCode":301
}

• result: API 请求是否成功
• statusCode: API 返回码
• message: API 返回码的中文解释
• info: 更多信息, 比如: 部分成功则返回具体失败信息, 获取时间戳则返回时间戳的值

API 返回码	含义
200	请求成功
301	部分成功
401	参数不能为空
402	参数accessKey为空
403	参数signature为空
404	签名signature错误
405	服务器时间不正确
406	参数nickNames为空
407	参数groupCode为空
408	参数nickNames对应的收件人不存在
409	参数groupCode对应的组不存在
410	参数groupCode的联系人为空
420	用户不存在
421	accessKey对应的用户不存在
422	用户未激活
423	用户被冻结
424	用户的服务已经到期
441	邮件参数subject为空
442	邮件参数content为空
450	1天内的邮件发送频率超限
451	1小时内的邮件发送频率超限
452	1分钟内的邮件发送频率超限
453	10秒内的邮件发送频率超限
459	发送邮件错误
461	微信参数subject为空
462	微信参数param1为空
463	微信参数param2为空
464	微信参数content为空
465	微信参数subject超长
466	微信参数param1超长
467	微信参数param2超长
470	1天内的微信发送频率超限
471	1小时内的微信发送频率超限
472	1分钟内的微信发送频率超限
473	10秒内的微信发送频率超限
479	发送微信错误
481	联系人不存在
482	nickName为空
483	nickName只支持50个字符(数字,字母,'@','.',及下划线)
484	nickName重复
485	email为空
486	email不合法
487	email重复
488	phone不合法
489	phone重复
490	userName只能在20个字符以内
491	无效的groupCode
492	人数已达上限
493	改动次数超限
494	添加联系人失败
495	修改联系人失败
496	删除联系人失败
501	服务器异常

---

邮件通知

URL

http://api.notice.sendcloud.net/mailapi/send

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
nickNames	string	是	昵称. 多个昵称使用';'分隔, 如 ben;joe
subject	string	是	邮件主题
content	string	是	邮件内容
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

注意:

1. 参数 vars 可能含有特殊字符, 记得 urlencode

2. vars 所传递的变量的值, 长度不能超过 32 个字符, 变量中不能含有 HTTP 链接

3. 生成签名时, 参数不要使用 urlencode. 在调用 api 时, 才需要对参数做 urlencode

---

邮件通知 (群组)

URL

http://api.notice.sendcloud.net/mailapi/sendgroup

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
groupCode	string	是	组编号
subject	string	是	邮件主题
content	string	是	邮件内容
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

---

微信通知

URL

http://api.notice.sendcloud.net/weixinapi/send

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
nickNames	string	是	昵称. 多个昵称使用';'分隔, 如 ben;joe
subject	string	是	微信主题, 不超过30个字符
param1	string	是	参数1, 不超过30个字符
param2	string	是	参数2, 不超过30个字符
content	string	是	微信内容
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

---

微信通知 (群组)

URL

http://api.notice.sendcloud.net/weixinapi/sendgroup

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
groupCode	string	是	组编号
subject	string	是	微信主题, 不超过30个字符
param1	string	是	参数1, 不超过30个字符
param2	string	是	参数2, 不超过30个字符
content	string	是	微信内容
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

---

服务器时间戳

URL

http://api.notice.sendcloud.net/mailapi/timestamp/get

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY

---

获取联系人数量

URL

http://api.notice.sendcloud.net/linkmanMember/count

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
nickName	string	否	联系人昵称
groupCode	string	否	分组编码
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

---

查询联系人

URL

http://api.notice.sendcloud.net/linkmanMember/list

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
nickName	string	否	联系人昵称
groupCode	string	否	分组编码
startNo	string	否	分页起始编号,默认为0,当大于总记录数时,为最大记录数
pageSize	string	否	一页中显示的记录数,默认为10
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

---

添加联系人

URL

http://api.notice.sendcloud.net/linkmanMember/add

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
nickName	string	是	联系人昵称
email	string	是	邮箱地址
phone	string	否	手机号
userName	string	否	姓名,小于等于20个字符
groupCodes	string	否	分组编码,多个用逗号分隔
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

---

修改联系人

URL

http://api.notice.sendcloud.net/linkmanMember/modify

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
nickName	string	是	联系人昵称
email	string	否	邮箱地址
phone	string	否	手机号
userName	string	否	姓名,小于等于20个字符
groupCodes	string	否	分组编码,多个用逗号分隔
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证

---

删除联系人

URL

http://api.notice.sendcloud.net/linkmanMember/remove

参数说明

参数	类型	必选	说明
accessKey	string	是	认证KEY
nickName	string	是	联系人昵称
timestamp	string	否	UNIX时间戳
signature	string	是	签名, 合法性验证