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',
}

微信通知的截图如下:

pic


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
}

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 签名, 合法性验证