私有部署版短信网关接口规范
短信网关接口规范

行云管家平台短信通知目前支持自定义配置短信网关,用户可以使用行云管家平台自带的短信通知服务,同时也可以根据用户需要配置使用自己的短信网关。自定义短信网关需要用户按照以下接口规范进行开发,并且到行云管家管理控制台手动配置,用户开发的自定义网关首先需要提供一个接口接收行云管家平台推送http请求,再根据接收到的消息去调用自有的短信通知业务代码。

对于每一次HTTP请求,我们都会带上签名信息,通过验证签名信息确认是否为行云管家平台所发请求。请求为POST请求,签名信息通过URL参数传递样例如下:

1.http请求URL:

endpoint?accessKeyId=HoCpZ8DLYq64mL9b&signature=GSYw4OI5Q%2BpApjgBjQPE7kHlFS4%3D&version=1&nonce=nQxEmx&timestamp=2018-10-08T15%3A50%3A39Z

2.header:

Content-type: application/json; charset=UTF-8    Accept: application/json

3.body:

{ "phones": ["18000000000"], "template": "SystemUpgrade", "parameters": ["2018-10-01 19:30:00", "2018-10-01 22:30:00"] }

提示:其中endpoint为用户提供的用于接收行云管家平台推送短信消息的URL地址。

URL参数:

  • accessKeyId 行云管家管理控制台 OpenAPI中的AccessKey信息
  • signature 签名工具类签名后结果
  • version api接口版本号
  • nonce 随机数
  • timestamp 时间戳

请求体参数:

  • phones 接收短信通知的手机号列表
  • emplate 短信模板枚举
  • parameters 短信模板参数列表

签名中accessKeyId、accessKeySecret 是行云管家管理控制台OpenAPI中的AccessKey信息:

模板种类

行云管家目前定义了六种短信模板,分别是:验证码模板、会话双因子认证模板、升级通知模板、监控预警模板、后付费资源消费预警模板、告警恢复模板。对应这六个模板我们定义了一个枚举类;

行云管家使用的第三方短信平台为sendcloud,在sendcloud平台上预定义的六种模板如下:

public enum SmsTemplate {
  /**
  * 短信验证码
  */
  VerifyCode(2),//验证码模版:验证码,超时(分)
  Session2FA(2),//会话双因子认证:超时(分)、验证码
  SystemUpgrade(2),//升级通知:开始时间,结束时间
  MonitorAlert(3),//监控预警
  CostAlert(2),//后付费资源消费预警
  AlertRecover(4)//告警恢复
  ;
    private int paramLength;//模版需要的参数长度

  SmsTemplate(int paramLength) {
      this.paramLength = paramLength;
    }

    public int getParamLength() {
      return paramLength;
    }
  }
1.验证码模板

【行云管家】您的验证码是:%code%,该验证码将会在%minute%分钟后过期。

2.验证码模板

【行云管家】您正在尝试进行的操作已开启双因子认证,请在%minute%分钟之内输入以下验证码:%code%,如非本人操作,请确认您的账户安全。

3.验证码模板

【行云管家】尊敬的用户,行云管家将于%startTime%进行版本升级,届时将暂停服务,请大家提前做好准备,升级工作预计于%endTime%完成,给您带来不便,敬请谅解!

4.验证码模板

【行云管家】您的%resourceType%“%resourceName%”由于%content%而产生预警,请确认预警原因。

5.验证码模板

【行云管家】您的云账户“%cloudAccount%”由于单日后付费资源消费大于%threshold%而产生预警,请确认预警原因。

6.验证码模板

【行云管家】您的%resourceType%“%resourceName%”%monitorItem%告警恢复,恢复时间:%time%。

提示:模板中两个%号隔开的是模板变动的内容,这些参数通过接口传递给第三方短信平台。如果您觉得行云管家短信网关配额不够,想用自有短信网关,可以参考我们的模板,关键参数通过接口传递您的自有短信网关上。

接口使用详解
1.接口签名与验签

行云管家的请求过来后,需要进行验签,具体验签可参考demo中代码:

public void doPost(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
    response.setContentType("application/json; charset=UTF-8");
    PrintWriter out = response.getWriter();

    //时间戳
  String timestamp = request.getParameter("timestamp");
    //随机数
  String nonce = request.getParameter("nonce");
    //签名工具签名后的结果
  String signature = request.getParameter("signature");
    //行云管家管理控制台 OpenAPI中的AccessKey信息
  String accessKeyId = request.getParameter("accessKeyId");

    Map<String, Object> signMap = new HashMap<String, Object>();
    signMap.put("timestamp", timestamp);
    signMap.put("version", version);
    signMap.put("nonce", nonce);
    signMap.put("accessKeyId", accessKeyId);

    //通过工具类生成签名,与请求中携带的签名信息比较是否相同
  String signature0 = SignUtil.sign(null, signMap, "POST", accessKeySecret);

    Map<String, Object> result = new HashMap<String, Object>();
    if (signature.equals(signature0)) {
      // body为短信模板参数,拿到参数去自有短信平台发送短信
  SmsRequest body = JSON.parseObject(request.getInputStream(), SmsRequest.class, null);
      result.put("success",true);
      result.put("msg","签名成功");
      System.out.println("签名成功");
    }else {
      //签名失败,非行云管家平台发送请求
  result.put("success",false);
      result.put("msg","签名失败");
      System.out.println("签名失败");
    }
    out.println(JSON.toJSONString(result));
    out.flush();
    out.close();
}

签名成功后解析请求体中的短信模板信息,模板信息包含三个参数,具体如下:

public class SmsRequest {
    //手机号列表
  private List<String> phones = new ArrayList<String>();
    //短信模版
  private SmsTemplate template;
    //模版参数
  private List<String> parameters = new ArrayList<String>();


    public List<String> getPhones() {
      return phones;
    }

    public void setPhones(List<String> phones) {
      this.phones = phones;
    }

    public SmsTemplate getTemplate() {
      return template;
    }

    public void setTemplate(SmsTemplate template) {
      this.template = template;
    }

    public List<String> getParameters() {
      return parameters;
    }

    public void setParameters(List<String> parameters) {
      this.parameters = parameters;
    }
}

提示:手机号列表为需要发送短信通知的手机号,短信模板为以上提到的六种模板,模板参数根据不同模板类型有不同参数,模板参数按顺序对应进行替换。