當所用程式設計語言沒有對應的SDK,或需要自行控制相依元件時,可以直接調用OpenAPI擷取Token。本文介紹請求參數、簽名機制和響應格式,並提供Java和Python樣本。
準備訪問憑證
調用介面需要AccessKey ID和AccessKey Secret。將訪問憑證配置到運行環境的 ALIYUN_AK_ID 和 ALIYUN_AK_SECRET 環境變數中,範例程式碼從環境變數讀取憑證。
AccessKey Secret和Token均為敏感資訊,不要寫入公開代碼或日誌。以下樣本會輸出包含Token的響應,整合到應用時應妥善保管。
程式碼範例
以下樣本通過HTTPS GET請求擷取Token。響應中的 Token.Id 為Token值,Token.ExpireTime 為到期時間戳記,單位為秒。
Java
使用JDK 8或更高版本,並添加以下Maven依賴。
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>3.9.1</version>
</dependency>
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Base64;
import java.util.Map;
import java.util.StringJoiner;
import java.util.TreeMap;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
public class CreateToken {
private static String encode(String value) throws Exception {
return URLEncoder.encode(value, "UTF-8")
.replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
}
public static void main(String[] args) throws Exception {
String accessKeyId = System.getenv("ALIYUN_AK_ID");
String accessKeySecret = System.getenv("ALIYUN_AK_SECRET");
if (accessKeyId == null || accessKeyId.isEmpty()
|| accessKeySecret == null || accessKeySecret.isEmpty()) {
throw new IllegalArgumentException("Set ALIYUN_AK_ID and ALIYUN_AK_SECRET.");
}
String endpoint = "https://nlsmeta.ap-southeast-1.aliyuncs.com/";
Map<String, String> parameters = new TreeMap<>();
parameters.put("AccessKeyId", accessKeyId);
parameters.put("Action", "CreateToken");
parameters.put("Version", "2019-07-17");
parameters.put("RegionId", "ap-southeast-1");
parameters.put("Format", "JSON");
parameters.put("SignatureMethod", "HMAC-SHA1");
parameters.put("SignatureVersion", "1.0");
parameters.put("SignatureNonce", UUID.randomUUID().toString());
parameters.put("Timestamp", Instant.now().truncatedTo(ChronoUnit.SECONDS).toString());
StringJoiner query = new StringJoiner("&");
for (Map.Entry<String, String> entry : parameters.entrySet()) {
query.add(encode(entry.getKey()) + "=" + encode(entry.getValue()));
}
String canonicalQuery = query.toString();
String stringToSign = "GET&" + encode("/") + "&" + encode(canonicalQuery);
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(new SecretKeySpec((accessKeySecret + "&").getBytes(StandardCharsets.UTF_8), "HmacSHA1"));
String signature = Base64.getEncoder().encodeToString(
mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8)));
Request request = new Request.Builder()
.url(endpoint + "?" + canonicalQuery + "&Signature=" + encode(signature))
.get().build();
OkHttpClient client = new OkHttpClient();
try (Response response = client.newCall(request).execute()) {
String body = response.body() == null ? "" : response.body().string();
if (!response.isSuccessful()) {
throw new IllegalStateException("HTTP " + response.code() + ": " + body);
}
System.out.println(body);
}
}
}
Python
使用Python 3.4或更高版本,安裝Requests庫。樣本使用Python 3.14.7。
pip install requests
import base64
import hashlib
import hmac
import os
import uuid
from datetime import datetime, timezone
from urllib.parse import quote
import requests
def encode(value):
return quote(value, safe="-_.~")
def create_token():
access_key_id = os.environ["ALIYUN_AK_ID"]
access_key_secret = os.environ["ALIYUN_AK_SECRET"]
endpoint = "https://nlsmeta.ap-southeast-1.aliyuncs.com/"
parameters = {
"AccessKeyId": access_key_id,
"Action": "CreateToken",
"Version": "2019-07-17",
"RegionId": "ap-southeast-1",
"Format": "JSON",
"SignatureMethod": "HMAC-SHA1",
"SignatureVersion": "1.0",
"SignatureNonce": str(uuid.uuid4()),
"Timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
}
canonical_query = "&".join(
encode(key) + "=" + encode(value)
for key, value in sorted(parameters.items())
)
string_to_sign = "GET&" + encode("/") + "&" + encode(canonical_query)
signature = base64.b64encode(hmac.new(
(access_key_secret + "&").encode("utf-8"),
string_to_sign.encode("utf-8"), hashlib.sha1
).digest()).decode("ascii")
response = requests.get(
endpoint + "?" + canonical_query + "&Signature=" + encode(signature),
timeout=20,
)
if response.status_code != 200:
raise RuntimeError("HTTP {}: {}".format(response.status_code, response.text))
return response.text
if __name__ == "__main__":
print(create_token())
請求說明
介面支援GET和POST方法,使用阿里雲POP協議進行簽名。HTTP和HTTPS請求的參數相同,建議使用HTTPS。
服務地址
Endpoint:https://nlsmeta.ap-southeast-1.aliyuncs.com/,RegionId:ap-southeast-1,API版本:2019-07-17。
請求參數
|
名稱 |
類型 |
必選 |
說明 |
|
AccessKeyId |
String |
是 |
AccessKey ID。 |
|
Action |
String |
是 |
介面名稱,固定為 |
|
Version |
String |
是 |
API版本,固定為 |
|
Format |
String |
否 |
響應格式。設為 |
|
RegionId |
String |
是 |
地區ID,固定為 |
|
Timestamp |
String |
是 |
請求時間戳記,使用UTC時間,格式為 |
|
SignatureMethod |
String |
是 |
簽名演算法,固定為 |
|
SignatureVersion |
String |
是 |
簽名演算法版本,固定為 |
|
SignatureNonce |
String |
是 |
唯一隨機字串,用於防止重放攻擊,每次請求不得重複。可使用UUID,例如 |
|
Signature |
String |
是 |
根據除Signature外的全部請求參數計算得到的簽名,計算方法見下文簽名機制。 |
要求標頭與參數傳遞
GET請求將參數放在URL查詢字串中;POST請求將參數放在請求體中。
|
要求標頭 |
必選 |
說明 |
|
Host |
否 |
服務網域名稱,通常由HTTP用戶端根據Endpoint自動化佈建。 |
|
Accept |
否 |
可設定為 |
|
Content-Type |
POST必選 |
POST請求設定為 |
請求格式如下,<encoded-parameters> 表示URL編碼後的參數字串,包含Signature。POST請求計算簽名時使用 POST,不能直接複用GET簽名。
GET
GET /?<encoded-parameters> HTTP/1.1
Host: <endpoint-host>
Accept: application/json
POST
POST / HTTP/1.1
Host: <endpoint-host>
Accept: application/json
Content-Type: application/x-www-form-urlencoded
<encoded-parameters>
簽名機制
每個請求都必須攜帶簽名。用戶端使用AccessKey Secret計算HMAC-SHA1訊息認證碼;服務端根據請求中的AccessKey ID尋找對應密鑰,並校正簽名,以驗證身份和請求完整性。
構造正常化請求字串
排除Signature參數,按參數名進行區分大小寫字典排序。
對參數名和參數值分別進行UTF-8 URL編碼:
A-Z、a-z、0-9、-、_、.、~不編碼。其他字元按其UTF-8位元組編碼為
%XY,例如雙引號編碼為%22。空格編碼為
%20,不能編碼為加號+。
使用
=串連編碼後的參數名和值,再用&串連各參數對。第一個參數前不加&。
percentEncode(name1)=percentEncode(value1)&percentEncode(name2)=percentEncode(value2)
Java的 URLEncoder 按表單規則編碼,需將編碼結果中的 + 替換為 %20、* 替換為 %2A、%7E 替換為 ~。
構造待簽名字串
將大寫HTTP方法、編碼後的請求路徑 / 和再次編碼的正常化請求字串用 & 串連。
StringToSign = HTTPMethod + "&" + percentEncode("/") + "&" + percentEncode(CanonicalizedQueryString)
計算並添加簽名
在AccessKey Secret末尾追加
&,作為HMAC-SHA1密鑰。使用UTF-8編碼的密鑰和待簽名字串計算HMAC-SHA1,再對結果進行Base64編碼。
對Base64結果進行URL編碼,以
Signature=<encoded-signature>的形式加入請求參數。
Signature = Base64(HMAC-SHA1(AccessKeySecret + "&", StringToSign))
簽名校正樣本
以下固定參數用於離線核對簽名實現。AccessKey為虛擬值,Timestamp已到期,不能用於實際擷取Token。
AccessKeyId: my_access_key_id
AccessKeySecret: my_access_key_secret
Action: CreateToken
Format: JSON
SignatureMethod: HMAC-SHA1
SignatureVersion: 1.0
SignatureNonce: b924c8c3-6d03-4c5d-ad36-d984d3116788
Timestamp: 2019-04-18T08:32:31Z
HTTPMethod: GET
正常化請求字串:
AccessKeyId=my_access_key_id&Action=CreateToken&Format=JSON&RegionId=ap-southeast-1&SignatureMethod=HMAC-SHA1&SignatureNonce=b924c8c3-6d03-4c5d-ad36-d984d3116788&SignatureVersion=1.0&Timestamp=2019-04-18T08%3A32%3A31Z&Version=2019-07-17
待簽名字串:
GET&%2F&AccessKeyId%3Dmy_access_key_id%26Action%3DCreateToken%26Format%3DJSON%26RegionId%3Dap-southeast-1%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3Db924c8c3-6d03-4c5d-ad36-d984d3116788%26SignatureVersion%3D1.0%26Timestamp%3D2019-04-18T08%253A32%253A31Z%26Version%3D2019-07-17
Base64簽名:
4TdrOuLHXJU+5C6s927Wkq2h+wc=
URL編碼後的簽名參數:
Signature=4TdrOuLHXJU%2B5C6s927Wkq2h%2Bwc%3D
響應說明
以下說明適用於 Format=JSON。GET和POST方法的響應格式相同。
成功響應
HTTP狀態代碼為200,主要欄位如下。
|
欄位 |
類型 |
說明 |
|
Token |
Object |
包含Token值和到期時間。 |
|
Token.Id |
String |
Token值。 |
|
Token.ExpireTime |
Long |
Token的到期時間,以Unix時間戳記表示,單位為秒;不是有效時間長度。例如1553825814對應UTC時間2019-03-29 02:16:54,Token在該時間之前有效。 |
響應中的Token欄位樣本如下。
{
"Token": {
"Id": "<token>",
"ExpireTime": 1553825814
}
}
失敗響應
HTTP狀態代碼為非200,根據Code和Message檢查請求參數。
|
欄位 |
類型 |
說明 |
|
RequestId |
String |
請求ID,可用於排查問題。 |
|
Code |
String |
錯誤碼。 |
|
Message |
String |
錯誤說明。 |
例如,AccessKey ID不存在時,返回HTTP 404,響應中包含以下欄位。
{
"RequestId": "<request-id>",
"Code": "InvalidAccessKeyId.NotFound",
"Message": "Specified access key is not found."
}
相關文檔
臨時調試時,可通過控制台擷取Token。
使用SDK封裝簽名和請求邏輯時,請參見通過SDK擷取Token。