1. 程式人生 > >握手API網關(7)開發指南-API參考

握手API網關(7)開發指南-API參考

custom psd title control test 機制 找不到 con 列表

一、簡介

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

術語表

術語全稱中文說明
Region 地域 用戶開放API,需選擇API在API網關的部署地域,建議選擇與後端服務相同的Region。
API 應用程序編程接口 用戶開放API,在API網關錄入API,以提供接口的方式對外提供服務或者數據。
Group API Group API分組 一組API。
  • 用戶開放API,首先需要創建API分組
  • 每個API分組擁有一個二級域名,兩個Stage
  • 用戶需要將已經備案且解析至分組二級域名的獨立域名綁定到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 唯一隨機數,用於防止網絡重放攻擊。用戶在不同請求間要使用不同的隨機數值

請求示例:

  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 IDAccess Key Secret進行對稱加密的方法來驗證請求者身份。Access Key IDAccess 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類型的規則進行編碼的。
  2. 實現時可以直接使用這類方式進行編碼,把編碼後的字符串中加號(+)替換成%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參考