文档

HTTP协议及签名

更新时间:

本文为您介绍HTTP协议及签名详细说明,方便其它语言能快速实现。

背景信息

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

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

    1. 通过调用语音呼叫API,例如文本转语音外呼接口,来成功发起呼叫。

    2. 平台成功收到请求后发送给运营商,等用户最终挂断电话后,平台会有最终的状态消息确认,就是消息回执对应的协议是:

      • 发送API采用Rest协议:签名算法使用了阿里云的POP协议。

      • 发送后消息回执:采用的是阿里云的消息中间件MNS来实现。

协议说明

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

  1. 文本转语音API的HTTP协议包示例。

    • 请求示例:

      GET /?Signature=ACaeddgMkXN%2FRu7%2BnpPqvgY%2Fyl4%3D&AccessKeyId=LTAIF0IDDKoh****&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
      HTTP/1.1
      Host: dyvmsapi.aliyuncs.com
      ...
              
    • 返回示例:

      HTTP/1.1 200 OK
      ...
      <?xml version='1.0' encoding='UTF-8'?>
      <SingleCallByTtsResponse>
      <Message>OK</Message>
      <RequestId>220F7831-A8A9-4A7F-9A55-272346F61B14</RequestId>
      <Code>OK</Code>
      <CallId>113277672277^100610220432</CallId>
      </SingleCallByTtsResponse>
      
              
  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文档描述

  3. 生成签名

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

    1. 请求参数

      1. 请求参数包括系统参数和业务参数,不要遗漏。

      2. 参数Key中不能包含最终要生成的签名Key(Signature是关键字)。

      3. 参考代码如下:

        // 阿里云账号AccessKey ID拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户
        // 此处以把AccessKey ID和 AccessKey Secret 保存在环境变量为例说明。 您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey ID和 AccessKey Secret 保存到代码里,会存在密钥泄漏风险
                    String accessKeyId = System.getenv("VMS_AK_ENV");
                    String accessSecret = System.getenv("VMS_SK_ENV");
                    java.text.SimpleDateFormat df = new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
                    df.setTimeZone(new java.util.SimpleTimeZone(0, "GMT"));// 这里一定要设置GMT时区
                    java.util.Map<String, String> paras = new java.util.HashMap<String, String>();
                    // 1. 系统参数
                    paras.put("SignatureMethod", "HMAC-SHA1");
                    paras.put("SignatureNonce", java.util.UUID.randomUUID().toString());
                    paras.put("AccessKeyId", accessKeyId);
                    paras.put("SignatureVersion", "1.0");
                    paras.put("Timestamp", df.format(new java.util.Date()));
                    paras.put("Format", "XML");
                    // 2. 业务API参数
                    paras.put("Action", "SingleCallByTts");
                    paras.put("Version", "2017-05-25");
                    paras.put("RegionId", "cn-hangzhou");
                    paras.put("CalledShowNumber", "057112345678");
                    paras.put("CalledNumber", "13000000000");
                    paras.put("TtsParam", "{\"code\":\"1234\",\"product\":\"test\"}");
                    paras.put("TtsCode", "TTS_0000000");
                    paras.put("OutId", "123");
                    // 3. 去除签名关键字Key
                    if (paras.containsKey("Signature"))
                        paras.remove("Signature");
                    
    2. 根据参数Key排序(顺序)

      参考代码如下:

      java.util.TreeMap<String, String> sortParas = new java.util.TreeMap<String, String>();
      sortParas.putAll(paras);
                  
    3. 构造待签名的请求串

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

        public static String specialUrlEncode(String value) throws Exception {
            return java.net.URLEncoder.encode(value, "UTF-8").replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
        }
                    
      2. 构造待签名的请求。把排序后的参数顺序拼接成如下格式:specialUrlEncode(参数Key) + "=" + specialUrlEncode(参数值)。参考代码如下:

        java.util.Iterator<String> it = sortParas.keySet().iterator();
        StringBuilder sortQueryStringTmp = new StringBuilder();
        while (it.hasNext()) {
            String key = it.next();
            sortQueryStringTmp.append("&").append(specialUrlEncode(key)).append("=").append(specialUrlEncode(paras.get(key)));
        }
        String sortedQueryString = sortQueryStringTmp.substring(1);// 去除第一个多余的&符号
                    
      3. 打印上面的sortQueryString结果如下:

        AccessKeyId%3DtestId&Action%3DSingleCallByTts&CalledNumber%3D13000000000&CalledShowNumber%3D057112345678&Format%3DXML&OutId%3D123&RegionId%3Dcn-hangzhou&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3Df7d2d4ef-6d5f-4da4-86ed-88e001a66abb&SignatureVersion%3D1.0&Timestamp%3D2017-09-28T14%253A31%253A56Z&TtsCode%3DTTS_0000000&TtsParam%3D%257B%2522code%2522%253A%25221234%2522%252C%2522product%2522%253A%2522test%2522%257D&Version%3D2017-05-25
                    
      4. 对应的未URL编码的值(方便用户对比):

        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
        
                    
      5. 按POP的签名规则拼接成最终的待签名串,规则如下:HTTPMethod + “&” + specialUrlEncode(“/”) + ”&” + specialUrlEncode(sortedQueryString)。参考代码如下:

        StringBuilder stringToSign = new StringBuilder();
        stringToSign.append("GET").append("&");
        stringToSign.append(specialUrlEncode("/")).append("&");
        stringToSign.append(specialUrlEncode(sortedQueryString));
                    
      6. 这就完成了待签名的请求字符串,打印结果如下:

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

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

        String sign = sign(accessSecret + "&", stringToSign.toString());
        
        public static String sign(String accessSecret, String stringToSign) throws Exception {
            javax.crypto.Mac mac = javax.crypto.Mac.getInstance("HmacSHA1");
            mac.init(new javax.crypto.spec.SecretKeySpec(accessSecret.getBytes("UTF-8"), "HmacSHA1"));
            byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8"));
            return new sun.misc.BASE64Encoder().encode(signData);
        }
                    
      • 参数说明:

        1. accessSecret:您的AccessKey ID对应的密钥AccessSecret。

          说明

          POP要求需要在后面多加一个“&”字符,即accessSecret + “&”。

        2. stringToSign:即第三步生成的待签名请求串。

      • 签名后的结果打印如下:

        aMfgrx8DLS7vLfpeR1c2rrKLr0Q=
                    
    5. 增加签名结果到请求参数中,发送请求

      重要

      签名也要做特殊URL编码。

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

      最终完整的GET请求HTTP为:

      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代码

public class VmsSignDemo {

     public static void main(String[] args) throws Exception {
            // 阿里云账号AccessKey ID拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户
            // 此处以把AccessKey ID和 AccessKey Secret 保存在环境变量为例说明。 您也可以根据业务需要,保存到配置文件里
            // 强烈建议不要把 AccessKey ID和 AccessKey Secret 保存到代码里,会存在密钥泄漏风险
            String accessKeyId = System.getenv("VMS_AK_ENV");
            String accessSecret = System.getenv("VMS_SK_ENV");
            java.text.SimpleDateFormat df = new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
            df.setTimeZone(new java.util.SimpleTimeZone(0, "GMT"));// 这里一定要设置GMT时区
            java.util.Map<String, String> paras = new java.util.HashMap<String, String>();
            // 1. 系统参数
            paras.put("SignatureMethod", "HMAC-SHA1");
            paras.put("SignatureNonce", java.util.UUID.randomUUID().toString());
            paras.put("AccessKeyId", accessKeyId);
            paras.put("SignatureVersion", "1.0");
            paras.put("Timestamp", df.format(new java.util.Date()));
            paras.put("Format", "XML");
            // 2. 业务API参数
            paras.put("Action", "SingleCallByTts");
            paras.put("Version", "2017-05-25");
            paras.put("RegionId", "cn-hangzhou");
            paras.put("CalledShowNumber", "05711234****");
            paras.put("CalledNumber", "1380000****");
            paras.put("TtsParam", "{\"code\":\"1234\",\"product\":\"test\"}");
            paras.put("TtsCode", "TTS_0000000");
            paras.put("OutId", "123");
            // 3. 去除签名关键字Key
            if (paras.containsKey("Signature"))
                paras.remove("Signature");
            // 4. 参数KEY排序
            java.util.TreeMap<String, String> sortParas = new java.util.TreeMap<String, String>();
            sortParas.putAll(paras);
            // 5. 构造待签名的字符串
            java.util.Iterator<String> it = sortParas.keySet().iterator();
            StringBuilder sortQueryStringTmp = new StringBuilder();
            while (it.hasNext()) {
                String key = it.next();
                sortQueryStringTmp.append("&").append(specialUrlEncode(key)).append("=").append(specialUrlEncode(paras.get(key)));
            }
            String sortedQueryString = sortQueryStringTmp.substring(1);// 去除第一个多余的&符号
            StringBuilder stringToSign = new StringBuilder();
            stringToSign.append("GET").append("&");
            stringToSign.append(specialUrlEncode("/")).append("&");
            stringToSign.append(specialUrlEncode(sortedQueryString));
            String sign = sign(accessSecret + "&", stringToSign.toString());
            // 6. 签名最后也要做特殊URL编码
            String signature = specialUrlEncode(sign);
            System.out.println(paras.get("SignatureNonce"));
            System.out.println("\r\n=========\r\n");
            System.out.println(paras.get("Timestamp"));
            System.out.println("\r\n=========\r\n");
            System.out.println(sortedQueryString);
            System.out.println("\r\n=========\r\n");
            System.out.println(stringToSign.toString());
            System.out.println("\r\n=========\r\n");
            System.out.println(sign);
            System.out.println("\r\n=========\r\n");
            System.out.println(signature);
            System.out.println("\r\n=========\r\n");
            // 最终打印出合法GET请求的URL
            System.out.println("http://dyvmsapi.aliyuncs.com/?Signature=" + signature + sortQueryStringTmp);
        }
        public static String specialUrlEncode(String value) throws Exception {
            return java.net.URLEncoder.encode(value, "UTF-8").replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
        }
        public static String sign(String accessSecret, String stringToSign) throws Exception {
            javax.crypto.Mac mac = javax.crypto.Mac.getInstance("HmacSHA1");
            mac.init(new javax.crypto.spec.SecretKeySpec(accessSecret.getBytes("UTF-8"), "HmacSHA1"));
            byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8"));
            return new sun.misc.BASE64Encoder().encode(signData);
        }
}
            
  • 本页导读 (1)
文档反馈