PolarDB-X 1.0-API參考-1.0（2017版本）-OpenAPI使用-簽名機制

關于 Access Key ID 與 Access Key Secret

• PolarDB-X 服務會對每個 API 的調用請求進行身份驗證，是以無論使用 HTTP 還是 HTTPS 協定送出請求，都需要在請求中包含由 Access Key ID 與 Access Key Secret 所産生的簽名（Signature）資訊。
• Access Key ID 和 Access Key Secret 由阿裡雲官方頒發給通路者（可以通過阿裡雲官方網站申請和管理），其中 Access Key ID 用于辨別通路者的身份。
• Access Key Secret 是用于加密簽名字元串和伺服器端驗證簽名字元串的密鑰，必須嚴格保密，隻有阿裡雲和使用者知道。

簽名方法

發送 OpenAPI 請求時，請按照下面的方法對請求進行簽名處理：

1. 使用請求參數構造規範化的請求字元串（Canonicalized Query String）。1.1. 按照參數名稱的字典順序對請求中所有的請求參數（包括文檔中描述的“公共請求參數”和給定了的請求接口的自定義參數，但不能包括“公共請求參數”中提到 Signature 參數本身）進行排序。注意：使用 GET 方法送出請求時，這些參數就是請求 URI 中的參數部分（即 URI 中“?”之後由“&”連接配接的部分）。1.2. 對每個請求參數的名稱和值進行編碼。名稱和值要使用 UTF-8字元集進行 URL 編碼，URL 編碼的編碼規則是：

• • 對于字元 A-Z、a-z、0-9以及字元“-”、“_”、“.”、“~”不編碼；
  • 對于其他字元編碼成“%XY”的格式，其中 XY 是字元對應 ASCII 碼的16進制表示。比如英文的雙引号（”）對應的編碼就是%22;
  • 對于擴充的 UTF-8 字元，編碼成“%XY%ZA…”的格式；

  • 英文空格（ ）要被編碼是%20，而不是加号（+）。

    注意：一般支援 URL 編碼的庫（比如 Java 中的 java.net.URLEncoder）都是按照“application/x-www-form-urlencoded”的 MIME 類型的規則進行編碼的。實作時可以直接使用這類方式進行編碼，把編碼後的字元串中加号（+）替換成%20、星号（*）替換成%2A、%7E 替換回波浪号（~），即可得到上述規則描述的編碼字元串。

1. 1.3. 對編碼後的參數名稱和值使用英文等号（=）進行連接配接。

   1.4. 把英文等号連接配接得到的字元串按參數名稱的字典順序依次使用&符号連接配接，即得到規範化請求字元串。

2. 使用上一步構造的規範化字元串按照下面的規則構造用于計算簽名的字元串。

1. 1. StringToSign=

   2. HTTPMethod + "&" +

   3. percentEncode("/") + "&" +

   4. percentEncode(CanonicalizedQueryString)

• • 其中 HTTPMethod 是送出請求用的 HTTP 方法，比 GET。
  • percentEncode（“/”）是按照1.2中描述的 URL 編碼規則對字元“/”進行編碼得到的值，即“%2F”。
  • percentEncode（CanonicalizedQueryString）是對第1步中構造的規範化請求字元串按 1.2 中描述的 URL 編碼規則編碼後得到的字元串。

1. 按照 RFC2104 的定義，使用上面的用于簽名的字元串計算簽名 HMAC 值。

   注意：計算簽名時使用的 Key 就是使用者持有的 Access Key Secret 并加上一個“&”字元（ASCII:38），使用的雜湊演算法是 SHA1。

2. 按照 Base64 編碼規則把上面的 HMAC 值編碼成字元串，即得到簽名值（Signature）。

3. 将得到的簽名值作為 Signature 參數添加到請求參數中，即完成對請求簽名的過程。

   注意：得到的簽名值在作為最後的請求參數值送出給 PolarDB-X 伺服器的時候，要和其他參數一樣，按照 RFC3986 的規則進行 URL 編碼）。

示例

以 DescribeDrdsInstances 為例，簽名前的請求參數字元串為：

1. AccessKeyId=testid&Action=DescribeDrdsInstances&Format=XML&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=ae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion=1.0&Timestamp=2016-01-20T14%3A26%3A15Z&Version=2015-04-13

對這個字元串進行編碼，那麼 StringToSign 就是：

1. GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeDrdsInstances&Format%3DXML&RegionId%3Dcn-hangzhou&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3Dae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion%3D1.0&Timestamp%3D2016-01-20T14%253A26%253A15Z&Version%3D2015-04-13

假如使用的 Access Key ID 是“testid”，Access Key Secret 是“testsecret”，用于計算 HMAC 的 Key 就是“testsecret&”，則計算得到的簽名值是：

1. h/ka/jNO+WZv8Tqgo4a75sp6eTs=

簽名後的請求 URL 為（注意增加了 Signature 參數）：

1. http://drds.aliyuncs.com/?AccessKeyId=testid&Action=DescribeDrdsInstances&Format=XML&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=ae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion=1.0&Timestamp=2016-01-20T14%3A26%3A15Z&Version=2015-04-13&Signature=h%2Fka%2FjNO%2BWZv8Tqgo4a75sp6eTs%3D

調用接口 DescribeDrdsInstances 的 Java 示例如下：

1. public static void drdsOpenAPI() throws NoSuchAlgorithmException, InvalidKeyException, IOException {

2. //AK 與 SK

3. String accessKey = "testid";

4. String accessSecret = "testsecret";

5. //公共參數

6. Map<String, String> parameters = new TreeMap<String, String>();

7. parameters.put("Format", "JSON");

8. parameters.put("Action", "DescribeDrdsInstances");//調用 DescribeDrdsInstances 接口

9. parameters.put("Version", "2015-04-13");

10. parameters.put("AccessKeyId", accessKey);

11. parameters.put("SignatureMethod", "HMAC-SHA1");

12. parameters.put("Timestamp", getISO8601Time());

13. parameters.put("SignatureVersion", "1.0");

14. parameters.put("SignatureNonce", UUID.randomUUID().toString());

15. parameters.put("RegionId", "cn-hangzhou");

16. StringBuilder paramStr = new StringBuilder();

17. //拼接請求參數

18. for(Map.Entry<String, String> entry : parameters.entrySet()) {

19. paramStr.append(percentEncode(entry.getKey())).append("=").append(percentEncode(entry.getValue())).append("&");

20. }

21. paramStr.deleteCharAt(paramStr.length()-1);

22. //計算簽名

23. StringBuilder stringToSign = new StringBuilder();

24. stringToSign.append("GET").append("&").append(percentEncode("/"))

25. .append("&").append(percentEncode(paramStr.toString()));

26. Mac mac = Mac.getInstance("HmacSHA1");

27. mac.init(new SecretKeySpec((accessSecret + "&").getBytes("UTF-8"),"HmacSHA1"));

28. byte[] signData = mac.doFinal(stringToSign.toString().getBytes("UTF-8"));

29. String signStr = Base64Helper.encode(signData);

30. //拼接 URL

31. String requestUrl = "http://drds.aliyuncs.com/?" + paramStr.toString() +

32. "&Signature=" + percentEncode(signStr);

33. //準備發送 HTTP 請求

34. URL url = new URL(requestUrl);

35. HttpURLConnection httpConn = (HttpURLConnection)url.openConnection();

36. httpConn.setRequestMethod("GET");

37. httpConn.setDoOutput(true);

38. httpConn.setDoInput(true);

39. httpConn.setUseCaches(false);

40. httpConn.connect();

41. InputStream content = httpConn.getInputStream();

42. ByteArrayOutputStream outputStream = new ByteArrayOutputStream();

43. byte[] buff = new byte[1024];

44. while(true) {

45. final int read = content.read(buff);

46. if(read == -1) break;

47. outputStream.write(buff,0,read);

48. }

49. System.out.println(new String(outputStream.toByteArray()));;

50. }

51. public static String percentEncode(String value) throws UnsupportedEncodingException{

52. return value != null ? URLEncoder.encode(value, "UTF-8").replace("+", "%20")

53. .replace("*", "%2A").replace("%7E", "~") : null;

54. }

55. static String getISO8601Time() {

56. SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");

57. df.setTimeZone(new SimpleTimeZone(0, "GMT"));

58. return df.format(new Date());

59. }

60. }