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 | 是 | 签名, 合法性验证 |
注意
:
-
参数 vars 可能含有特殊字符, 记得
urlencode
-
vars 所传递的变量的值, 长度不能超过 32 个字符, 变量中不能含有 HTTP 链接
-
生成签名时, 参数不要使用
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 | 是 | 联系人昵称 |
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 | 是 | 联系人昵称 |
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 | 是 | 签名, 合法性验证 |