全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 钉钉智能硬件

HTTP协议及签名

更新时间:2017-09-29 14:46:25

为方便其它语言能快速实现,在此增加了HTTP的详解

注:云通信下的三类产品(包括短信、语音、流量),接口协议一致

一、前言说明

三类产品平台都提供了调用API和消息回执的交互 举例如:

  1. 通过调用语音呼叫API,例如文本转语音外呼接口,来成功发起呼叫。
  2. 平台成功收到请求后发送给运营商,等用户最终挂断电话后,平台会有最终的状态消息确认,就是消息回执对应的协议是:

    • 发送API采用Rest协议:签名算法使用了阿里云的POP协议
    • 发送后消息回执:采用的是阿里云的消息中间件MNS来实现

    二、协议说明

    由于POP的签名算法比较复杂,下面这里结合文本转语音的接口一并详细说明

    2.1 文本转语音API的HTTP协议包示例

    请求示例:

  1. GET /?Signature=ACaeddgMkXN%2FRu7%2BnpPqvgY%2Fyl4%3D&AccessKeyId=LTAIF0IDDKoh1Ra0&Action=SingleCallByTts&CalledNumber=13000000000&CalledShowNumber=057112345678&Format=XML&OutId=123&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=50f16c4d-a91c-4a5a-b17b-7a391362e636&SignatureVersion=1.0&Timestamp=2017-09-28T14%3A21%3A37Z&TtsCode=TTS_0000000&TtsParam=%7B%22code%22%3A%221234%22%2C%22product%22%3A%22test%22%7D&Version=2017-05-25
  2. HTTP/1.1
  3. Host: dyvmsapi.aliyuncs.com
  4. ...

返回示例:

  1. HTTP/1.1 200 OK
  2. ...
  3. <?xml version='1.0' encoding='UTF-8'?>
  4. <SingleCallByTtsResponse>
  5. <Message>OK</Message>
  6. <RequestId>220F7831-A8A9-4A7F-9A55-272346F61B14</RequestId>
  7. <Code>OK</Code>
  8. <CallId>113277672277^100610220432</CallId>
  9. </SingleCallByTtsResponse>

2.2 文本转语音Rest请求参数

如HTTP示例包中,请求的参数可以分两大块:系统参数 和 业务参数

系统参数

系统参数为POP协议的基本参数,有

参数KEY 是否必填 说明
AccessKeyId
Timestamp 格式为:yyyy-MM-dd’T’HH:mm:ss’Z’;时区为:GMT
Format 没传默认为JSON,可选填值:XML
SignatureMethod 建议固定值:HMAC-SHA1
SignatureVersion 建议固定值:1.0
SignatureNonce 用于请求的防重放攻击,每次请求唯一,JAVA语言建议用:java.util.UUID.randomUUID()生成即可
Signature 最终生成的签名结果值
业务参数
参数KEY 是否必填 说明
Action API的命名,固定值,如发送短信API的值为:SendSms
Version API的版本,固定值,如短信API的值为:2017-05-25
RegionId API支持的RegionID,如短信API的值为:cn-hangzhou
CalledShowNumber 具体见API文档描述
CalledNumber 具体见API文档描述
TtsCode 具体见API文档描述
TtsParam 具体见API文档描述
OutId 具体见API文档描述

2.3 生成签名

签名是为了让请求合法,共分为五步:

第一步:请求参数
  1. 请求参数包括系统参数和业务参数,不要遗漏
  2. 参数Key中不能包含最终要生成签名Key(也就是说Signature这个Key是关键字)

参考代码如下

  1. String accessKeyId = "testId";
  2. String accessSecret = "testSecret";
  3. java.text.SimpleDateFormat df = new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
  4. df.setTimeZone(new java.util.SimpleTimeZone(0, "GMT"));// 这里一定要设置GMT时区
  5. java.util.Map<String, String> paras = new java.util.HashMap<String, String>();
  6. // 1. 系统参数
  7. paras.put("SignatureMethod", "HMAC-SHA1");
  8. paras.put("SignatureNonce", java.util.UUID.randomUUID().toString());
  9. paras.put("AccessKeyId", accessKeyId);
  10. paras.put("SignatureVersion", "1.0");
  11. paras.put("Timestamp", df.format(new java.util.Date()));
  12. paras.put("Format", "XML");
  13. // 2. 业务API参数
  14. paras.put("Action", "SingleCallByTts");
  15. paras.put("Version", "2017-05-25");
  16. paras.put("RegionId", "cn-hangzhou");
  17. paras.put("CalledShowNumber", "057112345678");
  18. paras.put("CalledNumber", "13000000000");
  19. paras.put("TtsParam", "{\"code\":\"1234\",\"product\":\"test\"}");
  20. paras.put("TtsCode", "TTS_0000000");
  21. paras.put("OutId", "123");
  22. // 3. 去除签名关键字Key
  23. if (paras.containsKey("Signature"))
  24. paras.remove("Signature");
第二步:根据参数Key排序(顺序)

参考代码如下:

  1. java.util.TreeMap<String, String> sortParas = new java.util.TreeMap<String, String>();
  2. sortParas.putAll(paras);
第三步:构造待签名的请求串

首先介绍下面会用到的特殊URL编码这个是POP特殊的一种规则,即在一般的URLEncode后再增加三种字符替换:加号(+)替换成 %20、星号(*)替换成 %2A、%7E 替换回波浪号(~)参考代码如下:

  1. public static String specialUrlEncode(String value) throws Exception {
  2. return java.net.URLEncoder.encode(value, "UTF-8").replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
  3. }

构造待签名的请求串这里有两步动作第1步,把排序后的参数顺序拼接成如下格式:

  • specialUrlEncode(参数Key) + “=” + specialUrlEncode(参数值)

参考代码如下:

  1. java.util.Iterator<String> it = sortParas.keySet().iterator();
  2. StringBuilder sortQueryStringTmp = new StringBuilder();
  3. while (it.hasNext()) {
  4. String key = it.next();
  5. sortQueryStringTmp.append("&").append(specialUrlEncode(key)).append("=").append(specialUrlEncode(paras.get(key)));
  6. }
  7. String sortedQueryString = sortQueryStringTmp.substring(1);// 去除第一个多余的&符号

打印上面的sortQueryString结果如下:

  1. AccessKeyId%3DtestId%26Action%3DSingleCallByTts%26CalledNumber%3D13000000000%26CalledShowNumber%3D057112345678%26Format%3DXML%26OutId%3D123%26RegionId%3Dcn-hangzhou%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3Df7d2d4ef-6d5f-4da4-86ed-88e001a66abb%26SignatureVersion%3D1.0%26Timestamp%3D2017-09-28T14%253A31%253A56Z%26TtsCode%3DTTS_0000000%26TtsParam%3D%257B%2522code%2522%253A%25221234%2522%252C%2522product%2522%253A%2522test%2522%257D%26Version%3D2017-05-25

对应的未URL编码的值(方便用户对比):

  1. AccessKeyId=testId&Action=SingleCallByTts&CalledNumber=13000000000&CalledShowNumber=057112345678&Format=XML&OutId=123&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=f7d2d4ef-6d5f-4da4-86ed-88e001a66abb&SignatureVersion=1.0&Timestamp=2017-09-28T14%3A31%3A56Z&TtsCode=TTS_0000000&TtsParam=%7B%22code%22%3A%221234%22%2C%22product%22%3A%22test%22%7D&Version=2017-05-25

第2步,按POP的签名规则拼接成最终的待签名串,规则如下:

  • HTTPMethod + “&” + specialUrlEncode(“/”) + ”&” + specialUrlEncode(sortedQueryString)

参考代码如下:

  1. StringBuilder stringToSign = new StringBuilder();
  2. stringToSign.append("GET").append("&");
  3. stringToSign.append(specialUrlEncode("/")).append("&");
  4. stringToSign.append(specialUrlEncode(sortedQueryString));

这就完成了待签名的请求字符串了打印结果如下:

  1. GET&%2F&AccessKeyId%3DtestId%26Action%3DSingleCallByTts%26CalledNumber%3D13000000000%26CalledShowNumber%3D057112345678%26Format%3DXML%26OutId%3D123%26RegionId%3Dcn-hangzhou%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3Df7d2d4ef-6d5f-4da4-86ed-88e001a66abb%26SignatureVersion%3D1.0%26Timestamp%3D2017-09-28T14%253A31%253A56Z%26TtsCode%3DTTS_0000000%26TtsParam%3D%257B%2522code%2522%253A%25221234%2522%252C%2522product%2522%253A%2522test%2522%257D%26Version%3D2017-05-25
第四步:签名

签名采用HmacSHA1算法 + Base64,编码采用:UTF-8参考代码如下:

  1. String sign = sign(accessSecret + "&", stringToSign.toString());
  2. public static String sign(String accessSecret, String stringToSign) throws Exception {
  3. javax.crypto.Mac mac = javax.crypto.Mac.getInstance("HmacSHA1");
  4. mac.init(new javax.crypto.spec.SecretKeySpec(accessSecret.getBytes("UTF-8"), "HmacSHA1"));
  5. byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8"));
  6. return new sun.misc.BASE64Encoder().encode(signData);
  7. }

参数说明:

  1. accessSecret:你的AccessKeyId对应的秘钥AccessSecret,特别说明:POP要求需要后面多加一个“&”字符,即accessSecret + “&”
  2. stringToSign:即第三步生成的待签名请求串

签名后的结果打印如下:

  1. aMfgrx8DLS7vLfpeR1c2rrKLr0Q=
第五步:增加签名结果到请求参数中,发送请求

注意:签名也要做特殊URL编码

  1. String Signature = specialUrlEncode(sign);// aMfgrx8DLS7vLfpeR1c2rrKLr0Q%3D

最终完整的GET请求HTTP为:

  1. http://dyvmsapi.aliyuncs.com/?Signature=aMfgrx8DLS7vLfpeR1c2rrKLr0Q%3D&AccessKeyId=testId&Action=SingleCallByTts&CalledNumber=13000000000&CalledShowNumber=057112345678&Format=XML&OutId=123&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=f7d2d4ef-6d5f-4da4-86ed-88e001a66abb&SignatureVersion=1.0&Timestamp=2017-09-28T14%3A31%3A56Z&TtsCode=TTS_0000000&TtsParam=%7B%22code%22%3A%221234%22%2C%22product%22%3A%22test%22%7D&Version=2017-05-25

三、附加完整的Java签名Demo代码

  1. public class VmsSignDemo {
  2. public static void main(String[] args) throws Exception {
  3. String accessKeyId = "LTAIF0IDDKoh1Ra0";
  4. String accessSecret = "b5uIoiwg0tCeNU2ZwcEfvYl0EmeR2u";
  5. java.text.SimpleDateFormat df = new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
  6. df.setTimeZone(new java.util.SimpleTimeZone(0, "GMT"));// 这里一定要设置GMT时区
  7. java.util.Map<String, String> paras = new java.util.HashMap<String, String>();
  8. // 1. 系统参数
  9. paras.put("SignatureMethod", "HMAC-SHA1");
  10. paras.put("SignatureNonce", java.util.UUID.randomUUID().toString());
  11. paras.put("AccessKeyId", accessKeyId);
  12. paras.put("SignatureVersion", "1.0");
  13. paras.put("Timestamp", df.format(new java.util.Date()));
  14. paras.put("Format", "XML");
  15. // 2. 业务API参数
  16. paras.put("Action", "SingleCallByTts");
  17. paras.put("Version", "2017-05-25");
  18. paras.put("RegionId", "cn-hangzhou");
  19. paras.put("CalledShowNumber", "057112345678");
  20. paras.put("CalledNumber", "13000000000");
  21. paras.put("TtsParam", "{\"code\":\"1234\",\"product\":\"test\"}");
  22. paras.put("TtsCode", "TTS_0000000");
  23. paras.put("OutId", "123");
  24. // 3. 去除签名关键字Key
  25. if (paras.containsKey("Signature"))
  26. paras.remove("Signature");
  27. // 4. 参数KEY排序
  28. java.util.TreeMap<String, String> sortParas = new java.util.TreeMap<String, String>();
  29. sortParas.putAll(paras);
  30. // 5. 构造待签名的字符串
  31. java.util.Iterator<String> it = sortParas.keySet().iterator();
  32. StringBuilder sortQueryStringTmp = new StringBuilder();
  33. while (it.hasNext()) {
  34. String key = it.next();
  35. sortQueryStringTmp.append("&").append(specialUrlEncode(key)).append("=").append(specialUrlEncode(paras.get(key)));
  36. }
  37. String sortedQueryString = sortQueryStringTmp.substring(1);// 去除第一个多余的&符号
  38. StringBuilder stringToSign = new StringBuilder();
  39. stringToSign.append("GET").append("&");
  40. stringToSign.append(specialUrlEncode("/")).append("&");
  41. stringToSign.append(specialUrlEncode(sortedQueryString));
  42. String sign = sign(accessSecret + "&", stringToSign.toString());
  43. // 6. 签名最后也要做特殊URL编码
  44. String signature = specialUrlEncode(sign);
  45. System.out.println(paras.get("SignatureNonce"));
  46. System.out.println("\r\n=========\r\n");
  47. System.out.println(paras.get("Timestamp"));
  48. System.out.println("\r\n=========\r\n");
  49. System.out.println(sortedQueryString);
  50. System.out.println("\r\n=========\r\n");
  51. System.out.println(stringToSign.toString());
  52. System.out.println("\r\n=========\r\n");
  53. System.out.println(sign);
  54. System.out.println("\r\n=========\r\n");
  55. System.out.println(signature);
  56. System.out.println("\r\n=========\r\n");
  57. // 最终打印出合法GET请求的URL
  58. System.out.println("http://dyvmsapi.aliyuncs.com/?Signature=" + signature + sortQueryStringTmp);
  59. }
  60. public static String specialUrlEncode(String value) throws Exception {
  61. return java.net.URLEncoder.encode(value, "UTF-8").replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
  62. }
  63. public static String sign(String accessSecret, String stringToSign) throws Exception {
  64. javax.crypto.Mac mac = javax.crypto.Mac.getInstance("HmacSHA1");
  65. mac.init(new javax.crypto.spec.SecretKeySpec(accessSecret.getBytes("UTF-8"), "HmacSHA1"));
  66. byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8"));
  67. return new sun.misc.BASE64Encoder().encode(signData);
  68. }
  69. }
  70. `
本文导读目录