メインコンテンツまでスキップ

Request Transformer

概要​

Request Transformerポリシーは、インバウンドポリシーであり、上流サービスに転送される前に、受信したHTTPリクエストの動的な変更を可能にします。これには以下の機能が含まれます：

  • ヘッダー、クエリ文字列、およびボディパラメータの削除または追加。
  • 特定のリクエストフィールドの名前変更または置換。
  • テンプレートや静的値を使用した変換ロジックの適用。

これは、APIをレガシーシステムに適応させたり、機密情報を追加またはマスクしたり、進化するAPI契約をサポートしたりするシナリオで役立ちます。

Kong Gatewayは、リクエスト変換を以下の順序で処理します：

  1. 削除
  2. 名前変更
  3. 置換
  4. 追加
  5. 追加（末尾に）

設定の詳細​

ユーザーインターフェースは動的な設定入力を提供します。緑のプラスアイコンをクリックすることで、複数の変換行を追加できます。

サポートされている変換タイプ​

Field Format Description
config.remove.headersx-remove-header指定されたヘッダーを削除します。
config.remove.querystringparam1,param2特定のクエリパラメータを削除します。
config.remove.bodyparam1,param2特定のフォームフィールドを削除します。
config.rename.headersold:newヘッダーの名前を変更します。
config.rename.querystringold:newクエリパラメータの名前を変更します。
config.rename.bodyold:newボディフィールドの名前を変更します。
config.replace.headerskey:valueヘッダーの値を置換します。
config.replace.querystringkey:valueクエリパラメータの値を置換します。
config.replace.bodykey:valueボディフィールドの値を置換します。
config.add.headerskey:value新しいヘッダーを追加します。
config.add.querystringkey:value新しいクエリパラメータを追加します。
config.add.bodykey:value新しいフォームフィールドを追加します。
config.append.headerskey:value既存のヘッダー値に追加します。
config.append.querystringkey:value既存のクエリパラメータ値に追加します。
config.append.bodykey:value既存のボディパラメータ値に追加します。
  • フィールドの値にカンマが含まれている場合は、カンマ区切りの文字列の代わりに配列表記を使用してください。
例: headers[1]=h1:v1
  • x-forwarded-* ヘッダー（Nginx によって追加されたもの）は、このプラグインで変更することはできません。
  • すべての設定タイプについて、リスト項目は「key:value」形式またはリネームのための「old:new」形式に従う必要があります。

テンプレート​

テンプレートを使用して、受信リクエストから値を動的に挿入できます：

ヘッダー:

${headers.<header_name>}

クエリ:

${query_params.<param_name>}

URI キャプチャ:

${uri_captures.<group_name>}

共有:

${shared.<variable_name>}

テンプレート内で Lua 式を使用することもできます：

Authorization:$(function()
	local value = headers.Authorization
	if not value then return end
	if value:sub(1,6) == "Basic " then return value end
	return "Basic " .. value
end())

例​

基本的なリクエスト変換​

ヘッダーを削除し、ボディフィールドの名前を変更し、クエリパラメータを追加することで、受信リクエストを変換します：

{
	"name": "request-transformer",
	"config": {
		"remove": {
		"headers": ["x-remove-header"],
		"body": ["formparam-toremove"],
		"querystring": ["qs-toremove"]
		},
		"rename": {
		"body": ["param-old:param-new"]
		},
		"add": {
		"querystring": ["new-param:some_value"],
		"headers": ["x-new-header:some_value"]
		}
	}
}

Kong Admin API を介しての有効化​

curl -X POST [http://localhost:8001/services/{serviceName}/plugins](http://localhost:8001/services/%7BserviceName%7D/plugins) \
--data "name=request-transformer" \
--data "config.add.body=new-field:defaultvalue"

1 回のリクエストでの追加と削除​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
--data "name=request-transformer" \
--data "config.append.headers=h1:v2,h2:v1" \
--data "config.remove.body=p1"

URIキャプチャテンプレートの使用​

--data "config.add.headers=x-user-id:${uri_captures['user_id']}"

複数のヘッダー（配列として）​

--data "config.add.headers[1]=h1:v1" \
--data "config.add.headers[2]=h2:v1"

このプラグインは非常に柔軟であり、クライアントの期待と上流APIの仕様との違いを橋渡しする重要な役割を果たします。

ポリシーの使用に関する詳細な指示や高度な例については、次のガイドを参照してください: Request Transformer - Plugin | Kong Docs