API Gateway支援的參數映射與校正邏輯 - API Gateway

1. 概述

API Gateway支援參數映射與校正邏輯，本篇文檔描述了API Gateway對轉寄用戶端發起的HTTP請求到HTTP後端服務，以及轉寄後端服務的HTTP應答到用戶端的處理規則，後端為阿里雲Function Compute的使用者請參考Function Compute。

目前API Gateway支援以下幾種傳輸處理方式：

入參透傳模式：API Gateway除Path位置的請求參數外，不對其他位置的請求參數進行映射與校正，使用者參數會透明傳遞給後端，詳細請閱讀章節3。
入參映射（過濾未知參數）模式：API Gateway會根據使用者配置的所有參數執行校正與映射，如果用戶端傳遞了未在配置中的參數，參數將會被API Gateway過濾掉，不會轉寄給後端，詳細請參考章節4。
入參映射（透傳未知參數）模式：在此模式下，如果使用者傳遞了未配置的參數，參數會被透傳給後端，詳細請參考章節5。

2. 參數位置與讀取規則

API Gateway支援從HTTP請求的各種位置上讀取參數，以及API Gateway提供的系統參數與使用者可配置的常量參數。

2.1. `path`參數

API Gateway支援從HTTP請求的分段路徑中提取參數的能力，使用path參數，需要首先將API的請求路徑配置為/path/[parameter]的格式，API Gateway會使用參數路徑方式去匹配HTTP請求中的路徑，請參考如下的例子：

請求路徑配置	輸入	參數提取結果
/request/to/[path]	/request/to/user1	path=user1
/[path1]/[path2].	/group1/user1	path1=group1, path2=user1
/[root]/*	/root/user1	root=root
/[root]	/root/user1	無法匹配

- API Gateway對於不符合RFC3986的非法輸入，直接返回錯誤碼：I400PH: Invalid Request Path- API Gateway支援的最大RequestUri長度為128KBytes, 超過這個限制時會返回錯誤碼：I413RL: Request Url too Large。

2.2. `query`參數

query參數為請求在QueryString中攜帶的參數，API Gateway會對請求QueryString通過=與&分割符進行索引值對的拆分，並使用UTF-8編碼做Url Decode，對於?a=和?a均被認為是值等於Null 字元串''的合法值，如：

QueryString輸入	參數提取結果
?a=1&b=2	a: "1", b: "2"。
?a=1&a=2	a: ["1", "2"] ; 參數為非`array`類型時僅使用第一個值。
?a	a: ""。
?a=	a: ""。
?=a&b=1	b: "1" ; `=a`這個輸入會被API Gateway忽略。

*API Gateway對於不符合RFC3986的非法輸入，直接返回錯誤碼：I400PH: Invalid Request Path。
*API Gateway支援的最大RequestUri長度為128KBytes, 超過這個限制時會返回錯誤碼：I413RL: Request Url too Large。

2.3. `formData`參數

formData參數為當請求的Content-Type為application/x-www-form-urlencoded時，訊息體中攜帶的值。如果Content-Type沒有指定charset=則網關會使用UTF-8編碼，否則使用charset中指定的字元集來進行Url Decode，對於Form的拆分與處理邏輯與QueryString中描述的處理方式一致。

當Content-Type為multipart/formdata時，網關支援進行檔案類型參數。

2.4. `header`參數

header參數會從HTTP請求的頭中讀取，比如X-User: aaa會被解析為X-User=aaa，特殊規則如下：

Header值中包含的前後空格會被截取掉。
如果存在多個重名Header且參數類型被配置為ARRAY則參數會被解析為數組，否則只取第一個值。
API Gateway使用ISO-8859-1編碼讀取和轉寄Header，非法字元會導致亂碼或其他非預期的結果。

2.5. `host`參數

host參數僅在使用者綁定了泛網域名稱和有效泛網域名稱模板時才有效，例如：綁定泛網域名稱*.api.foo.com且配置了泛網域名稱模板${user}.api.foo.com，則當收到請求1234.api.foo.com時，會讀取到host參數user=1234，使用者可以配置多個泛網域名稱模板，API Gateway會使用第一個匹配到的記錄來解析host參數，如果沒有記錄，則不會讀取到host參數，具體例子如下：

泛網域名稱模板配置	請求Host	參數提取結果
`${User}.api.io`	123.api.io	User: "123"
`${User}.${Group}.api.io`	123.g01.api.io	User: "123" Group: "g01"
`${Admin}.admin.api.io${User}.${Group}.api.io`.	123.api.io	User: "123"
`${Admin}.admin.api.io${User}.${Group}.api.io`	123.admin.api.io	Admin: "123"
`${Admin}.admin.api.io${User}.${Group}.api.io`	123.u00.api.io	User: "123"GroupId: "u00"
`${User}.${Group}.api.io${Admin}.admin.api.io`	123.admin.api.io	User: "123"Group: "admin"

在最後一個例子中，因為第一條記錄就已經命中匹配了，所以忽略後面的所有記錄。

3. 入參透傳模式

透傳模式支援以下方法： GET、PUT、POST、DELETE、PATCH、HEAD、OPTIONS。

3.1. 轉寄`用戶端請求`到`後端服務`

在透傳模式下，API Gateway在處理簽名和授權後，會將請求透明傳輸給後端，對於不同位置的透傳規則如下：

Path: 當使用者將API的請求路徑配置為/path/to/[user]的格式時，可以同時配置/path/backend/[user]到後端服務路徑上，API Gateway會識別前端路徑參數並將其映射到後端服務路徑上。
QueryString: 透明傳輸給後端，保持原始接收到的QueryString的順序與格式。
Header: 除一些系統頭和以X-Ca-開頭的Header以外，網關會透傳其餘的Header給後端，API Gateway會使用ISO-8859-1編碼讀取和轉寄Header，所以如果您在Header中傳遞了非法的編碼，可能會收到非預期的結果，對於系統以及API Gateway保留Header的處理邏輯，請參考“章節6.Http Header處理規則”。
Body: 包體會透明轉寄給後端，如果使用者在API配置中設定了自訂Content-Type，則使用設定的Content-Type，否則轉寄用戶端提供的Content-Type頭。

3.2. 轉寄`後端應答`給`用戶端`

在透傳模式下，如果後端成功返回應答，API Gateway會將來自後端服務的HTTP應答轉寄給用戶端，如果在處理過程中失敗了，由API Gateway建置錯誤碼，錯誤處理請參考錯誤碼表，透傳規則如下：

StatusCode: 透傳來自後端應答的錯誤碼。
Header: API Gateway會過濾或添加一些系統Header和名字以X-Ca-起始的保留Header，透傳來自後端應答的其他Header，詳細參考章節6. Http Header處理規則。
Body: API Gateway會將來自後端服務應答的包體轉寄給用戶端，後端應答的Content-Type為空白，則補充一個預設值：application/oct-stream。

可以通過使用錯誤碼映射外掛程式，來改寫用戶端的應答碼。

4. 入參映射（過濾未知參數）模式

API Gateway會根據使用者配置的所有參數執行校正與映射，如果用戶端傳遞了未在配置中的參數，參數將會被API Gateway過濾掉，不會轉寄給後端，如果您希望網關轉寄未配置參數給後端，請參考章節5。在參數映射模式下，API Gateway可以支援query、header、host、path、formData位置下的參數，並進行參數值的類型判斷、校正，並進行向後端的映射。

4.1. 參數類型

API Gateway目前支援以下參數類型：

類型	類型說明	格式支援	可選校正方式
String	字串	不限	最小長度、最大長度、枚舉值、正則。
Integer	32位整數	`1`, `-1`, `100`。	最小值，最大值，枚舉值。
Long	64位整數	`-1233`, `1001`。	最小值，最大值，枚舉值。
Double	浮點數	`100`,`0.1`,`9E-9`,`1.01E16`。	最小值，最大值。
Boolean	布爾值	`true`, `false`；（忽略大小寫）
File	檔案類型	僅用於`multipart/form-data`。	最小長度、最大長度。
Array	數群組類型	參考數組欄位類型。	數組欄位類型上的校正。

Float類型與Double類型在處理標準與過程一致，不再單獨列出。

4.2. 參數校正配置

參數校正可通過控制台、OpenAPI或匯入Swagger的方式設定，設定方式與含義如下：

名稱	說明	OpenAPI的欄位	Swagger中的欄位
參數名	必選，API內唯一。	ApiParameterName	name
參數位置	必選。	Location	location
參數類型	可選，預設類型為`String`。	ParameterType	type
數組參數類型	可選，參數類型為`Array`時，指定數組欄位類型。	ArrayItemsType	items.type
是否必填	可選，預設為`否`。	Required	required
預設值	可選，Null 字元串`''`不是有效預設值。	DefaultValue	default
最大值	可選，輸入值必須`小於等於`最大值。	MaxValue	maximum
最小值	可選，輸入值必須`大於等於`最小值。	MinValue	minimum
最大長度	可選，僅對`String`類型有效。	MaxLength	maxLength
最小長度	可選，僅對`String`類型有效。	MinLength	minLength
Regex	可選，僅對`String`類型有效。	RegularExpression	pattern
枚舉值	可選。	EnumValue	enum

OpenAPI的參數配置參考：建立API->RequestParameter。
Swagger參數配置參考：通過匯入Swagger建立API。

參數校正的一些匹配規則：

OpenAPI與Swagger對參數類型的取值定義不同，本節的描述參考Swagger標準。
如果不設定參數類型，預設的類型為String。
如果參數類型的輸入格式與當前類型的支援格式不符，會報錯誤碼： I400IP Invalid Parameter :...。
如果參數設定為了必選，如果用戶端的請求中不傳遞，網關會阻攔這個請求，並報錯誤碼： I400MP Invalid Parameter Required:...。
選擇性參數可以配置預設值，當用戶端不傳遞這個參數時，使用配置的預設值傳遞給後端，但API Gateway不認為Null 字元串： ''是合法的預設值，網關不會將配置為空白字串的預設值傳給後端。
當參數處於query,formData位置時，對於形如a或a=格式的輸入，如?b=1&a，API Gateway認為輸入參數為空白字串''。
- 此時如果參數設定必選，不報錯。
- 如果參數設定為可選且配置了預設值，網關將不使用預設值，將空串傳遞給後端。
當參數類型為Integer,Long,Float,Double值時，如果輸入為空白字串''，則認為此參數沒有傳遞。
- 當此參數為必選時，網關會阻攔這個請求，並報錯誤碼400: <I400MP> Invalid Parameter Required: ...。
- 當此參數為可選且存在預設值配置時，使用預設值發送給後端。
最小長度與最大長度的判斷依據為大於等於最小長度和小於等於最大長度，可以單獨設定，或同時設定，只有大於0的配置才會生效。
Regex的最大允許長度為40個字元。
字串類型和數字類型均可以使用枚舉設定，使用逗號分隔：比如江,河,湖,海，如果輸入值不在列表中，會報錯誤碼：I400IP: Invalid Parameter :...。
如果參數類型設定為ARRAY數群組類型，只有query, formData, header三個位置的參數支援數組格式，數組參數的校正規則對可以對每個數組元素生效，類型由數組參數類型欄位指定，預設為字串。

4.3. 後端參數映射規則

使用者可以設定參數的後端位置與後端名稱，API Gateway會在發送請求給後端服務時，進行參數位置與名稱的轉換。
API Gateway的參數類型僅用於校正，不會變更傳遞到後端的形式，如Double類型的參數如果輸入為a=1不會被更改為a=1.0。
參數類型為ARRAY時，後端位置只能為query、formData,header，發送給後端時使用多個參數或多個Header的方式，如a=1&a=2, 不使用a=1,2的方式。
傳遞給後端的QueryString會使用UTF-8編碼的URL Encode進行重新組裝。
如果參數中包含了Form參數時，會使用application/x-www-form-urlencoded; charset=utf-8或multipart/formdata; charset=utf-8作為包體格式發送給後端。
- 如果參數中包含File類型，會使用multipart/formdata; charset=utf-8進行組裝，否則使用application/x-www-form-urlencoded; charset=utf-8進行組裝。
- 如果使用者在API定義的後端服務部分，設定了自訂Content-Type，則會以使用者的Content-Type發給後端，如果使用者自訂的Content-Type形式屬於application/x-www-form-urlencoded; charset=???或multipart/formdata; charset=???形式，則使用自訂中描述的Encoding進行組裝，對於其他的Content-Type，不進行編碼的特殊處理。
當轉寄的參數處於header位置時，網關會使用ISO8859-1編碼進行轉換和發送。

4.4. 轉寄`後端應答`給`用戶端`

在映射模式下，如果後端成功返回應答，API Gateway會將來自後端服務的HTTP應答轉寄給用戶端，如果在處理過程中失敗了，由API Gateway建置錯誤碼，錯誤處理請參考API Gateway異常處理，透傳規則如下：

StatusCode: 透傳來自後端應答的錯誤碼。
Header: API Gateway會過濾或添加一些系統Header和名字以X-Ca-起始的保留Header，透傳來自後端應答的其他Header，詳細參考章節6. Http Header處理規則。
Body: API Gateway會將來自後端服務應答的包體轉寄給用戶端，後端應答的Content-Type為空白，則補充一個預設值：application/oct-stream。

可以通過使用錯誤碼映射外掛程式，來改寫用戶端的應答碼。

5. 入參映射（透傳未知參數）模式

入參映射（透傳未知參數）模式與入參映射（過濾未知參數）模式的校正與處理機制一致，區別在於透傳未知參數模式下，請求中的未知參數會在原位置上透傳給後端，而過濾未知參數模式下，未知參數會被過濾掉。

6. Http Header處理規則

一般來講，所有以X-Ca-開頭的Header均為API Gateway保留Header, API Gateway會對X-Ca-的Header做特殊處理，請不要在您的業務中使用X-Ca-開頭的頭，否則會導致頭被過濾，或產生未預期的行為。

HeaderName	請求處理方式	應答處理方式
Connection	重建	重建
Keep-Alive	重建	重建
Proxy-Authenticate	重建	重建
Proxy-Authorization	重建	重建
Trailer	重建	重建
TE	重建	重建
Transfer-Encoding	重建	重建
Upgrade	重建	重建
Host	重建
Authorization	校正、映射或透傳（當後端服務是HTTP函數時，會被HTTP函數的Authorization覆蓋）。
Date		透傳或添加預設。
Content-Type	映射或透傳。	透傳或添加預設。
Content-Length	映射或透傳。
Content-MD5	校正並透傳。
Via	添加網關記錄。
X-Forwarded-For	在右側添加用戶端IP。
X-Forwarded-Proto	添加用戶端請求協議：'http',https','ws','wss'。
User-Agent	透傳或添加網關UserAgent。
Server		透傳或添加預設。

所有標記為重建的Header不會透傳，網關會重新添加為網關設定的值。
未在表中出現的Header如果用戶端請求為透傳模式，則將要求標頭透傳給後端，如果為映射模式，則除預設的HttpHeader外，其餘的Header會被過濾。
未在表中出現的應答的Header預設均透傳給用戶端。

1. 概述

2. 參數位置與讀取規則

2.1. path參數

2.2. query參數

2.3. formData參數

2.4. header參數

2.5. host參數