一、簡介

用戶可以使用開發指南介紹的 API 對 API 網關服務進行相關操作。

術語表

業務限制資源規格限制說明

在 API 網關中，對每個用戶可創建的API分組、API個數都有限制，對用戶經過API網關調用開放的API也有限制。詳情請參考官網文檔對使用限制的說明《開放API使用限制》和《調用API使用限制》。

在接口說明部分，凡出現與官網上給出的限制發生矛盾時，均以官網的限制說明為準。

三、API概覽

API分組相關接口

域名相關接口

API管理相關接口

API流量控制相關接口

後端簽名相關接口

APP相關接口

授權相關接口

其他接口

四、調用方式

調用方式

更新時間：2017-06-07 13:26:11 分享：

對 API 網關 API 接口調用是通過向 API 網關 API 的服務端地址發送HTTP GET請求，並按照接口說明在請求中加入相應請求參數來完成的；根據請求的處理情況，系統會返回處理結果。

請求結構

服務地址

API網關 API的服務接入地址為：apigateway.[RegionId].aliyuncs.com.

如：apigateway.cn-hangzhou.aliyuncs.com

通信協議

支持通過HTTP或HTTPS通道進行請求通信。為了獲得更高的安全性，推薦您使用HTTPS通道發送請求。

請求方法

支持HTTP GET方法發送請求，這種方式下請求參數需要包含在請求的URL中。

請求參數

每個請求都需要指定要執行的操作，即Action參數（例如CreateApi），以及每個操作都需要包含的公共請求參數和指定操作所特有的請求參數。

字符編碼

請求及返回結果都使用UTF-8字符集進行編碼。

公共參數

公共請求參數

公共請求參數是指每個接口都需要使用到的請求參數。

請求示例：

1. https://apigateway.cn-hangzhou.aliyuncs.com/?Format=xml
2. &Version=2016-07-14
3. &Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
4. &SignatureMethod=HMACSHA1
5. &SignatureNonce=15215528852396
6. &SignatureVersion=1.0
7. &AccessKeyId=key-test
8. &TimeStamp=2016-08-08T08:00:00Z

公共返回參數

用戶發送的每次接口調用請求，無論成功與否，系統都會返回一個唯一識別碼RequestId給用戶。

XML返回示例：

1. <?xml version="1.0" encoding="UTF-8"?>
2. <!—結果的根結點-->
3. <接口名稱+Response>
4. <!—返回請求標簽-->
5. <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
6. <!—返回結果數據-->
7. </接口名稱+Response>

JSON返回示例：

1. {
2. "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
3. /* 返回結果數據 */
4. }

返回結果

調用API服務後返回數據采用統一格式，返回的HTTP狀態碼為2xx，代表調用成功。返回4xx或5xx的HTTP狀態碼代表調用失敗。

調用成功返回的數據格式主要有XML和JSON兩種，外部系統可以在請求時傳入參數來制定返回的數據格式，默認為XML格式。

本文檔中的返回示例為了便於用戶查看，做了格式化處理，實際返回結果是沒有進行換行、縮進等處理的。

成功結果

XML返回示例：

（XML返回結果包括請求是否成功信息和具體的業務數據）

1. <?xml version="1.0" encoding="UTF-8"?>
2. <!—結果的根結點-->
3. <接口名稱+Response>
4. <!—返回請求標簽-->
5. <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
6. <!—返回結果數據-->
7. </接口名稱+Response>

JSON示例：

1. {
2. "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
3. /* 返回結果數據 */
4. }

錯誤結果

調用接口出錯後，將不會返回結果數據。調用方可根據附表<錯誤查詢表>來定位錯誤原因。

當調用出錯時，HTTP請求返回一個4xx或5xx的HTTP狀態碼。返回的消息體中是具體的錯誤代碼及錯誤信息。另外還包含一個全局唯一的請求ID：RequestId和一個您該次請求訪問的站點ID：HostId。在調用方找不到錯誤原因時，可以聯系阿裏雲客服，並提供該HostId和RequestId，以便我們盡快幫您解決問題。

XML示例：

1. <?xml version="1.0" encoding="UTF-8"?>
2. <Error>
3. <RequestId>8906582E-6722-409A-A6C4-0E7863B733A5</RequestId>
4. <HostId>apigateway.cn-hangzhou.aliyuncs.com</HostId>
5. <Code>InternalError</Code>
6. <Message>The request processing has failed due to some unknown error.</Message>
7. </Error>

JSON示例：

1. {
2. "RequestId": "8906582E-6722-409A-A6C4-0E7863B733A5",
3. "HostId": "apigateway.cn-hangzhou.aliyuncs.com",
4. "Code": "InternalError",
5. "Message": "The request processing has failed due to some unknown error."
6. }

五、簽名機制

詳細說明

API網關服務會對每個訪問的請求進行身份驗證，所以無論使用HTTP還是HTTPS協議提交請求，都需要在請求中包含簽名（Signature）信息。

API網關通過使用Access Key ID和Access Key Secret進行對稱加密的方法來驗證請求者身份。Access Key ID和Access Key Secret由阿裏雲官方頒發給訪問者（可以通過阿裏雲官方網站申請和管理），其中

Access Key ID用於標識訪問者的身份

Access Key Secret是用於加密簽名字符串和服務器端驗證簽名字符串的密鑰，必須嚴格保密，只有阿裏雲和用戶知道。

用戶在訪問時，按照下面的方法對請求進行簽名處理：

a. 使用請求參數構造規範化的請求字符串（Canonicalized Query String）

• 按照參數名稱的字典順序對請求中所有的請求參數（包括文檔中描述的“公共請求參數”和給定了的請求接口的自定義參數，但不能包括“公共請求參數”中提到Signature參數本身）進行排序。

註：當使用GET方法提交請求時，這些參數就是請求URI中的參數部分（即URI中“?”之後由“&”連接的部分）。

• 對每個請求參數的名稱和值進行編碼。名稱和值要使用UTF-8字符集進行URL編碼，URL編碼的編碼規則是：

1. 對於字符 A-Z、a-z、0-9以及字符“-”、“_”、“.”、“~”不編碼;
2. 對於其他字符編碼成“%XY”的格式，其中XY是字符對應ASCII碼的16進制表示。比如英文的雙引號（”）對應的編碼就是%22
3. 對於擴展的UTF-8字符，編碼成“%XY%ZA…”的格式；
4. 需要說明的是英文空格（ ）要被編碼是%20，而不是加號（+）。

1. 註：一般支持URL編碼的庫（比如Java中的java.net.URLEncoder）都是按照“application/x-www-form-urlencoded”的MIME類型的規則進行編碼的。
3. 實現時可以直接使用這類方式進行編碼，把編碼後的字符串中加號（+）替換成%20、星號（*）替換成%2A、%7E替換回波浪號（~），即可得到上述規則描述的編碼字符串。

• 對編碼後的參數名稱和值使用英文等號（=）進行連接。
• 再把英文等號連接得到的字符串按參數名稱的字典順序依次使用&符號連接，即得到規範化請求字符串。

b. 使用上一步構造的規範化字符串按照下面的規則構造用於計算簽名的字符串：

1. StringToSign=
2. HTTPMethod + “&” +
3. percentEncode(“/”) + ”&” +
4. percentEncode(CanonicalizedQueryString)

其中HTTPMethod是提交請求用的HTTP方法，比GET。

percentEncode(“/”)是按照1.b中描述的URL編碼規則對字符“/”進行編碼得到的值，即“%2F”。

percentEncode(CanonicalizedQueryString)是對第1步中構造的規範化請求字符串按1.b中描述的URL編碼規則編碼後得到的字符串。

c. 按照RFC2104的定義，使用上面的用於簽名的字符串計算簽名HMAC值。註意：計算簽名時使用的Key就是用戶持有的Access Key Secret並加上一個“&”字符(ASCII:38)，使用的哈希算法是SHA1。

d. 按照Base64編碼規則把上面的HMAC值編碼成字符串，即得到簽名值（Signature）。

e. 將得到的簽名值作為Signature參數添加到請求參數中，即完成對請求簽名的過程。

註意：得到的簽名值在作為最後的請求參數值提交給API網關服務器的時候，要和其他參數一樣，按照RFC3986的規則進行URL編碼）。

以DescribeRegions為例，簽名前的請求URL為：

1. http://apigateway.cn-qingdao.aliyuncs.com?Format=json&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=Hmac-SHA1&SignatureNonce=d48e931b-90c9-49c7-ac86-a70dd3607c88&SignatureVersion=1.0&Version=2016-07-14&Timestamp=2016-09-27T09%3A08%3A30Z

那麽StringToSign就是：

1. GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeRegions%26Format%3Djson%26SignatureMethod%3DHmac-SHA1%26SignatureNonce%3Dd48e931b-90c9-49c7-ac86-a70dd3607c88%26SignatureVersion%3D1.0%26Timestamp%3D2016-09-27T09%253A08%253A30Z%26Version%3D2016-07-14

假如使用的Access Key Id是“testid”，Access Key Secret是“testsecret”，用於計算HMAC的Key就是“testsecret&”，則計算得到的簽名值是：

1. DRdMb%2F1m7PeToGRBApTl3wThyOg%3D

簽名後的請求URL為（註意增加了Signature參數）：

1. http://apigateway.cn-qingdao.aliyuncs.com?Signature=DRdMb%2F1m7PeToGRBApTl3wThyOg%3D&Format=json&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=Hmac-SHA1&SignatureNonce=d48e931b-90c9-49c7-ac86-a70dd3607c88&SignatureVersion=1.0&Version=2016-07-14&Timestamp=2016-09-27T09%3A08%3A30Z

握手API網關（7）開發指南-API參考