본문으로 건너뛰기

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"

한 요청에서 추가 및 제거​

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