平台技術-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/resthttps://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簽名範例程式碼

public static String signTopRequest(Map<String, String> params, String secret, String signMethod) throws IOException {
  #    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() ;
}



#



































##################### #############################################C#簽章範例程式碼# ##############
public static string SignTopRequest(IDictionary<string, string> parameters, string secret, string signMethod)
{## ;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. 拼接參數名稱與參數值

app_key12345678fieldsnum_iid,title,nick,price,numformatjsonmethodtaobao.item.seller.getnum_iid11223344sessiontestsignm.item.seller。 .0

4. 產生簽章
#假設app的secret為helloworld,則簽章結果為:hex(md5(helloworld 依序拼接好的參數名稱與參數值helloworld)) = “66987CB115214E59E6EC978214934FB8”

5. 組裝HTTP請求
將所有參數名稱和參數值採用utf-8進行URL編碼(參數順序可隨意,但必須要包含簽章參數),然後透過GET或POST(含byte[]型別參數)發起請求,如:

http://gw. api.taobao.com/router/rest?method=taobao.item.seller.get&app_key=12345678&session=test×tamp=2016-01-01 12:00:00&format=json&v=2.0&sign_pod,mdti; num&num_iid=11223344&sign=66987CB115214E59E6EC978214934FB8
#

注意事項

  • 所有的請求和回應資料編碼都是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」