網(wǎng)關(guān)指南：https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl

網(wǎng)關(guān)控制臺(tái)：https://apigateway.console.aliyun.com/?spm=5176.doc42740.2.2.Q4z5ws

前言：調(diào)用 API 的三個(gè)前置條件：

API：即將要調(diào)用的API，明確API參數(shù)定義。
應(yīng)用 app：作為調(diào)用API時(shí)的身份， AppKey 和 AppSecret 用于驗(yàn)證身份。
API 和 App 的權(quán)限關(guān)系：App 想調(diào)用某個(gè) API 需要具有該 API 的權(quán)限，這個(gè)權(quán)限通過授權(quán)的功能來建立。

以下會(huì)詳細(xì)說如何具備三個(gè)條件，并提供 API 調(diào)用 Demo 供參考。

一、獲取 API 文檔

1、從數(shù)據(jù)市場(chǎng)購買的 API 服務(wù)

您購買 API 服務(wù)時(shí)，如果還沒有開通 API 網(wǎng)關(guān)服務(wù)，那么會(huì)同時(shí)幫助您開通 API 網(wǎng)關(guān)服務(wù)，讓您使用的更流暢。

購買成功之后您進(jìn)入云市場(chǎng)的管理控制臺(tái)，就會(huì)看見您購買的所有 API 服務(wù)。您可以在當(dāng)前控制臺(tái)查看 API 接口的定義。

您還可以跳轉(zhuǎn)到API 網(wǎng)關(guān)的控制臺(tái)，在已購買 API頁面，展示您購買的所有 API 服務(wù)列表，以及使用情況概況。

選擇一個(gè)服務(wù)點(diǎn)擊查看 API，頁面會(huì)展示該服務(wù)的基本信息和 API 接口列表。注意在基本信息處關(guān)鍵的信息是訪問域名。

選擇一個(gè) API 接口，點(diǎn)擊詳情，就會(huì)出現(xiàn)詳細(xì)的接口定義了。

2、不經(jīng)過購買，由提供方主動(dòng)授權(quán)

提供 API 的一方需要在控制臺(tái)主動(dòng)操作授權(quán)，這時(shí)您需要已經(jīng)創(chuàng)建過應(yīng)用 APP，并且將 AppId告知提供方，由他們搜索您的 APP 然后操作授權(quán)。

APP 的相關(guān)內(nèi)容在創(chuàng)建 APP中介紹。這里先假設(shè)您已經(jīng)創(chuàng)建了 APP，并且提供 API 的一方已經(jīng)為您的 APP 授權(quán)。

您進(jìn)入 API 網(wǎng)關(guān)的控制臺(tái)應(yīng)用管理頁面，這里是您創(chuàng)建的所有應(yīng)用APP。

點(diǎn)擊 APP 的名稱進(jìn)入 APP 詳情，此處會(huì)展示 APP 的基本信息以及兩個(gè)最重要的信息。AppKey和已授權(quán)的 API。

AppKey是您這個(gè) APP 的Key和Secret。您請(qǐng)求的時(shí)候需要帶上這對(duì)密鑰，網(wǎng)關(guān)會(huì)根據(jù)這對(duì)密鑰對(duì)您進(jìn)行身份驗(yàn)證。后面會(huì)詳細(xì)解釋。已授權(quán)的 API是您該 APP 已經(jīng)被授權(quán)的 API ，如果提供方已經(jīng)操作了授權(quán)，那么您會(huì)在這里看見 API 接口。點(diǎn)擊詳情就可以查看詳細(xì)的接口定義

以上是兩種 API 渠道的獲取 API 定義的方式。

二、創(chuàng)建應(yīng)用

應(yīng)用（APP）是調(diào)用 API 服務(wù)時(shí)的身份。

每個(gè) APP 有一組Key和Secret，調(diào)用 API 時(shí)這兩個(gè)參數(shù)的用途如下：

將AppKey做參數(shù)傳入
AppSecret用于簽名計(jì)算，不能在請(qǐng)求中傳遞，

網(wǎng)關(guān)會(huì)校驗(yàn)這對(duì)密鑰對(duì)您進(jìn)行身份認(rèn)證。

調(diào)用 API 需要這個(gè) APP 具備調(diào)用該API的權(quán)限，這個(gè)授權(quán)和鑒權(quán)是面向 APP 的。您可以在 API 網(wǎng)關(guān)控制臺(tái)應(yīng)用管理頁面創(chuàng)建您的 APP。

創(chuàng)建成功后，系統(tǒng)會(huì)為 APP 分配一對(duì)AppKey和AppSecret。

調(diào)用服務(wù)時(shí)，客戶端程序需要用AppSecret完成簽名計(jì)算，請(qǐng)求時(shí)攜帶AppKey和簽名信息1，

網(wǎng)關(guān)會(huì)根據(jù)AppKey找到服務(wù)器側(cè)的AppSecret重新計(jì)算簽名信息2和簽名信息1比對(duì)，這就是身份驗(yàn)證。

在應(yīng)用管理頁面，點(diǎn)擊應(yīng)用名稱進(jìn)入詳情，就能看見AppKey和AppSecret信息了，如果密鑰丟失還可以操作重置。

APP 更多說明參見用戶指南（調(diào)用API）

三、獲得授權(quán)

授權(quán)，是指授予 APP 調(diào)用某個(gè) API 的權(quán)限。您的 APP 需要獲得 API 的授權(quán)才能調(diào)用該API。根據(jù)獲取 API 的渠道不同，建立授權(quán)的方式也不同。

從數(shù)據(jù)市場(chǎng)購買的 API 服務(wù)

您購買了 API 服務(wù)就意味著您已經(jīng)獲得了授權(quán)。但是為了更精確的權(quán)限控制，您的賬號(hào)獲得了授權(quán)，不代表您的每個(gè) APP 都獲得了授權(quán)。您需要手動(dòng)操作將已購買的API授權(quán)給哪些 APP，然后這些 APP 才能調(diào)用該API。

不經(jīng)過購買，由提供方主動(dòng)授權(quán)

您需要向 API 服務(wù)商提供您的應(yīng)用 ID (AppID)或者阿里云郵箱賬戶，使 API 服務(wù)商能夠搜索到您的 APP，并完成授權(quán)。完成授權(quán)后您可以在控制臺(tái)看到該 APP 被授權(quán)的 API。

由提供方操作授權(quán)的 API 會(huì)出現(xiàn)在應(yīng)用詳情的已授權(quán) API子頁面。提供方授權(quán)時(shí)就已經(jīng)將 API 授權(quán)給準(zhǔn)確的 APP 了，所以不需要調(diào)用者來操作授權(quán)。

四、調(diào)用 API

您可以直接用 API 網(wǎng)關(guān)控制臺(tái)為您提供的多語言調(diào)用示例來測(cè)試調(diào)用，可以自行編輯 HTTP(s) 請(qǐng)求來調(diào)用 API。關(guān)于簽名方式，您可以參照控制臺(tái)的SDK示例下載。

通過上述步驟，您已經(jīng)獲取了 API 定義文檔、創(chuàng)建了 APP、建立了授權(quán)關(guān)系。

您可以調(diào)用 API 了。API 的請(qǐng)求步驟說明如下：

第一部分：請(qǐng)求

請(qǐng)求地址：http://e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com/demo/post

請(qǐng)求方法：POST

請(qǐng)求體：

FormParam1=FormParamValue1&FormParam2=FormParamValue2

//HTTP Request Body

請(qǐng)求頭部

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

//請(qǐng)求體類型，請(qǐng)根據(jù)實(shí)際請(qǐng)求體內(nèi)容設(shè)置。

Accept: application/json

//請(qǐng)求響應(yīng)體類型，部分 API 可以根據(jù)指定的響應(yīng)類型來返回對(duì)應(yīng)數(shù)據(jù)格式，建議手動(dòng)指定此請(qǐng)求頭，如果不設(shè)置，部分 HTTP 客戶端會(huì)設(shè)置默認(rèn)值 */*，導(dǎo)致簽名錯(cuò)誤。

X-Ca-Request-Mode: debug

//是否開啟 Debug 模式，大小寫不敏感，不設(shè)置默認(rèn)關(guān)閉，一般 API 調(diào)試階段可以打開此設(shè)置。

X-Ca-Version: 1

// API版本號(hào)，目前所有 API 僅支持版本號(hào)『1』，可以不設(shè)置此請(qǐng)求頭，默認(rèn)版本號(hào)為『1』。

X-Ca-Signature-Headers: X-Ca-Request-Mode,X-Ca-Version,X-Ca-Stage,X-Ca-Key,X-Ca-Timestamp

//參與簽名的自定義請(qǐng)求頭，服務(wù)端將根據(jù)此配置讀取請(qǐng)求頭進(jìn)行簽名，此處設(shè)置不包含 Content-Type、Accept、Content-MD5、Date 請(qǐng)求頭，這些請(qǐng)求頭已經(jīng)包含在了基礎(chǔ)的簽名結(jié)構(gòu)中，詳情參照請(qǐng)求簽名說明文檔。

X-Ca-Stage: RELEASE

//請(qǐng)求 API的Stage，目前支持 TEST、PRE、RELEASE 三個(gè) Stage，大小寫不敏感，API 提供者可以選擇發(fā)布到哪個(gè) Stage，只有發(fā)布到指定 Stage 后 API 才可以調(diào)用，否則會(huì)提示 API 找不到或 Invalid Url。

X-Ca-Key: 60022326

//請(qǐng)求的 AppKey，請(qǐng)到 API 網(wǎng)關(guān)控制臺(tái)生成，只有獲得 API 授權(quán)后才可以調(diào)用，通過云市場(chǎng)等渠道購買的 API 默認(rèn)已經(jīng)給APP授過權(quán)，阿里云所有云產(chǎn)品共用一套 AppKey 體系，刪除 ApppKey 請(qǐng)謹(jǐn)慎，避免影響到其他已經(jīng)開通服務(wù)的云產(chǎn)品。

X-Ca-Timestamp: 1471864864235

//請(qǐng)求的時(shí)間戳，值為當(dāng)前時(shí)間的毫秒數(shù)，也就是從1970年1月1日起至今的時(shí)間轉(zhuǎn)換為毫秒，時(shí)間戳有效時(shí)間為15分鐘。

X-Ca-Nonce:b931bc77-645a-4299-b24b-f3669be577ac

//請(qǐng)求唯一標(biāo)識(shí)，15分鐘內(nèi) AppKey+API+Nonce 不能重復(fù)，與時(shí)間戳結(jié)合使用才能起到防重放作用。

X-Ca-Signature: FJleSrCYPGCU7dMlLTG+UD3Bc5Elh3TV3CWHtSKh1Ys=

//請(qǐng)求簽名。

CustomHeader: CustomHeaderValue

//自定義請(qǐng)求頭，此處僅作為示例，實(shí)際請(qǐng)求中根據(jù) API定義可以設(shè)置多個(gè)自定義請(qǐng)求頭。

第二部分：響應(yīng)

狀態(tài)碼：400//響應(yīng)狀態(tài)碼，大于等于200小于300表示成功；大于等于400小于500為客戶端錯(cuò)誤；大于500為服務(wù)端錯(cuò)誤。

響應(yīng)頭

X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF

//請(qǐng)求唯一 ID，請(qǐng)求一旦進(jìn)入 API 網(wǎng)關(guān)應(yīng)用后，API 網(wǎng)關(guān)就會(huì)生成請(qǐng)求 ID 并通過響應(yīng)頭返回給客戶端，建議客戶端與后端服務(wù)都記錄此請(qǐng)求 ID，可用于問題排查與跟蹤。

X-Ca-Error-Message: Invalid Url

// API網(wǎng)關(guān)返回的錯(cuò)誤消息，當(dāng)請(qǐng)求出現(xiàn)錯(cuò)誤時(shí) API 網(wǎng)關(guān)會(huì)通過響應(yīng)頭將錯(cuò)誤消息返回給客戶端。

X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}

//當(dāng)打開 Debug 模式后會(huì)返回 Debug 信息，此信息后期可能會(huì)有變更，僅用做聯(lián)調(diào)階段參考。

您調(diào)用 API 時(shí)，無論使用 HTTP 還是 HTTPS 協(xié)議提交請(qǐng)求，都需要在請(qǐng)求中包含簽名信息。詳細(xì)加密簽名的計(jì)算傳遞方式，見下。

簽名的計(jì)算 demo 請(qǐng)參照 API 網(wǎng)關(guān)控制臺(tái)SDK下載頁面的 SDK 示例。

五、請(qǐng)求簽名說明文檔

1、名詞解釋

1.1、域名

每個(gè) API 服務(wù)都屬于一個(gè) API 分組，每個(gè) API 分組有不同的域名。域名是由服務(wù)端綁定的獨(dú)立域名，API 網(wǎng)關(guān)通過域名來尋址定位 API 分組。
域名的格式為 www.[獨(dú)立域名].com/[Path]?[HTTPMethod]。
API 網(wǎng)關(guān)通過域名定位到一個(gè)唯一的分組，通過 Path+HTTPMethod 確定該分組下唯一的 API。
您購買后在控制臺(tái)已購買的 API可以獲得 API 文檔說明，若無購買行為，則可以聯(lián)系 API 提供者操作授權(quán)，授權(quán)后您就可以在控制臺(tái)已授權(quán)的 API獲得 API 文檔說明。

1.2、系統(tǒng)級(jí) Header

【必選】X-Ca-Key：AppKey。
【必選】X-Ca-Signature：簽名字符串。
【可選】X-Ca-Timestamp：API 調(diào)用者傳遞時(shí)間戳，值為當(dāng)前時(shí)間的毫秒數(shù)，也就是從1970年1月1日起至今的時(shí)間轉(zhuǎn)換為毫秒，時(shí)間戳有效時(shí)間為15分鐘。
【可選】X-Ca-Nonce：API 調(diào)用者生成的 UUID，結(jié)合時(shí)間戳防重放。
【可選】Content-MD5 當(dāng)請(qǐng)求 Body 非 Form 表單時(shí)，可以計(jì)算 Body 的 MD5 值傳遞給云網(wǎng)關(guān)進(jìn)行 Body MD5 校驗(yàn)。
【可選】X-Ca-Stage請(qǐng)求 API 所屬 Stage，目前僅支持 TEST 、PRE 和 RELEASE，默認(rèn)RELEASE，若您調(diào)用的 API 不在線上環(huán)境，請(qǐng)一定要指定該參數(shù)的值，否則會(huì)報(bào) URL 錯(cuò)誤。

2、簽名校驗(yàn)

2.1、組織參與簽名計(jì)算的字符串

String stringToSign=

HTTPMethod + "
" +

Accept + "
" + //建議顯示設(shè)置 Accept Header。當(dāng) Accept 為空時(shí)，部分 Http 客戶端會(huì)給 Accept 設(shè)置默認(rèn)值為 */*，導(dǎo)致簽名校驗(yàn)失敗。

Content-MD5 + "
"

Content-Type + "
" +

Date + "
" +

Headers +

Url

HTTPMethod 為全大寫，如 POST。

Accept、Content-MD5、Content-Type、Date 如果為空也需要添加換行符”
”，Headers如果為空不需要添加”
”。

Content-MD5

Content-MD5 是指 Body 的 MD5 值，只有當(dāng) Body 非 Form 表單時(shí)才計(jì)算 MD5，計(jì)算方式為：

String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

bodyStream 為字節(jié)數(shù)組。

Headers

Headers 是指參與 Headers 簽名計(jì)算的 Header 的 Key、Value 拼接的字符串，建議對(duì) X-Ca 開頭以及自定義 Header 計(jì)算簽名，注意如下參數(shù)不參與 Headers 簽名計(jì)算：X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。

Headers 組織方法：

先對(duì)參與 Headers 簽名計(jì)算的 Header的Key按照字典排序后使用如下方式拼接，如果某個(gè) Header 的 Value 為空，則使用 HeaderKey + “:” + “
”參與簽名，需要保留 Key 和英文冒號(hào)。

String headers =

HeaderKey1 + ":" + HeaderValue1 + "
"+

HeaderKey2 + ":" + HeaderValue2 + "
"+

...

HeaderKeyN + ":" + HeaderValueN + "
"

將 Headers 簽名中 Header 的 Key 使用英文逗號(hào)分割放到 Request 的 Header 中，Key為：X-Ca-Signature-Headers。

Url

Url 指Path + Query + Body中Form參數(shù)，組織方法：對(duì)Query+Form參數(shù)按照字典對(duì)Key進(jìn)行排序后按照如下方法拼接，如果Query或Form參數(shù)為空，則 Url = Path，不需要添加？，如果某個(gè)參數(shù)的Value為空只保留Key參與簽名，等號(hào)不需要再加入簽名。

String url =

Path +

"?" +

Key1 + "=" + Value1 +

"&" + Key2 + "=" + Value2 +

...

"&" + KeyN + "=" + ValueN

注意這里Query或Form參數(shù)的Value可能有多個(gè)，多個(gè)的時(shí)候只取第一個(gè) Value 參與簽名計(jì)算。

2.2、計(jì)算簽名

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、傳遞簽名

將計(jì)算的簽名結(jié)果放到 Request 的 Header 中，Key為：X-Ca-Signature。

3、簽名錯(cuò)誤排查方法

當(dāng)簽名校驗(yàn)失敗時(shí)，API網(wǎng)關(guān)會(huì)將服務(wù)端的 StringToSign 放到 HTTP Response 的 Header 中返回到客戶端，Key為：X-Ca-Error-Message，

只需要將本地計(jì)算的 StringToSign 與服務(wù)端返回的 StringToSign 進(jìn)行對(duì)比即可找到問題；

如果服務(wù)端與客戶端的 StringToSign 一致請(qǐng)檢查用于簽名計(jì)算的密鑰是否正確；

因?yàn)?HTTP Header 中無法表示換行，因此 StringToSign 中的換行符都被過濾掉了，對(duì)比時(shí)請(qǐng)忽略換行符。

4、簽名 demo

簽名計(jì)算的詳細(xì) demo（JAVA）請(qǐng)參照鏈接：https://github.com/aliyun/api-gateway-demo-sign-java。

在 API 網(wǎng)關(guān)控制臺(tái)，調(diào)用 API—SDK 下載處還有更多語種的調(diào)用 demo。

總結(jié)

以上是生活随笔為你收集整理的阿里云API网关（3）快速入门（调用 API）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。