網關指南： https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl
網關控制台： https://apigateway.console.aliyun.com/?spm=5176.doc42740.2.2.Q4z5ws#/cn-hangzhou/apis/list
前言：調用 API 的三個前置條件：
- API：即將要調用的API，明確API參數定義。
- 應用 app：作為調用API時的身份， AppKey 和 AppSecret 用於驗證身份。
- API 和 App 的權限關系：App 想調用某個 API 需要具有該 API 的權限，這個權限通過授權的功能來建立。
以下會詳細說如何具備三個條件，並提供 API 調用 Demo 供參考。
一、獲取 API 文檔
1、從數據市場購買的 API 服務
您購買 API 服務時，如果還沒有開通 API 網關服務，那么會同時幫助您開通 API 網關服務，讓您使用的更流暢。
購買成功之后您進入雲市場的 管理控制台，就會看見您購買的所有 API 服務。您可以在當前控制台查看 API 接口的定義。
您還可以跳轉到 API 網關的控制台，在 已購買 API 頁面，展示您購買的所有 API 服務列表，以及使用情況概況。
選擇一個服務點擊 查看 API ，頁面會展示該服務的基本信息和 API 接口列表。注意在基本信息處關鍵的信息是 訪問域名。
選擇一個 API 接口，點擊 詳情，就會出現詳細的接口定義了。
2、不經過購買，由提供方主動授權
提供 API 的一方需要在控制台主動操作授權，這時您需要已經創建過應用 APP，並且將 AppId告知提供方，由他們搜索您的 APP 然后操作授權。
APP 的相關內容在 創建 APP 中介紹。這里先假設您已經創建了 APP，並且提供 API 的一方已經為您的 APP 授權。
您進入 API 網關的控制台應用管理頁面，這里是您創建的所有應用APP。
點擊 APP 的名稱進入 APP 詳情，此處會展示 APP 的基本信息以及兩個最重要的信息。AppKey 和 已授權的 API 。
AppKey 是您這個 APP 的 Key 和 Secret。您請求的時候需要帶上這對密鑰，網關會根據這對密鑰對您進行身份驗證。后面會詳細解釋。已授權的 API 是您該 APP 已經被授權的 API ，如果提供方已經操作了授權，那么您會在這里看見 API 接口。點擊 詳情 就可以查看詳細的接口定義
以上是兩種 API 渠道的獲取 API 定義的方式。
二、創建應用
應用（APP）是調用 API 服務時的身份。
每個 APP 有一組 Key 和 Secret，調用 API 時這兩個參數的用途如下：
- 將 AppKey 做參數傳入
- AppSecret 用於簽名計算，不能在請求中傳遞，
網關會校驗這對密鑰對您進行身份認證。
調用 API 需要這個 APP 具備調用該API的權限，這個授權和鑒權是面向 APP 的。您可以在 API 網關控制台 應用管理 頁面創建您的 APP。
創建成功后，系統會為 APP 分配一對 AppKey 和 AppSecret。
調用服務時，客戶端程序需要用 AppSecret 完成簽名計算，請求時攜帶AppKey和簽名信息1，
網關會根據AppKey找到服務器側的AppSecret重新計算簽名信息2和簽名信息1比對，這就是身份驗證。
在應用管理 頁面，點擊應用名稱進入詳情，就能看見 AppKey 和 AppSecret 信息了，如果密鑰丟失還可以操作重置。
APP 更多說明參見 用戶指南（調用API）
三、獲得授權
授權，是指授予 APP 調用某個 API 的權限。您的 APP 需要獲得 API 的授權才能調用該API。根據獲取 API 的渠道不同，建立授權的方式也不同。
從數據市場購買的 API 服務
您購買了 API 服務就意味着您已經獲得了授權。但是為了更精確的權限控制，您的賬號獲得了授權，不代表您的每個 APP 都獲得了授權。您需要手動操作將已購買的API授權給哪些 APP，然后這些 APP 才能調用該API。
不經過購買，由提供方主動授權
您需要向 API 服務商提供您的 應用 ID (AppID) 或者阿里雲郵箱賬戶，使 API 服務商能夠搜索到您的 APP，並完成授權。完成授權后您可以在控制台看到該 APP 被授權的 API。
由提供方操作授權的 API 會出現在應用詳情的 已授權 API 子頁面。提供方授權時就已經將 API 授權給准確的 APP 了，所以不需要調用者來操作授權。
四、調用 API
您可以直接用 API 網關控制台為您提供的多語言調用示例來測試調用，可以自行編輯 HTTP(s) 請求來調用 API。關於簽名方式，您可以參照控制台的 SDK示例下載 。
通過上述步驟，您已經獲取了 API 定義文檔、創建了 APP、建立了授權關系。
您可以調用 API 了。API 的請求步驟說明如下：
第一部分：請求
請求地址：http://e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com/demo/post
請求方法：POST
請求體：
FormParam1=FormParamValue1&FormParam2=FormParamValue2
//HTTP Request Body
請求頭部
Host: e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com
Date: Mon, 22 Aug 2016 11:21:04 GMT
User-Agent: Apache-HttpClient/4.1.2 (java 1.6)
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
//請求體類型，請根據實際請求體內容設置。
Accept: application/json
//請求響應體類型，部分 API 可以根據指定的響應類型來返回對應數據格式，建議手動指定此請求頭，如果不設置，部分 HTTP 客戶端會設置默認值 */*，導致簽名錯誤。
X-Ca-Request-Mode: debug
//是否開啟 Debug 模式，大小寫不敏感，不設置默認關閉，一般 API 調試階段可以打開此設置。
X-Ca-Version: 1
// API版本號，目前所有 API 僅支持版本號『1』，可以不設置此請求頭，默認版本號為『1』。
X-Ca-Signature-Headers: X-Ca-Request-Mode,X-Ca-Version,X-Ca-Stage,X-Ca-Key,X-Ca-Timestamp
//參與簽名的自定義請求頭，服務端將根據此配置讀取請求頭進行簽名，此處設置不包含 Content-Type、Accept、Content-MD5、Date 請求頭，這些請求頭已經包含在了基礎的簽名結構中，詳情參照請求簽名說明文檔。
X-Ca-Stage: RELEASE
//請求 API的Stage，目前支持 TEST、PRE、RELEASE 三個 Stage，大小寫不敏感，API 提供者可以選擇發布到哪個 Stage，只有發布到指定 Stage 后 API 才可以調用，否則會提示 API 找不到或 Invalid Url。
X-Ca-Key: 60022326
//請求的 AppKey，請到 API 網關控制台生成，只有獲得 API 授權后才可以調用，通過雲市場等渠道購買的 API 默認已經給APP授過權，阿里雲所有雲產品共用一套 AppKey 體系，刪除 ApppKey 請謹慎，避免影響到其他已經開通服務的雲產品。
X-Ca-Timestamp: 1471864864235
//請求的時間戳，值為當前時間的毫秒數，也就是從1970年1月1日起至今的時間轉換為毫秒，時間戳有效時間為15分鍾。
X-Ca-Nonce:b931bc77-645a-4299-b24b-f3669be577ac
//請求唯一標識，15分鍾內 AppKey+API+Nonce 不能重復，與時間戳結合使用才能起到防重放作用。
X-Ca-Signature: FJleSrCYPGCU7dMlLTG+UD3Bc5Elh3TV3CWHtSKh1Ys=
//請求簽名。
CustomHeader: CustomHeaderValue
//自定義請求頭，此處僅作為示例，實際請求中根據 API定義可以設置多個自定義請求頭。
第二部分：響應
狀態碼：400 //響應狀態碼，大於等於200小於300表示成功；大於等於400小於500為客戶端錯誤；大於500為服務端錯誤。
響應頭
X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
//請求唯一 ID，請求一旦進入 API 網關應用后，API 網關就會生成請求 ID 並通過響應頭返回給客戶端，建議客戶端與后端服務都記錄此請求 ID，可用於問題排查與跟蹤。
X-Ca-Error-Message: Invalid Url
// API網關返回的錯誤消息，當請求出現錯誤時 API 網關會通過響應頭將錯誤消息返回給客戶端。
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}
//當打開 Debug 模式后會返回 Debug 信息，此信息后期可能會有變更，僅用做聯調階段參考。
您調用 API 時，無論使用 HTTP 還是 HTTPS 協議提交請求，都需要在請求中包含簽名信息。詳細加密簽名的計算傳遞方式，見下。
簽名的計算 demo 請參照 API 網關控制台 SDK下載 頁面的 SDK 示例。
五、請求簽名說明文檔
1、名詞解釋
1.1、域名
- 每個 API 服務都屬於一個 API 分組，每個 API 分組有不同的域名。域名是由服務端綁定的獨立域名，API 網關通過域名來尋址定位 API 分組。
- 域名的格式為 www.[獨立域名].com/[Path]?[HTTPMethod]。
- API 網關通過域名定位到一個唯一的分組，通過 Path+HTTPMethod 確定該分組下唯一的 API。
- 您購買后在控制台 已購買的 API 可以獲得 API 文檔說明，若無購買行為，則可以聯系 API 提供者操作授權，授權后您就可以在控制台 已授權的 API 獲得 API 文檔說明。
1.2、系統級 Header
- 【必選】X-Ca-Key：AppKey。
- 【必選】X-Ca-Signature：簽名字符串。
- 【可選】X-Ca-Timestamp：API 調用者傳遞時間戳，值為當前時間的毫秒數，也就是從1970年1月1日起至今的時間轉換為毫秒，時間戳有效時間為15分鍾。
- 【可選】X-Ca-Nonce：API 調用者生成的 UUID，結合時間戳防重放。
- 【可選】Content-MD5 當請求 Body 非 Form 表單時，可以計算 Body 的 MD5 值傳遞給雲網關進行 Body MD5 校驗。
- 【可選】X-Ca-Stage請求 API 所屬 Stage，目前僅支持 TEST 、PRE 和 RELEASE，默認RELEASE，若您調用的 API 不在線上環境，請一定要指定該參數的值，否則會報 URL 錯誤。
2、簽名校驗
2.1、組織參與簽名計算的字符串
String stringToSign=
HTTPMethod + "\n" +
Accept + "\n" + //建議顯示設置 Accept Header。當 Accept 為空時，部分 Http 客戶端會給 Accept 設置默認值為 */*，導致簽名校驗失敗。
Content-MD5 + "\n"
Content-Type + "\n" +
Date + "\n" +
Headers +
Url
HTTPMethod 為全大寫，如 POST。
Accept、Content-MD5、Content-Type、Date 如果為空也需要添加換行符”\n”，Headers如果為空不需要添加”\n”。
Content-MD5
Content-MD5 是指 Body 的 MD5 值，只有當 Body 非 Form 表單時才計算 MD5，計算方式為：
String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));
bodyStream 為字節數組。
Headers
Headers 是指參與 Headers 簽名計算的 Header 的 Key、Value 拼接的字符串，建議對 X-Ca 開頭以及自定義 Header 計算簽名，注意如下參數不參與 Headers 簽名計算：X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。
- Headers 組織方法：
先對參與 Headers 簽名計算的 Header的Key 按照字典排序后使用如下方式拼接，如果某個 Header 的 Value 為空，則使用 HeaderKey + “:” + “\n”參與簽名，需要保留 Key 和英文冒號。
String headers =
HeaderKey1 + ":" + HeaderValue1 + "\n"\+
HeaderKey2 + ":" + HeaderValue2 + "\n"\+
...
HeaderKeyN + ":" + HeaderValueN + "\n"
將 Headers 簽名中 Header 的 Key 使用英文逗號分割放到 Request 的 Header 中，Key為：X-Ca-Signature-Headers。
Url
Url 指 Path + Query + Body 中 Form 參數，組織方法：對 Query+Form 參數按照字典對 Key 進行排序后按照如下方法拼接，如果 Query 或 Form 參數為空，則 Url = Path，不需要添加 ？，如果某個參數的 Value 為空只保留 Key 參與簽名，等號不需要再加入簽名。
String url =
Path +
"?" +
Key1 + "=" + Value1 +
"&" + Key2 + "=" + Value2 +
...
"&" + KeyN + "=" + ValueN
注意這里 Query 或 Form 參數的 Value 可能有多個，多個的時候只取第一個 Value 參與簽名計算。
2.2、計算簽名
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-8")),"UTF-8"));
secret 為 APP 的密鑰。
2.3、傳遞簽名
將計算的簽名結果放到 Request 的 Header 中，Key為：X-Ca-Signature。
3、簽名錯誤排查方法
當簽名校驗失敗時，API網關會將服務端的 StringToSign 放到 HTTP Response 的 Header 中返回到客戶端，Key為：X-Ca-Error-Message，
只需要將本地計算的 StringToSign 與服務端返回的 StringToSign 進行對比即可找到問題；
如果服務端與客戶端的 StringToSign 一致請檢查用於簽名計算的密鑰是否正確；
因為 HTTP Header 中無法表示換行，因此 StringToSign 中的換行符都被過濾掉了，對比時請忽略換行符。
4、簽名 demo
簽名計算的詳細 demo（JAVA）請參照鏈接：https://github.com/aliyun/api-gateway-demo-sign-java。
在 API 網關控制台，調用 API—SDK 下載 處還有更多語種的調用 demo。