본문으로 건너뛰기

Request Transformer

개요​

Request Transformer 정책은 인바운드 정책으로, 수신된 HTTP 요청을 업스트림 서비스로 전달하기 전에 동적으로 수정할 수 있게 해줍니다. 여기에는 다음과 같은 기능이 포함됩니다:

  • 헤더, 쿼리 문자열 및 본문 매개변수를 제거하거나 추가합니다.
  • 특정 요청 필드를 이름 변경하거나 교체합니다.
  • 템플릿이나 정적 값을 사용하여 변환 논리를 적용합니다.

이는 API를 레거시 시스템에 맞추거나, 민감한 정보를 추가하거나 마스킹하거나, 진화하는 API 계약을 지원하는 등의 시나리오에서 유용합니다.

Kong Gateway는 요청 변환을 다음 순서로 처리합니다:

  1. 제거
  2. 이름 변경
  3. 교체
  4. 추가
  5. 추가(append)

구성 세부정보​

사용자 인터페이스는 동적 구성 입력을 제공합니다. 녹색 더하기 아이콘을 클릭하여 여러 변환 라인을 추가할 수 있습니다.

지원되는 변환 유형​

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"

한 요청에서 추가 및 제거​

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