如何通過錄入API的定義來建立API - API Gateway

建立API即錄入API的定義，需要錄入API的基本資料、服務資訊、請求資訊、和返回資訊，然後對建立的API進行調試，及進行安全配置。經測試證明API可用後，可發布上線供使用者使用。

1 定義 API

在API Gateway控制台中API列表頁面，單擊建立API，即進入API的建立和定義流程。

1.1 定義請求的基本資料

參數	描述
API分組	分組是API的嵌入式管理單元，建立API之前您需要先建立分組，選擇分組即選擇Region。
API名稱	所建立的API的名稱。API名稱標識需在所屬分組內具有唯一性。
安全認證方式	目前支援阿里雲APP、和無認證。阿里雲APP：要求要求者調用該API時，需通過對APP的身份認證。無認證：即任何人知曉該API的請求定義後，均可發起請求，網關不對其做身分識別驗證，均會將請求轉寄至您的後端服務。（強烈不建議使用此模式。）
簽名演算法	參與簽名的演算法 HMAC_SHA256 HMAC_SHA1和HMAC_SHA256：表示同時支援這2種簽名演算法。
描述	填寫API的相關描述。

1.2 定義API請求

定義使用者如何請求API，包括協議、請求Path、HTTP Method、入參請求模式和入參定義。

參數	描述
請求協議	支援HTTP、HTTPS。
請求Path	Path指相對於服務host，API的請求路徑。請求Path可以與後端服務實際Path不同，您可以隨意撰寫合法且具有明確語義的Path給使用者使用。您可以在請求Path中配置動態參數，即要求使用者在Path中傳入參數，同時您的後端可以不在Path中接收這些參數，可以映射為在Query、Header等位置接收。
HTTP Method	支援標準的HTTP Method，可選擇PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS或ANY。
入參定義模式	可選入參映射（過濾未知參數）、入參映射（透傳未知參數）和入參透傳。入參映射（過濾未知參數）：表示Query，Path 和 Body Form位置的參數需要配置前後端映射，網關只會透傳給後端配置過的參數，其他參數會被過濾掉。入參映射（透傳未知參數）：表示Query，Path 和 Body Form位置的參數需要配置前後端映射，網關除配置的請求參數外，不對其他位置的請求參數進行映射與校正，使用者參數會透明傳遞給後端。入參透傳：表示不需要在入參定義處配置Query，Body Form參數（PATH參數仍需要配置）。用戶端傳給網關的參數都會被網關透傳給後端

配置入參定義：定義您API的請求入參，即配置使用者需要在什麼位置傳入什麼參數。可選位置有Head、Query、Body、Path（Parameter Path），尤其當您在Path中配置了動態參數，那麼在入參配置時需要對動態參數做配置說明。支援的參數類型有String、Integer、Boolean。

需要注意所有參數的名稱會校正是否唯一。
您可以使用左側的快速鍵快速調整參數順序。
您可以使用操作表徵圖下的移除選項，移除不需要的參數。

說明

如果您在Path中配置了動態參數，存在參數位置為Parameter Path的同名參數。

設定參數校正規則：您可以單擊操作表徵圖中的編輯更多配置校正規則。如String的長度，Number的枚舉等等。網關會參照校正規則對請求做初步校正，如果入參不合法，則不會到達您的後端服務，大大的降低了後端服務的壓力。

1.3 定義後端服務資訊

這部分主要是定義一些參數的前後端映射，具體描述的是您後端真實服務的API配置。使用者請求到達網關後，網關會根據您的後端配置映射為對應實際後端服務的請求形式，去請求您的後端。包括後端服務地址、後端Path、後端逾時時間、參數映射、常量參數、系統參數。

後端基礎定義

參數	描述
後端服務類型	目前支援HTTP/HTTPS、Function Compute、VPC、OSS、Mock五種類型。 HTTP(s): 預設類型，後端是HTTP或者HTTPS協議的服務接入，當網關和後端服務網路能直接連通時使用。若是HTTPS服務，後端服務必須有SSL認證。 Function Compute：若選擇Function Compute為後端服務，需先在Function Compute控制台中建立函數，並需填入函數服務名稱和函數名稱，和擷取Function Compute角色Arn。 VPC: 當後端服務在某個VPC內時使用。 OSS：當後端是OSS時使用。 Mock: 用於類比最初預定的返回結果HTTP/HTTPS：若您的服務為HTTP/HTTPS服務，則選擇此項。說明海外region及中國香港不支援建立HTTP/OSS類型後端服務。
VPC授權名稱	當您的後端服務在VPC中時，需要填寫建立VPC授權時設定的VPC授權名稱。
後端服務地址	後端服務的Host，可以是一個網域名稱，也可以是http(s)://host:port的形式。填寫時，必須包含http://或https://。
後端請求Path	Path是您的API服務在您後端伺服器上的實際請求路徑。若您後端Path需要接收動態參數，則需要聲明調用者需傳入參數的具體位置和參數名，即宣告對應關係。
HTTP Method	支援標準的HTTP Method，可選擇PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS或ANY。
後端逾時	指API請求到達網關後，網關去調用API後端服務的回應時間。由網關請求後端開始到網關收到後端返回結果。該值不能超過30秒。超過該值網關會放棄請求後端服務，並給使用者返回相應的錯誤資訊。

配置後端服務參數： 網關支援參數在前端、後端的全映射，包括名稱映射和位置映射。位置映射包括Path、Header、Query、Body的混排映射。也就是說，您可以將您的後端服務通過映射完成封裝成更規範、更專業的API形態。這部分就是在聲明前後端API映射關係的。

配置常量參數：您可以配置常量參數。您配置的常量參數對您的使用者不可見，但是API Gateway會在中轉請求時，將這些參數加入到請求中的指定位置，再傳遞至後端服務，實現您的後端的一些業務需求。比如您需要網關每次請求您後端時都帶有參數abc，您可以直接將abc配置為常量參數。請求達到網關後，網關會自動在指定位置加上該參數再去請求您的後端。

配置系統參數：指API Gateway的系統參數。預設系統參數不會傳遞給您，但是如果您需要擷取系統參數，您可以在API裡配置接收位置和名稱。具體內容如下表：

參數名稱	參數含義
CaClientIp	發送請求的用戶端IP（若您配置了WAF、CDN等，則記錄的是回源IP，真實IP需要在X-Forwarded-For中查看）
CaDomain	發送請求的網域名稱
CaRequestHandleTime	請求時間（格林威治時間）
CaRequestId	RequestId
CaApiName	API名稱
CaHttpSchema	使用者調用API使用的協議，http或者https
CaProxy	代理（AliCloudApiGateway）
CaClientUa	請求用戶端的User-Agent
CaCloudMarketInstanceId	雲市場商品首次購買的執行個體ID
CaAppId	請求的APP的ID
CaAppKey	請求的APP的KEY
CaAppExtendInfo	請求的APP的拓展欄位
CaStage	請求的環境（RELEASE、TEST、PRE）
CaInstanceId	API所屬的執行個體ID
CaSourceVpcId	用戶端IP所屬的Vpc

可以在分組詳情中設定透傳HOST頭（網域名稱頭），開啟後API Gateway會將請求網域名稱透傳至後端，若沒有開啟，後端收到的是使用者在API Gateway填寫的後端HOST。樣本如下：

樣本中API分組綁定的請求HOST為xuemeng.XXXX.com，API後端HOST為apigatewayXXXXXXalicloudapi.com:8080，配置前後如下

透傳HOST頭（網域名稱頭）開啟時：

Host: xuemeng.XXXX.com

透傳HOST頭（網域名稱頭）未開啟時：

Host: apigatewayXXXXXXalicloudapi.com:8080

說明

您需確保您錄入的所有參數的參數名稱全域唯一，包括Path中的動態參數、Headers參數、Query參數、Body參數（非二進位）、常量參數、系統參數。如果您同時在Headers和Query裡各有一個名為name的參數，將會導致錯誤

1.4 定義返回結果

錄入返回ContentType、返回結果樣本、失敗返回結果樣本和錯誤碼定義。

2 API 調試

API定義錄入完成後，您可以在API調試頁面調試API，以確定API的可用性。

API建立、定義完成後，頁面自動跳轉到API列表頁。您可以通過此頁面按鈕，測試建立的API是否可用，請求鏈路是否正確。

單擊API名稱或管理按鈕，進入API定義頁面。
單擊左側導覽列中調試API。
輸入請求參數，單擊發送請求。

返回結果將顯示在右側頁面。

如果調試返回成功結果，則說明該API可以使用。

如果傳回碼為4XX或5XX，則表示存在錯誤。請參見如何擷取錯誤資訊和錯誤碼表。

3 後續步驟

完成以上定義後和初步調試後，您就完成了API的建立。您發行就緒API到測試、預發、線上環境，繼續調試或供使用者使用。還可以為API綁定用戶端簽名說明文檔等安全配置。