平台技術-API呼叫協議
開放平台(TOP)的API是基於HTTP協定來呼叫的,開發者(ISV)可以直接使用TOP提供的官方SDK(支援多種語言,包含了請求的封裝,簽章加密,回應解釋,效能最佳化等)來調用,也可以根據TOP的協定來封裝HTTP請求進行調用,以下主要是針對自行封裝HTTP請求進行API調用的原理進行詳細解說。
呼叫流程
根據TOP的協定:填充參數> 產生簽章> 拼裝HTTP請求> 發起HTTP請求> 得到HTTP回應> 解釋json/xml結果,以下是大體的呼叫過程示意圖:
#呼叫入口
#呼叫API的服務URL位址,開放平台目前提供了4個環境給ISV使用:沙箱測試環境,正式測試環境,正式環境,海外環境。
- 沙箱測試環境: ISV軟體的測試環境,套用建立後即可使用。此環境提供簡化版的淘寶網,支援大部分場景的API調用,沙箱環境的權限和流量均無限制,可放開使用。
- 正式測試環境: ISV軟體上線前的正式模擬環境,應用創建成功後即可使用。此環境主要是針對部分無法在沙箱完成測試的場景使用,限制API呼叫為5000次/天,授權使用者數量為5個,所能呼叫的API與應用程式擁有的權限能力一致。
- 正式環境: ISV軟體上線之後使用的環境,此環境的入口與正式測試環境一致,只不過應用上線之後,流量限制會進行打開,具體流量限制與應用所屬類目有關,例如服務市場類的應用,限制API呼叫為100萬次/天。
- 海外環境: 海外環境也屬於正式環境的一種,主要給海外(歐美國家)ISV使用,對於海外的ISV,使用海外環境會比國內環境的性能高一倍。
#呼叫環境 | #服務位址(HTTP) | 服務位址(HTTPS) |
---|---|---|
沙箱環境 | http://gw.api.tbsandbox.com/router/rest | #https:// gw.api.tbsandbox.com/router/rest |
正式環境 | http://gw.api.taobao.com/router/rest | #https://eco.taobao.com/router/rest |
海外環境 | http://api.taobao.com/router/rest | https://api.taobao.com/router/rest |
公共參數
呼叫任何一個API都必須傳入的參數,目前支援的公共參數有:
##參數名稱參數類型是否必須參數描述#methodString ##是API介面名稱。 app_keyString是sessionString否使用者登入授權成功後,TOP頒發給應用的授權信息,詳細介紹請點擊這裡。當此API文件的標籤上註明:“需要授權”,則此參數必傳;“不需要授權”,則此參數不需要傳;“可選授權”,則此參數為可選。 timestampString是時間戳,格式為yyyy-MM-dd HH:mm:ss,時區為GMT 8,例如:2016-01-01 12:00:00。淘寶API服務端允許客戶端請求最大時間誤差為10分鐘。 formatString否回應格式。預設為xml格式,可選值:xml,json。 vString是API協定版本,可選值:2.0。 partner_idString否合作夥伴身分識別識別。 target_app_keyString#否被呼叫的目標AppKey,僅當被呼叫的API為第三方ISV提供時有效。 simplifyBoolean否是否採用精簡JSON回傳格式,僅當format=json時有效,預設值為:false。 sign_methodString是簽署的摘要演算法,可選值為:hmac,md5。 signString是API輸入參數簽章結果,簽章演算法參考下面的介紹。TOP分配給應用程式的AppKey。 這裡要注意正式環境和沙箱環境的AppKey是不同的(包括AppSecret),使用時要注意區分;進入開放平台控制台「應用管理-概覽」 和「應用程式管理-沙箱環境管理」可分別查看正式環境及沙箱環境的AppKey、AppSecret | |||
業務參數
API呼叫除了必須包含公共參數外,如果API本身有業務級的參數也必須傳入,每個API的業務級參數請考API文件說明。
簽名演算法
為了防止API呼叫過程中被駭客惡意竄改,呼叫任何一個API都需要攜帶簽名,TOP服務端會根據請求參數,對簽章進行驗證,簽章不合法的請求將會被拒絕。 TOP目前支援的簽章演算法有兩種:MD5(sign_method=md5),HMAC_MD5(sign_method=hmac),簽章大體流程如下:
- 對所有API請求參數(包含公用參數與商業參數,但除去sign參數和byte[]類型的參數),依參數名稱的ASCII碼表的順序排序。如:foo=1, bar=2, foo_bar=3, foobar=4排序後的順序是bar=2, foo=1, foo_bar=3, foobar=4。
- 將排序好的參數名稱和參數值拼裝在一起,根據上面的範例得到的結果為:bar2foo1foo_bar3foobar4。
- 把拼裝好的字串採用utf-8編碼,使用簽章演算法對編碼後的位元組流進行摘要。如果使用MD5演算法,則需要在拼裝的字串前後加上app的secret後,再進行摘要,如:md5(secret bar2foo1foo_bar3foobar4 secret);如果使用HMAC_MD5演算法,則需要用app的secret初始化摘要後,再進行進行摘要,如:hmac_md5(bar2foo1foo_bar3foobar4)。
- 將摘要得到的位元組流結果使用十六進位表示,如:hex(“helloworld”.getBytes(“utf-8”)) = “68656C6C6F776F726C64”
#說明:MD5和HMAC_MD5都是128位元長度的摘要演算法,用16進位表示,一個十六進位的字元能表示4個位,所以簽章後的字串長度固定為32個十六進位字符。
JAVA簽名範例程式碼
# String[] keys = params.keySet().toArray(new String[0]);
Arrays.sort(keys);
/// 在一起
StringBuilder query = new StringBuilder();
if (Constants.SIGN_METHOD_MD5.equals(signMethod)) p. for (String key : keys) {
String value = 參數.append(value);
}
}
// 第三步驟:使用MD5/HMAC加密
byte[] bytes;
= encryptHMAC (query.toString(), secret);
} else {
query.append(secret);
# // 第四步:將二元轉換為大寫的十六進位
return byte2hex(bytes);
}
public static byte[] encryptHMAC(String data, static byte[] encryptHMAC(String data, static byte[] encryptHMAC(String data, static byte[] encryptHMAC(String data, static byte {
byte[] bytes = null;
try {
SecretKey secretKey Mac mac = Mac.getInstance(secretKey .getAlgorithm());
mac.init(secretKey);
bytes = mac.doFinal(data.getBytes(Constants.CHAR bytes = mac.doFinal(data.getBytes(Constants.CHAR bytes ));} catch (GeneralSecurityException gse) {
# 拋出new IOException(gse.toString());
}#o String data ) 拋出IOException {
返回encryptMD5(data.getBytes(Constants.CHARSET_UTF8));
}
public static String> new StringBuilder( );
for (int i = 0; i < bytes.length; i ) {
if (hex.length () == 1) {
sign.append("0");
}
return sign.toString() ;
}
#
{## ;string, string> sortedParams = new SortedDictionary<string, string>(parameters, StringComparer.Ordinal);
IEnumerator<KeyPair< ;
/ / 第二步:將所有參數名稱、參數值串在一起
StringBuilder query = new StringBuilder();
if (Constants.SIGN_METHOD_ secret);
}
while (dem.MoveNext())
{
# dem.Current.Value;
if (!string.IsNullOrEmpty(key) && !string.IsNullOrEmpty(value))
{
# }
# // 第三步:使用MD5/HMAC加密
byte[] bytes;
if (Constants.SIGN_METHOD_HMAC.Equals(signMethod))## ding.UTF8. GetBytes(secret));
bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
query.Append(secret) ;
MD5 md5 = MD5.Create();
bytes = md // 第四步:將二進位轉換為大寫的十六進位
StringBuilder result = new StringBuilder();
for (int i = 0; .result.Append(bytes[i].ToString("X2"));
}
return result.ToString();
}
其他語言簽章範例程式碼請參考TOP官方SDK原始碼。
呼叫範例
以taobao.item.seller.get呼叫為例,具體步驟如下:
1. 設定參數值
公用參數:
- method = “taobao.item.seller.get”
- app_key = “12345678”
- session = “test”
- timestamp = “2016-01-01 12:00:00”
- format = “json”
- v = “2.0”
- sign_method = “md5 ”
業務參數:
- fields = “num_iid,title,nick,price,num”
- num_iid = 11223344
#2. 依ASCII順序排序
- app_key = “12345678”
- fields = “num_iid,title,nick,price,num”
- format = “json”
- method = “taobao.item.seller.get”
- #num_iid = 11223344
- #session = “test”
- sign_method = “md5”
- timestamp = “2016-01-01 12:00:00”
- v = “2.0”
# 3. 拼接參數名稱與參數值
4. 產生簽章
#假設app的secret為helloworld,則簽章結果為:hex(md5(helloworld 依序拼接好的參數名稱與參數值helloworld)) = “66987CB115214E59E6EC978214934FB8”
5. 組裝HTTP請求
將所有參數名稱和參數值採用utf-8進行URL編碼(參數順序可隨意,但必須要包含簽章參數),然後透過GET或POST(含byte[]型別參數)發起請求,如:
注意事項
- 所有的請求和回應資料編碼都是utf-8格式,URL裡的所有參數名稱和參數值請做URL編碼。如果請求的Content-Type是application/x-www-form-urlencoded,則HTTP Body體內的所有參數值也做URL編碼;如果是multipart/form-data格式,每個表單欄位的參數值無需編碼,但每個表單欄位的charset部分需要指定為utf-8。
- 參數名稱與參數值拼裝起來的URL長度小於1024個字元時,可以用GET發起請求;參數類型含byte[]類型或拼裝好的請求URL過長時,必須用POST發起請求。所有API都可以用POST發起請求。
- 如需需要在沙箱環境測試,請在應用控制台的沙箱管理頁面取得沙箱環境對應的app_key(一般為正式環境的app_key前面加上「10」)和app_secret,對應的session值也用沙箱帳號登入授權取得,沙箱環境授權和正式環境授權類似,詳細可參考使用者授權介紹。
- 產生簽章(sign)僅對未使用TOP官方SDK進行API呼叫時需要操作,如使用了TOP官方SDK,該步驟SDK會自動完成。
FAQ
介面呼叫報簽錯誤「 Invalid signature」