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