握手API網關(7)開發指南-API參考
一、簡介
用戶可以使用開發指南介紹的 API 對 API 網關服務進行相關操作。
術語表
術語 | 全稱 | 中文 | 說明 |
---|---|---|---|
Region | 地域 | 用戶開放API,需選擇API在API網關的部署地域,建議選擇與後端服務相同的Region。 | |
API | 應用程序編程接口 | 用戶開放API,在API網關錄入API,以提供接口的方式對外提供服務或者數據。 | |
Group | API Group | API分組 | 一組API。
|
SubDomain | 分組二級域名 | 用戶開放API,創建的每個API分組都有一個二級域名,獨立域名需要解析到該二級域名上,直接訪問該域名可以調用測試環境的API。 | |
CustomDomain | Custom Domain | 域名 | 用戶開放API,需要綁定自己的獨立域名,該域名需要CNAME解析到分組二級域名上且在阿裏雲備案或備案接入。且若支持HTTPS協議,還需為域名上傳SSL合規證書。 |
Stage | 環境 | 用戶開放API,創建的每個API分組目前有兩個環境,測試和線上。用戶操作API發布到某個環境後,API才能被調用。區別在於,直接訪問分組二級域名調用API,默認是調用測試環境。 | |
Signature | Backend Signature | 後端簽名密鑰 | 用於開放API的用戶給API網關頒發身份驗證密鑰。後端簽名密鑰綁定到API後對綁定的API即時生效。網關接收到這些API的請求,再去請求後端服務的時候就會帶上簽名信息,供後端服務對API網關做身份校驗。 |
TrafficControl | 流量控制策略(簡稱“流控策略”) | 用於開放API的用戶對API做訪問流控。流控策略與API綁定後對綁定的API即時生效。流控策略可以從Api、App、User三個維度管控API的調用。流控策略下還可以配置特殊流控,如某App/User在調用綁定的API時,可以按照特殊的值來流控。 | |
Special | Special Traffic Control | 特殊流量控制(簡稱“特殊流控”) | 是流控策略的一個配置,可以指定某App/User,針對流控策略綁定的API,按照單獨的值進行流控。 |
APP | 應用 | 調用其他用戶開放的API時,需要創建一個APP作為調用者的身份。請求到達網關時,會對AppKey和AppSecret進行簽名校驗。 |
業務限制資源規格限制說明
在 API 網關中,對每個用戶可創建的API分組、API個數都有限制,對用戶經過API網關調用開放的API也有限制。詳情請參考官網文檔對使用限制的說明《開放API使用限制》和《調用API使用限制》。
在接口說明部分,凡出現與官網上給出的限制發生矛盾時,均以官網的限制說明為準。
三、API概覽
API分組相關接口
API | 描述 |
---|---|
CreateApiGroup | 創建API分組 |
ModifyApiGroup | 修改API分組 |
DeleteApiGroup | 刪除API分組 |
CreateApiStageVariable | 創建環境變量 |
DeleteApiStageVariable | 刪除環境變量 |
DescribeApiStage | 查詢指定環境詳情 |
DescribeApiGroup | 查詢指定API分組詳情 |
DescribeApiGroups | 查詢API分組列表 |
域名相關接口
API | 描述 |
---|---|
SetDomain | 綁定自定義域名 |
SetDomainCertificate | 給指定自定義域名上傳SSL證書 |
DescribeDomain | 查詢指定自定義域名詳情信息 |
DeleteDomain | 刪除指定自定義域名 |
DeleteDomainCertificate | 刪除指定域名的證書 |
API管理相關接口
API | 描述 |
---|---|
CreateApi | 創建API |
ModifyApi | 修改API |
DeployApi | 發布指定API到指定環境 |
SwitchApi | 切換指定API在指定環境運行中的定義 |
AbolishApi | 將指定環境的指定API下線 |
DeleteApi | 刪除指定Api定義 |
DescribeApi | 查詢指定API定義中的詳情 |
DescribeApis | 查詢定義中的API列表 |
DescribeApiDoc | 查詢指定API在指定環境中的調用說明(運行的定義) |
DescribeDeployedApi | 查詢指定API在指定環境中的運行定義 |
DescribeDeployedApis | 查詢指定環境中正在運行的API列表 |
DescribeApiHistory | 查詢指定API指定歷史版本的定義 |
DescribeApiHistories | 查詢指定API指定歷史版本列表 |
DescribeApiErrorData | 查詢指定API的錯誤監控數據 |
DescribeApiLatencyData | 查詢指定API的響應時間監控數據 |
DescribeApiQpsData | 查詢指定API的Qps監控數據 |
DescribeApiTrafficData | 查詢指定API的流量監控數據 |
API流量控制相關接口
API | 描述 |
---|---|
CreateTrafficControl | 創建流量控制策略 |
ModifyTrafficControl | 修改流量控制策略 |
DeleteTrafficControl | 刪除指定流控策略 |
AddTrafficSpecialControl | 在指定流控策略下添加特殊流控策略 |
DeleteAllTrafficSpecialControl | 刪除指定流控策略下所有的特殊流控 |
DeleteTrafficSpecialControl | 刪除指定流控策略下的指定特殊流控 |
SetTrafficControlApis | 添加API與流控策略的綁定關系 |
RemoveTrafficControlApis | 解除API與流控策略的綁定關系 |
DescribeTrafficControls | 條件查詢流控策略列表及詳情信息 |
DescribeApisByTrafficControl | 查詢指定策略下已綁定的API |
DescribeApiTrafficControls | 查詢指定分組指定環境下所有API的流控策略綁定概況 |
DescribeTrafficControlsByApi | 查詢指定API已綁定的流控策略 |
後端簽名相關接口
API | 描述 |
---|---|
CreateSignature | 創建後端簽名密鑰 |
ModifySignature | 修改後端簽名密鑰 |
DeleteSignature | 刪除後端簽名密鑰 |
SetSignatureApis | 添加API與後端簽名密鑰的綁定關系 |
RemoveSignatureApis | 解除API與後端簽名密鑰的綁定關系 |
DescribeSignatures | 查詢後端簽名密鑰列表 |
DescribeApisBySignature | 查詢指定簽名密鑰所綁定的API |
DescribeApiSignatures | 查詢指定分組指定環境下所有API的簽名密鑰綁定概況 |
DescribeSignaturesByApi | 查詢指定API已綁定的後端簽名密鑰 |
APP相關接口
API | 描述 |
---|---|
CreateApp | 創建應用 |
ModifyApp | 修改應用 |
ResetAppSecret | 重置指定APP密鑰 |
DescribeAppAttributes | 查詢APP列表及基本屬性 |
DescribeAppSecurity | 查詢指定APP密鑰信息 |
DeleteApp | 刪除應用 |
授權相關接口
API | 描述 |
---|---|
DescribeApps | 查詢可授權的APP列表 |
DescribeAuthorizedApis | 查詢指定APP已授權的API列表 |
DescribeAuthorizedApps | 查詢API的應用授權列表 |
SetApisAuthorities | 給指定APP添加多個API的訪問權限 |
SetAppsAuthorities | 給多個APP添加指定API的訪問權限 |
RemoveApisAuthorities | 批量撤銷指定APP對多個API的訪問權限 |
RemoveAppsAuthorities | 批量撤銷多個APP對指定API的訪問權限 |
其他接口
API | 描述 |
---|---|
DescribeRegions | 查詢支持的區域列表 |
DescribeSystemParameters | 查詢系統參數列表 |
四、調用方式
調用方式
更新時間: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字符集進行編碼。
公共參數
公共請求參數
公共請求參數是指每個接口都需要使用到的請求參數。
名稱 | 類型 | 是否必填 | 描述 |
---|---|---|---|
Format | String | 否 | 返回值的類型,支持JSON與XML。默認為XML |
Version | String | 是 | API版本號,為日期形式:YYYY-MM-DD,本版本對應為2016-07-14 |
AccessKeyId | String | 是 | 阿裏雲頒發給用戶的訪問服務所用的密鑰ID |
Signature | String | 是 | 簽名結果串,關於簽名的計算方法,請參見簽名機制。 |
SignatureMethod | String | 是 | 簽名方式,目前支持HMAC-SHA1 |
TimeStamp | String | 是 | 請求的時間戳。日期格式按照ISO8601標準表示,並需要使用UTC時間。格式為:YYYY-MM-DDThh:mm:ssZ。例如,2014-11-11T12:00:00Z(為北京時間2014年11月11日20點0分0秒) |
SignatureVersion | String | 是 | 簽名算法版本,目前版本是1.0 |
SignatureNonce | String | 是 | 唯一隨機數,用於防止網絡重放攻擊。用戶在不同請求間要使用不同的隨機數值 |
請求示例:
https://apigateway.cn-hangzhou.aliyuncs.com/?Format=xml
&Version=2016-07-14
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureMethod=HMACSHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&AccessKeyId=key-test
&TimeStamp=2016-08-08T08:00:00Z
公共返回參數
用戶發送的每次接口調用請求,無論成功與否,系統都會返回一個唯一識別碼RequestId給用戶。
XML返回示例:
<?xml version="1.0" encoding="UTF-8"?>
<!—結果的根結點-->
<接口名稱+Response>
<!—返回請求標簽-->
<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
<!—返回結果數據-->
</接口名稱+Response>
JSON返回示例:
{
"RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
/* 返回結果數據 */
}
返回結果
調用API服務後返回數據采用統一格式,返回的HTTP狀態碼為2xx,代表調用成功。返回4xx或5xx的HTTP狀態碼代表調用失敗。
調用成功返回的數據格式主要有XML和JSON兩種,外部系統可以在請求時傳入參數來制定返回的數據格式,默認為XML格式。
本文檔中的返回示例為了便於用戶查看,做了格式化處理,實際返回結果是沒有進行換行、縮進等處理的。
成功結果
XML返回示例:
(XML返回結果包括請求是否成功信息和具體的業務數據)
<?xml version="1.0" encoding="UTF-8"?>
<!—結果的根結點-->
<接口名稱+Response>
<!—返回請求標簽-->
<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
<!—返回結果數據-->
</接口名稱+Response>
JSON示例:
{
"RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
/* 返回結果數據 */
}
錯誤結果
調用接口出錯後,將不會返回結果數據。調用方可根據附表<錯誤查詢表>來定位錯誤原因。
當調用出錯時,HTTP請求返回一個4xx或5xx的HTTP狀態碼。返回的消息體中是具體的錯誤代碼及錯誤信息。另外還包含一個全局唯一的請求ID:RequestId和一個您該次請求訪問的站點ID:HostId。在調用方找不到錯誤原因時,可以聯系阿裏雲客服,並提供該HostId和RequestId,以便我們盡快幫您解決問題。
XML示例:
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<RequestId>8906582E-6722-409A-A6C4-0E7863B733A5</RequestId>
<HostId>apigateway.cn-hangzhou.aliyuncs.com</HostId>
<Code>InternalError</Code>
<Message>The request processing has failed due to some unknown error.</Message>
</Error>
JSON示例:
{
"RequestId": "8906582E-6722-409A-A6C4-0E7863B733A5",
"HostId": "apigateway.cn-hangzhou.aliyuncs.com",
"Code": "InternalError",
"Message": "The request processing has failed due to some unknown error."
}
五、簽名機制
詳細說明
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編碼的編碼規則是:
- 對於字符 A-Z、a-z、0-9以及字符“-”、“_”、“.”、“~”不編碼;
- 對於其他字符編碼成“%XY”的格式,其中XY是字符對應ASCII碼的16進制表示。比如英文的雙引號(”)對應的編碼就是%22
- 對於擴展的UTF-8字符,編碼成“%XY%ZA…”的格式;
- 需要說明的是英文空格( )要被編碼是%20,而不是加號(+)。
註:一般支持URL編碼的庫(比如Java中的java.net.URLEncoder)都是按照“application/x-www-form-urlencoded”的MIME類型的規則進行編碼的。
實現時可以直接使用這類方式進行編碼,把編碼後的字符串中加號(+)替換成%20、星號(*)替換成%2A、%7E替換回波浪號(~),即可得到上述規則描述的編碼字符串。
- 對編碼後的參數名稱和值使用英文等號(=)進行連接。
- 再把英文等號連接得到的字符串按參數名稱的字典順序依次使用&符號連接,即得到規範化請求字符串。
b. 使用上一步構造的規範化字符串按照下面的規則構造用於計算簽名的字符串:
StringToSign=
HTTPMethod + “&” +
percentEncode(“/”) + ”&” +
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為:
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就是:
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&”,則計算得到的簽名值是:
DRdMb%2F1m7PeToGRBApTl3wThyOg%3D
簽名後的請求URL為(註意增加了Signature參數):
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參考