簽名機制
發送 OpenAPI 請求時,請按照下面的方法對請求進行簽名處理:
關于 Access Key ID 與 Access Key Secret
TSDB 服務會對每個 API 的調用請求進行身份驗證,所以無論使用 HTTP 還是 HTTPS 協議提交請求,都需要在請求中包含由 Access Key ID 與 Access Key Secret 所產生的簽名(Signature)信息。
Access Key ID 和 Access Key Secret 由阿里云官方頒發給訪問者(可以通過阿里云官方網站申請和管理),其中 Access Key ID 用于標識訪問者的身份。
Access Key Secret 是用于加密簽名字符串和服務器端驗證簽名字符串的密鑰,必須嚴格保密,只有阿里云和用戶知道。
簽名方法
發送 OpenAPI 請求時,請按照下面的方法對請求進行簽名處理:
使用請求參數構造規范化的請求字符串(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.3. 對編碼后的參數名稱和值使用英文等號(=)進行連接。
1.4. 把英文等號連接得到的字符串按參數名稱的字典順序依次使用&符號連接,即得到規范化請求字符串。
使用上一步構造的規范化字符串按照下面的規則構造用于計算簽名的字符串。
StringToSign= HTTPMethod + "&" + percentEncode("/") + "&" + percentEncode(CanonicalizedQueryString)
其中 HTTPMethod 是提交請求用的 HTTP 方法,比 GET。
percentEncode(“/”)
是按照1.2中描述的 URL 編碼規則對字符“/”進行編碼得到的值,即“%2F”。percentEncode(CanonicalizedQueryString)
是對第1步中構造的規范化請求字符串按 1.2 中描述的 URL 編碼規則編碼后得到的字符串。
按照 RFC2104 的定義,使用上面的用于簽名的字符串計算簽名 HMAC 值。
注意:計算簽名時使用的 Key 就是用戶持有的 Access Key Secret 并加上一個“&”字符(ASCII:38),使用的哈希算法是 SHA1。
按照 Base64 編碼規則把上面的 HMAC 值編碼成字符串,即得到簽名值(Signature)。
將得到的簽名值作為 Signature 參數添加到請求參數中,即完成對請求簽名的過程。
注意:得到的簽名值在作為最后的請求參數值提交給 TSDB 服務器的時候,要和其他參數一樣,按照 RFC3986 的規則進行 URL 編碼。
示例
以 DescribeHiTSDBInstanceList 為例,簽名前的請求參數字符串為:
AccessKeyId=testid&Action=DescribeHiTSDBInstanceList&Format=JSON&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=ae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion=1.0&Timestamp=2016-01-20T14%3A26%3A15Z&Version=2017-06-01
對這個字符串進行編碼,那么 StringToSign 就是:
GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeHiTSDBInstanceList&Format%3DJSON&RegionId%3Dcn-hangzhou&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3Dae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion%3D1.0&Timestamp%3D2016-01-20T14%253A26%253A15Z&Version%3D2017-06-01
假如使用的 Access Key ID 是“testid”,Access Key Secret 是“testsecret”,用于計算 HMAC 的 Key 就是“testsecret&”,則計算得到的簽名值是:
h/ka/jNO+WZv8Tqgo4a75sp6eTs=
簽名后的請求 URL 為(注意增加了 Signature 參數):
http://hitsdb.aliyuncs.com/?AccessKeyId=testid&Action=DescribeHiTSDBInstanceList&Format=JSON&RegionId=cn-hangzhou&SignatureMethod=HMAC-SHA1&SignatureNonce=ae5bdbeb-9b44-40a1-8bb4-b40784bff686&SignatureVersion=1.0&Timestamp=2016-01-20T14%3A26%3A15Z&Version=2017-06-01&Signature=h%2Fka%2FjNO%2BWZv8Tqgo4a75sp6eTs%3D
調用接口 DescribeHiTSDBInstanceList 的 Java 示例如下:
public static void hitsdbOpenAPI() throws NoSuchAlgorithmException, InvalidKeyException, IOException {
//AK 與 SK
String accessKey = "testid";
String accessSecret = "testsecret";
//公共參數
Map<String, String> parameters = new TreeMap<String, String>();
parameters.put("Format", "JSON");
parameters.put("Action", "DescribeHiTSDBInstanceList");//調用 DescribeDrdsInstances 接口
parameters.put("Version", "2017-06-01");
parameters.put("AccessKeyId", accessKey);
parameters.put("SignatureMethod", "HMAC-SHA1");
parameters.put("Timestamp", getISO8601Time());
parameters.put("SignatureVersion", "1.0");
parameters.put("SignatureNonce", UUID.randomUUID().toString());
parameters.put("RegionId", "cn-hangzhou");
StringBuilder paramStr = new StringBuilder();
//拼接請求參數
for(Map.Entry<String, String> entry : parameters.entrySet()) {
paramStr.append(percentEncode(entry.getKey())).append("=").append(percentEncode(entry.getValue())).append("&");
}
paramStr.deleteCharAt(paramStr.length()-1);
//計算簽名
StringBuilder stringToSign = new StringBuilder();
stringToSign.append("GET").append("&").append(percentEncode("/"))
.append("&").append(percentEncode(paramStr.toString()));
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(new SecretKeySpec((accessSecret + "&").getBytes("UTF-8"),"HmacSHA1"));
byte[] signData = mac.doFinal(stringToSign.toString().getBytes("UTF-8"));
String signStr = Base64Helper.encode(signData);
//拼接 URL
String requestUrl = "http://hitsdb.aliyuncs.com/?" + paramStr.toString() +
"&Signature=" + percentEncode(signStr);
//準備發送 HTTP 請求
URL url = new URL(requestUrl);
HttpURLConnection httpConn = (HttpURLConnection)url.openConnection();
httpConn.setRequestMethod("GET");
httpConn.setDoOutput(true);
httpConn.setDoInput(true);
httpConn.setUseCaches(false);
httpConn.connect();
InputStream content = httpConn.getInputStream();
ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
byte[] buff = new byte[1024];
while(true) {
final int read = content.read(buff);
if(read == -1) break;
outputStream.write(buff,0,read);
}
System.out.println(new String(outputStream.toByteArray()));;
}
public static String percentEncode(String value) throws UnsupportedEncodingException{
return value != null ? URLEncoder.encode(value, "UTF-8").replace("+", "%20")
.replace("*", "%2A").replace("%7E", "~") : null;
}
static String getISO8601Time() {
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
df.setTimeZone(new SimpleTimeZone(0, "GMT"));
return df.format(new Date());
}
}