Version: 2.3.3

Request Transformer

用途說明#

此插件可以在請求到達上游服務器之前，將請求進行簡單的轉換。

這些轉換可以是簡單的替換，也可以是使用正則表達式匹配傳入請求部分的複雜轉換，會將匹配的字符串保存到變量中，再使用彈性的模板將這些字符串替換為轉換後的請求。

欄位配置說明#

啟用時可以看到以下畫面：

插件啟用配置圖

對應的配置說明如下：

參數	類型	說明
http_method	string	更改對上游請求的HTTP方法。
remove.headers	array of string	標頭名稱列表。對上游請求前，會將對應到的標頭名稱移除。
remove.querystring	array of string	字符串名稱列表。對上游請求前，會將對應之字符串名稱移除。
remove.body	array of string	參數名稱列表。僅當content-type為以下其中之一：`application/json`、`multipart /form-data`、`application/x-www-form-urlencoded`且參數名稱存在時，才刪除該參數。
replace.uri	string	使用此設定值更新上游請求URI。該值只能用於更新URI的路徑部分，而不能用於配置或主機名。
replace.body	array of string	參數名稱:值的列表。格式需照「參數名稱:值」的方式來設定。僅當content-type為以下其中之一：`application/json`、`multipart /form-data`、`application/x-www-form-urlencoded`，且若參數名稱已經存在，才會使用該參數名稱所對應的值來取代；若該參數名稱不存在，則會忽略。
replace.headers	array of string	標頭名稱:值的列表。格式需照「標頭名稱:值」的方式來設定。若標頭名稱已經存在，才會使用該標頭名稱所對應的值來取代；若該標頭名稱不存在，則會忽略。
replace.querystring	array of string	查詢字串名稱:值的列表。格式需照「查詢字串名稱:值」的方式來設定。若查詢字串名稱已經存在，才會使用該查詢字串名稱所對應的值來取代；若該查詢字串名稱不存在，則會忽略。
rename.headers	array of string	標頭名稱:值的列表。格式需照「標頭名稱:值」的方式來設定。若標頭名稱已經存在，才會將該標頭名稱更名；若該標頭名稱不存在，則會忽略。
rename.querystring	array of string	查詢字串名稱:值的列表。格式需照「查詢字串名稱:值」的方式來設定。若查詢字串名稱已經存在，才會將該查詢字串名稱改名；若該查詢字串名稱不存在，則會忽略。
rename.body	array of string	參數名稱:值的列表。格式需照「參數名稱:值」的方式來設定。僅當content-type為以下其中之一：`application/json`、`multipart /form-data`、`application/x-www-form-urlencoded`，且若參數名稱已經存在，才會將該參數名稱更名；若該參數名稱不存在，則會忽略。
add.headers	array of string	標頭名稱:值的列表。格式需照「標頭名稱:值」的方式來設定。只有當標頭名稱不存在的時候，才會使用設定值來設置一個新的標頭名稱；若該標頭名稱已存在，則會忽略。
add.querystring	array of string	查詢字串名稱:值的列表。格式需照「查詢字串名稱:值」的方式來設定。只有當查詢字串名稱不存在的時候，才會使用設定值來設置一個新的查詢字串名稱；若該查詢字串名稱已存在，則會忽略。
add.body	array of string	參數名稱:值的列表。格式需照「參數名稱:值」的方式來設定。僅當content-type為以下其中之一：`application/json`、`multipart /form-data`、`application/x-www-form-urlencoded`，且當參數名稱不存在的時候，才會使用設定值來設置一個新的參數名稱(使用表單編碼)；若該參數名稱已存在，則會忽略。
append.headers	array of string	標頭名稱:值的列表。格式需照「標頭名稱:值」的方式來設定。當標頭名稱不存在的時候，會使用設定值來設置一個新的標頭名稱。若該標頭名稱已存在，則會附加一個設定值的標頭名稱。
append.querystring	array of string	查詢字串名稱:值的列表。格式需照「查詢字串名稱:值」的方式來設定。當查詢字串名稱不存在的時候，會使用設定值來設置一個新的查詢字串名稱。若該查詢字串名稱已存在，則會附加一個設定值的查詢字串名稱。
append.body	array of string	參數名稱:值的列表。格式需照「參數名稱:值」的方式來設定。僅當content-type為以下其中之一：`application/json`、`application/x-www-form-urlencoded`，且當參數名稱不存在的時候，會使用設定值來設置一個新的參數名稱。若該參數名稱已存在，則會把兩個值(原本對應的值和新的設定值)匯總到一個陣列(array)內。

注意事項

如果設定值含有 ,，則不能使用逗號分隔的列表格式。
X-Forwarded-* 之名稱是Nginx編寫的非標準標頭名稱，用於向上游通知客戶端詳細訊息，無法被此插件所轉換。

實際執行配置的順序#

插件會按照以下順序之配置來執行請求的轉換：

remove → rename → replace → add → append

模板值設定說明#

你可以使用任何當前請求的標頭、查詢字串參數、和取得的URI groups作為模板值，來結合上述所說的欄位配置說明。

請求參數	模板值
header	`$(headers.<header_name>)`、 `$(headers["<Header-Name>"])` 、 `$(headers["<header-name>"])`)
querystring	`$(query_params.<query-param-name>)` 、 `$(query_params["<query-param-name>"])`)
captured URIs	`$(uri_captures.<group-name>)` 、 `$(uri_captures["<group-name>"])`)

要跳脫原模板的話，可以把模板值使用兩個單引號包覆，再放入原模板內，如：$('$(some_escaped_template)')

模板值進階說明#

內容為$(...)的佔位符被評估為Lua表達式，因此可以使用邏輯運算符號，例如：

Header-Name:$(uri_captures["user-id"] or query_params["user"] or "unknown")

首先會查找路徑參數(uri_captures)，如果找不到，則返回查詢字串參數(query_params)。假設兩者都不存在，則會回一個預設值：unknown。

可以將常量指定為動態佔位符之外的模板值的一部分。例如，從查詢字串(query_params)名為auth的參數來創建一個基本身份驗證標頭，而該標頭僅包含base64編碼的部分：

Authorization:Basic $(query_params["auth"])

注意事項

特別注意，在多行的模板中（像是上方的範例），請確保沒有添任何句尾的空白或是換行符號。因為這些空白及符號是位於佔位符之外，會被附加到生成的值上。

該環境是沙盒環境，意思是Lambdas除了字符串方法(string method)（如上述範例中的sub()）之外，無法訪問其他任何的元件庫函數。

用法示例#

在全局啟用插件#

從網站左邊Menu中 外掛插件 頁面中，點選右上角的 新增外掛插件 ：

全局啟用畫面

點選後，選擇 轉換 頁籤，並啟用Request Transformer，填寫內容參考欄位配置說明，設定成功後，任何請求(不分服務、路由、用戶)的請求轉換都會生效。

在服務端上啟用插件#

從網站左邊Menu中 服務 > 服務列表 頁面中，選擇要啟用此插件的服務，假設為google，點選對應的編輯按鈕：

服務啟用畫面1

在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

服務啟用畫面2

點選後，選擇 轉換 頁籤，並啟用Request Transformer，填寫內容參考欄位配置說明，設定成功後，僅有此服務(範例為google)的請求轉換會生效。

在路由端上啟用插件#

可以由兩種方式來選擇路由，並啟用插件：

方式一：路由列表#

從網站左邊Menu中 服務 > 路由列表 頁面中，選擇要啟用此插件的路由，假設為google，點選對應的編輯按鈕：

路由啟用畫面1

方式二：服務 > 服務列表 > 路由列表#

從網站左邊Menu中 服務 > 服務列表 頁面中，選擇要啟用此插件的路由所屬之服務(假設為google)，點選對應的編輯按鈕。

在編輯畫面中，點選上方的 路由 頁籤，選擇要啟用此插件的路由(假設為google)，點選對應的編輯按鈕：

路由啟用畫面2

承第1步，點擊上述兩種方式之一的編輯按鈕後，在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

路由啟用畫面3

點選新增外掛插件 按鈕後，選擇 轉換 頁籤，並啟用Request Transformer，填寫內容參考欄位配置說明，設定成功後，僅有此路由(範例為google)的請求轉換會生效。

在用戶端上啟用插件#

從網站左邊Menu中 訂閱用戶 > 用戶列表 頁面中，選擇要啟用此插件的用戶，假設為portaladmin，點選對應的編輯按鈕：

用戶啟用畫面1

在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

用戶啟用畫面2

點選後，選擇 轉換 頁籤，並啟用Request Transformer，填寫內容參考欄位配置說明，設定成功後，僅有此用戶(範例為portaladmin)的請求轉換會生效。

使用模板作為設定值的範例#

假設我有註冊一個名為backend的服務，此服務的回覆會將目前收到請求的路徑、標頭、內文全部都放在回應內。

先在該服務上啟用插件：

在add的區塊的headers欄位填入：x-consumer-id:$(headers['x-user-id'] or 'alice')
在remove的區塊的headers欄位填入：x-user-id
送出新增插件成功

接著，試著使用API Manager去呼叫該backend的服務，如下：

curl -XGET <API Manager protocol>://<API Manager ip>:<API Manager port>/forward \
-H 'x-user-id: Foo' \
-H 'X-API-HOST: backend' | json_pp

{
   "path" : "/forward",
   "header" : {
      "user-agent" : "curl/7.65.3",
      "x-forwarded-proto" : "http",
      "x-api-host" : "backend",
      "x-forwarded-path" : "/forward",
      "host" : "172.35.1.146",
      "accept" : "*/*",
      "connection" : "keep-alive",
      "x-consumer-id" : "Foo",
      "x-forwarded-host" : "localhost",
      "x-real-ip" : "172.18.0.1",
      "x-forwarded-for" : "172.18.0.1",
      "x-forwarded-port" : "8000"
   },
   "body" : {}
}

可以看到收到的標頭中，x-consumer-id的標頭值對應的就是傳入的x-user-id，而x-user-id這個標頭同時也被移除，看不到了。

假設再呼叫一次backend的服務，但不帶入x-user-id的標頭：

curl -XGET <API Manager protocol>://<API Manager ip>:<API Manager port>/forward \
-H 'X-API-HOST: backend' | json_pp

{
   "path" : "/forward",
   "header" : {
      "user-agent" : "curl/7.65.3",
      "x-forwarded-proto" : "http",
      "x-api-host" : "backend",
      "x-forwarded-path" : "/forward",
      "host" : "172.35.1.146",
      "accept" : "*/*",
      "connection" : "keep-alive",
      "x-consumer-id" : "alice",
      "x-forwarded-host" : "localhost",
      "x-real-ip" : "172.18.0.1",
      "x-forwarded-for" : "172.18.0.1",
      "x-forwarded-port" : "8000"
   },
   "body" : {}
}

可以看到，因為沒有傳入x-user-id，所以預設會在x-consmer-id標頭填入alice的值。

驗證#

請參考使用模板作為設定值的範例的內容來進行驗證。