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

Response Transformer

概要​

Response Transformerポリシーは、アウトバウンドポリシーであり、クライアントに配信する前に上流サービスから返されたレスポンスを修正します。この変換により、以下が可能になります：

  • レスポンスヘッダーやJSONフィールドの追加、削除、置換、名前変更、または追加。
  • レスポンスボディのフィルタリングまたは再構成。
  • 機密フィールドのマスキングまたは変換。
  • 異なるサービス間でのレスポンスペイロードの一貫性の確保。

これは、内部の実装詳細を隠したり、APIレスポンスを外部クライアント契約に合わせたりする場合に特に便利です。

注記

このプラグインはDBレスモードと互換性があり、grpc、grpcs、http、およびhttpsプロトコルをサポートしています。

設定の詳細​

設定は、変換操作を宣言するためのシンプルなキーと値の形式を使用します。各操作は特定の名前空間の下で定義され、ヘッダーとJSONボディフィールドの両方をサポートします。

変換の順序​

変換は以下の順序で実行されます：

  1. 削除
  2. 名前変更
  3. 置換
  4. 追加
  5. 追加

サポートされている変換フィールド​

Field Description
remove特定のレスポンスヘッダーまたはJSONキーを削除
rename既存のレスポンスヘッダーまたはJSONキーの名前を変更
replace既存のレスポンスヘッダーまたはJSONキーの値を置換
add新しいレスポンスヘッダーまたはJSONフィールドを追加（既存のフィールドがある場合は置換）
append既存のヘッダーやJSON配列に追加の値を追加

主要な設定オプション​

FieldDescription
config.add.headers新しいレスポンスヘッダーを追加します。形式：header-name:value
config.add.jsonレスポンスボディに新しいJSONキーを追加します。フォーマット: key:value
config.add.json_typesaddまたはappendを使用する際にJSON値のタイプ（文字列、ブール値、数値）を明示的に設定します。
config.append.headers既存のヘッダーに値を追加します。フォーマット: header-name:value
config.append.json既存のJSONキーに値を追加します。
config.remove.headers既存のレスポンスヘッダーを削除します。フォーマット: header-name
config.remove.jsonレスポンスから特定のJSONキーを削除します。
config.rename.headersヘッダーの名前を変更します。フォーマット: old-name:new-name
config.rename.jsonJSONキーの名前を変更します。フォーマット: old-key:new-key
config.replace.headersヘッダーの値を置き換えます。フォーマット: header-name:new-value
config.replace.jsonJSONキーの値を置き換えます。フォーマット: key:new-value
config.replace.json_types非文字列タイプ（ブール値、数値）でJSON値を置き換える際に必要です。

例​

基本的な例 - ヘッダーとJSONキーを追加する​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"add": {
				"headers": ["x-new-header:value", "x-another-header:something"],
				"json": ["new-json-key:some_value", "another-json-key:some_value"],
				"json_types": ["string", "boolean", "number"]
		}
	}
}'

ヘッダーを追加し、JSONフィールドを削除する​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"append": {
				"headers": ["x-header-1:v2", "x-header-2:v1"]
			},
			"remove": {
				"json": ["internal-field"]
		}
	}
}'

JSONキーとヘッダーの名前を変更する​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--data "name=response-transformer" \
	--data "config.rename.headers=old-header:new-header" \
	--data "config.rename.json=old-key:new-key"

複数のアクションを伴う完全な例​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"remove": {
				"headers": ["x-toremove", "x-another-one"],
				"json": ["json-key-toremove", "another-json-key"]
		},
		"add": {
			"headers": ["x-new-header:value"],
			"json": ["new-json-key:some_value"],
			"json_types": ["string"]
		},
		"append": {
			"headers": ["x-existing-header:some_value", "x-another-header:some_value"]
		}
	}
}'

追加の注意事項​

  • 値にカンマ (,) が含まれている場合、配列表記を使用する必要があります（例：JSON配列）。
  • このプラグインは、変換中にレスポンスボディ全体をメモリに保持するため、大きなレスポンスではパフォーマンスに影響を与える可能性があります。
  • gzip圧縮されたペイロードを変換する際は、Content-Encoding: gzip ヘッダーが適切に処理されることを確認してください。
  • このプラグインは、Nginxによって書き込まれた x-forwarded-* ヘッダーを変更しません。
  • JSONキーの値の型 (json_types) は、数値またはブールフィールドを追加または付加する際に重要です。

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