阿里云API網(wǎng)關(guān)服務(wù)-API手冊

1、API 網(wǎng)關(guān)使用手冊（調(diào)用API）API 網(wǎng)關(guān)/使用手冊（調(diào)用API） PAGE 5使用手冊（調(diào)用API）調(diào)用API您可以通過API網(wǎng)關(guān)，調(diào)用由其他阿里云用戶或者第三方服務(wù)商開放的API服務(wù)。API網(wǎng)關(guān)將為您提供一系列管 理服務(wù)與支撐。調(diào)用示例您可以基于API網(wǎng)關(guān)提供的SDK，通過編寫代碼的方式調(diào)用API。也可以自行編輯HTTP請求調(diào)用API。API的請 求結(jié)構(gòu)如下：/假如，域名：/假如，Path：/web/cloudapi/mapping/service/假如，Query內(nèi)容是：a=name，b=12 HYPERLINK /web/cloudapi/mapping/service /web/

2、cloudapi/mapping/service？a=name&b=12/則請求的url如下/請求的MethodPOST HttpMethod：POST/Headers中需要包含簽名信息和部分參數(shù)X-Ca-Version: 1/API版本X-Ca-Signature-Headers: X-Ca-Version,X-Ca-Key,X-Ca-Stage,X-Ca-Timestamp /參與簽名的Header X-Ca-Key: 60028305 /AppKeyX-Ca-Stage: test /StageX-Ca-Timestamp: 1456905123049 /時間戳X-Ca-Signatur

3、e: UAaH/qteir4G9UK4YR+NWdyq+c1rjl0PvtO/C1Qo68U= /簽名/詳細(xì)加密簽名的計算傳遞方式，請查看文檔-入口及協(xié)議。/Http標(biāo)準(zhǔn)頭/服務(wù)地址Host: Date: Wed 02 Mar 2016 07:52:02 GMTUser-Agent: Apache-HttpClient/4.1.2 (java 1.6)Content-Type: application/x-www-form-urlencoded; charset=utf-8Amount=11&InstanceId=ClientInstanceId&InstanceName=ClientInst

4、anceName/Body內(nèi)容以上內(nèi)容加上API的入?yún)⒕蜆?gòu)成了API請求。其中，在公測階段，您需要在線下從提供API的服務(wù)方獲取API的說 明文檔，獲取服務(wù)地址、Path等詳細(xì)說明。AppKey是您創(chuàng)建的APP的密鑰，用于做身份驗證。APP是您調(diào)用 API需要創(chuàng)建的身份。詳情將在后續(xù)內(nèi)容中說明。應(yīng)用（APP）您需要創(chuàng)建應(yīng)用（APP）作為您調(diào)用API的身份，每個APP有一對AppKey和AppSecret密鑰對，用于您請求時 做加密簽名，網(wǎng)關(guān)會對簽名做驗證。在API網(wǎng)關(guān)，您需要創(chuàng)建應(yīng)用（APP）作為請求者的身份。APP創(chuàng)建時，系統(tǒng)會自動分配一對AppKey和AppSecret，AppKey用于標(biāo)

5、識您的身份，AppSecret是用于加密簽名字符串和服務(wù)器端 驗證簽名字符串的密鑰。調(diào)用API時您需要將AppKey和AppSecret加密簽名放入請求參數(shù)，API網(wǎng)關(guān) 會通過對稱加密來驗證您的身份。詳細(xì)加密簽名的計算傳遞方式，請查看文檔-入口及協(xié)議。AppKey和AppSecret密鑰對，具備該APP的全部權(quán)限，需要妥善保管。如果發(fā)生泄漏，您可以在API網(wǎng)關(guān)的控制臺進(jìn)行重置。您可以擁有多個APP，可以根據(jù)您的業(yè)務(wù)需求分別被授權(quán)不同的API。注意，API的授權(quán)對象是APP而 不是阿里云用戶賬號。您可以在API網(wǎng)關(guān)控制臺完成對APP的創(chuàng)建、修改、刪除、查看詳情、密鑰管理、查看已授權(quán)等管理 操作。

6、授權(quán)授權(quán)，是指授予APP調(diào)用某個API的權(quán)限。您的APP需要獲得API的授權(quán)才能調(diào)用該API。在公測階段，由API服 務(wù)方建立APP和API之間的權(quán)限關(guān)系。在公測階段，由提供API的服務(wù)方來建立授權(quán)關(guān)系，您需要向其提供AppID或者您的阿里云郵箱賬戶，說明給予某一個APP進(jìn)行授權(quán)。授權(quán)建立后，您就可以使用該APP調(diào)用API了。在公測階段，您不具備建立或者刪除授權(quán)的權(quán)限。您僅可以在控制臺查看相應(yīng)APP下已經(jīng)被授權(quán)的API。如果您需要解除某個API的授權(quán)，請您聯(lián)系A(chǔ)PI服務(wù)提供方。加密簽名您調(diào)用API時，需要使用AppKey和AppSecret計算加密簽名，完成身份驗證。在API網(wǎng)關(guān)，使用APP作

7、為您調(diào)用API的身份。APP創(chuàng)建時，系統(tǒng)會自動分配AppKey和AppSecret。 服務(wù)器端會通過驗證AppKey和AppSecret來完成請求者的身份驗證。無論使用HTTP還是HTTPS協(xié)議提交請求，都需要在請求中包含簽名信息。AppKey用于標(biāo)識您的身 份，AppSecret是用于加密簽名字符串和服務(wù)器端驗證簽名字符串的密鑰。詳細(xì)加密簽名的計算傳遞 方式，請查看文檔-入口及協(xié)議。使用限制每個賬號下APP個數(shù)上限為10個，APP名稱應(yīng)為賬號下唯一。在公測階段，您不具備授權(quán)或解除授權(quán)的權(quán)限，由API服務(wù)方完成相關(guān)操作。您的請求需要包含簽名信息，請參照文檔-入口及協(xié)議訪問入口域名每個API服務(wù)

8、都屬于一個API分組，每個API分組有不同的域名。域名是由服務(wù)端綁定的獨立域名，API網(wǎng)關(guān)通過域名來尋址定位API分組。域名的格式為 HYPERLINK http:/www/ www.獨立域名.com/Path?HTTPMethod,在公測階段，API使用者需要在線下從API提供者處獲取此域名。云API網(wǎng)關(guān)通過域名定位到一個唯一的分組，通過Path+HTTPMethod確定該分組下唯一的API。您需要在線下從API服務(wù)商處獲取API文檔，其中會包含域名、Path等必要參數(shù)信息。系統(tǒng)級Header【必選】X-Ca-Key：AppKey【必選】X-Ca-Signature：簽名字符串【可選】X-C

9、a-Timestamp：API調(diào)用者傳遞時間戳，為時間轉(zhuǎn)換為毫秒的值，也就是從1970年1月 1日起至今的時間轉(zhuǎn)換為毫秒，可選，默認(rèn)15分鐘內(nèi)有效【可選】X-Ca-Nonce：API調(diào)用者生成UUID，結(jié)合時間戳進(jìn)行防重放，可選【可選】Content-MD5：當(dāng)請求Body非Form表單時，可以計算Body的MD5值傳遞給云網(wǎng)關(guān)進(jìn)行Body MD5校驗【可選】X-Ca-Stage：請求API所屬Stage，目前僅支持test和release，默認(rèn)release。若您調(diào)用的API不在線上環(huán)境，請一定要指定該參數(shù)的值，否則會報URL錯誤。簽名校驗簽名計算的詳細(xì)demo（JAVA）請參照鏈接：/al

10、iyun/api-gateway-demo-sign-java。簽名計算方法步驟如下：String stringToSign= HTTPMethod + n + Accept + n + Content-MD5 + n Content-Type + n + Date + n +Headers + Url組織參與簽名計算的字符串說 明 HTTPMethod為全大寫Accept、Content-MD5、Content-Type、Date如果為空也需要添加換行符n，Headers如果為空不需要添加n，不為空的Headers中包含了n，詳見下面組織Headers的描述Content-MD5String

11、 content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes(UTF-8);Content-MD5是指Body的MD5值，只有當(dāng)Body非Form表單時才計算MD5，計算方式為：bodyStream為字節(jié)數(shù)組HeadersHeaders指所有參與簽名計算的Header的Key、Value，這里要注意參與簽名計算的Header是不包含X-Ca- Signature、X-Ca-Signature-Headers的。Headers組織方法：String headers =HeaderKey1 + : + HeaderValue1 + n+ He

12、aderKey2 + : + HeaderValue2 + n+.HeaderKeyN + : + HeaderValueN + n先對所有參與簽名計算的Header的Key按照字典排序，然后按照如下方式拼接：UrlUrl指Path + Query + Body中Form參數(shù)，組織方法：對Query+Form參數(shù)按照字典對Key進(jìn)行排序后按照如下方法拼接，如果Query或Form參數(shù)為空，則Url = Path，不需要添加?String url = Path +? +Key1 + = + Value1 +& + Key2 + = + Value2 +.& + KeyN + = + ValueN注意這里Query或Form參數(shù)的Value可能有多個，多個的時候只取第一個Value參與簽名計算Mac hmacSha256 = Mac.getInstance(HmacSHA256); byte keyBytes = secret.getBytes(UTF-8);hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, HmacSHA256);String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes(UTF-