Amazon API Gateway API 요청 및 응답 데이터 매핑 참조

이 섹션에서는 context, stage 또는 util 변수에 저장된 다른 데이터를 포함한 API의 메서드 요청 데이터에서 해당 통합 요청 파라미터로, 그리고 다른 데이터를 포함한 통합 응답 데이터에서 메서드 응답 파라미터로의 데이터 매핑을 설정하는 방법을 설명합니다. 메서드 요청 데이터는 요청 파라미터(경로, 쿼리 문자열, 헤더)와 본문을 포함합니다. 통합 응답 데이터는 응답 파라미터(헤더)와 본문을 포함합니다. 단계 변수 사용에 대한 자세한 내용은 Amazon API Gateway 단계 변수 참조 단원을 참조하십시오.

주제

• 통합 요청 파라미터에 메서드 요청 데이터 매핑
• 메서드 응답 헤더에 통합 응답 데이터 매핑
• 메서드와 통합 간의 요청 및 응답 페이로드 매핑
• 통합 패스스루 동작

통합 요청 파라미터에 메서드 요청 데이터 매핑

경로 변수 형식의 통합 요청 파라미터, 쿼리 문자열 또는 헤더를 정의된 메서드 요청 파라미터 및 페이로드에서 매핑할 수 있습니다.

다음 표에서 PARAM_NAME은 지정된 파라미터 유형의 메서드 요청 파라미터 이름입니다. 정규식 '^[a-zA-Z0-9._$-]+$]'와 일치해야 합니다. 이 파라미터가 이미 정의되어 있어야 참조할 수 있습니다. JSONPath_EXPRESSION은 요청 또는 응답 본문의 JSON 필드에 대한 JSONPath 표현식입니다.

참고

"$" 접두사는 이 구문에서 생략됩니다.

통합 요청 데이터 매핑 표현식
매핑된 데이터 원본	매핑 표현식
메서드 요청 경로	method.request.path.PARAM_NAME
메서드 요청 쿼리 문자열	method.request.querystring.PARAM_NAME
다중 값 메서드 요청 쿼리 문자열	method.request.multivaluequerystring.PARAM_NAME
메서드 요청 헤더	method.request.header.PARAM_NAME
다중 값 메서드 요청 헤더	method.request.multivalueheader.PARAM_NAME
메서드 요청 본문	method.request.body
메서드 요청 본문 () JsonPath	method.request.body.JSONPath_EXPRESSION.
단계 변수	stageVariables.VARIABLE_NAME
컨텍스트 변수	context.VARIABLE_NAME은 지원되는 컨텍스트 변수 중 하나여야 합니다.
정적 값	'STATIC_VALUE'. STATIC_VALUE는 문자열 리터럴이며 작은따옴표 쌍으로 묶여야 합니다.

예 OpenAPI의 메서드 요청 파라미터에서 매핑

다음 예제에서는 다음과 같이 매핑하는 OpenAPI 코드 조각을 보여줍니다.

• methodRequestHeaderParam라는 메서드 요청 헤더를 integrationPathParam라는 통합 요청 경로 파라미터로 매핑합니다.

• methodRequestQueryParam라는 다중 값 메서드 요청 쿼리 문자열은 integrationQueryParam라는 통합 요청 쿼리 문자열에 매핑됩니다.

...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam"
            
}
...
                
            

JSONPath 표현식을 사용하여 JSON 요청 본문의 필드에서 통합 요청 파라미터를 매핑할 수도 있습니다. 다음 표에서는 메서드 요청 본문 및 JSON 필드에 대한 매핑 표현식을 보여줍니다.

예 OpenAPI의 메서드 요청 본문에서 매핑

다음 예에서는 1) 메서드 요청 본문을 body-header라는 통합 요청 헤더에 매핑하고, 2) JSON 표현식(petstore.pets[0].name, $. 접두사 사용 안 함)으로 표시된 본문의 JSON 필드를 매핑하는 OpenAPI 코드 조각을 보여줍니다.

...
"requestParameters" : {
            
    "integration.request.header.body-header" : "method.request.body",
    "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name",
            
}
...
                
            

메서드 응답 헤더에 통합 응답 데이터 매핑

통합 응답 헤더, 통합 응답 본문, $context 변수 또는 정적 값에서 메서드 응답 헤더 파라미터를 매핑할 수 있습니다.

메서드 응답 헤더 매핑 표현식
매핑된 데이터 원본	매핑 표현식
통합 응답 헤더	integration.response.header.PARAM_NAME
통합 응답 헤더	integration.response.multivalueheader.PARAM_NAME
통합 응답 본문	integration.response.body
통합 응답 본문 (JsonPath)	integration.response.body.JSONPath_EXPRESSION
단계 변수	stageVariables.VARIABLE_NAME
컨텍스트 변수	context.VARIABLE_NAME은 지원되는 컨텍스트 변수 중 하나여야 합니다.
정적 값	'STATIC_VALUE'. STATIC_VALUE는 문자열 리터럴이며 작은따옴표 쌍으로 묶여야 합니다.

예 OpenAPI의 통합 응답에서 데이터 매핑

다음 예에서는 1) 통합 응답의 redirect.url JSONPath 필드에서 요청 응답의 location 헤더로 매핑하고, 2) 통합 응답의 x-app-id 헤더에서 메서드 응답의 id 헤더로 매핑하는 OpenAPI 코드 조각을 보여줍니다.

...
"responseParameters" : {
            
    "method.response.header.location" : "integration.response.body.redirect.url",
    "method.response.header.id" : "integration.response.header.x-app-id",
    "method.response.header.items" : "integration.response.multivalueheader.item",
            
}
...
                
            

메서드와 통합 간의 요청 및 응답 페이로드 매핑

API Gateway에서는 Velocity Template Language(VTL) 엔진을 사용하여 통합 요청 및 통합 응답에 대한 본문 매핑 템플릿을 처리합니다. 매핑 템플릿은 메서드 요청 페이로드를 해당 통합 요청 페이로드로 변환하고 통합 응답 본문을 메서드 응답 본문으로 변환합니다.

VTL 템플릿은 JSONPath 표현식, 기타 파라미터(예: 호출 컨텍스트, 단계 변수) 및 유틸리티 함수를 사용하여 JSON 데이터를 처리합니다.

페이로드의 데이터 구조를 설명하도록 모델을 정의한 경우 API Gateway에서는 모델을 사용하여 통합 요청 또는 통합 응답에 대한 스켈레톤 매핑 템플릿을 생성할 수 있습니다. 스켈레톤 템플릿을 보조 수단으로 사용하여 매핑 VTL 스크립트를 사용자 지정하고 확장할 수 있습니다. 페이로드의 데이터 구조에 대한 모델을 정의하지 않고 매핑 템플릿을 처음부터 생성할 수 있습니다.

VTL 매핑 템플릿 선택

API Gateway에서는 다음 로직을 사용하여 매핑 템플릿을 선택하고 VTL(Velocity Template Language)에서 메서드 요청에서 해당 통합 요청으로 또는 통합 응답에서 해당 메서드 응답으로 페이로드를 매핑합니다.

요청 페이로드의 경우 API Gateway에서는 요청의 Content-Type 헤더 값을 키로 사용하여 요청 페이로드에 대한 매핑 템플릿을 선택합니다. 응답 페이로드의 경우 API Gateway에서는 수신 요청의 Accept 헤더 값을 키로 사용하여 매핑 템플릿을 선택합니다.

Content-Type 헤더가 요청에 없는 경우 API Gateway에서는 기본값이 application/json인 것으로 가정합니다. 그런 요청의 경우 API Gateway에서는 application/json을 기본 키로 사용하여 매핑 템플릿을 선택합니다(정의되어 있는 경우). 이 키와 일치하는 템플릿이 없는 경우 API Gateway에서는 매핑되지 않은 템플릿을 통해 페이로드를 전달합니다(passthroughBehavior 속성이 WHEN_NO_MATCH 또는 WHEN_NO_TEMPLATES로 설정되어 있는 경우).

Accept 헤더가 요청에 지정되어 있지 않은 경우 API Gateway에서는 기본값이 application/json인 것으로 가정합니다. 이 경우 API Gateway에서는 application/json에 대한 기존 매핑 템플릿을 선택하여 응답 페이로드를 매핑합니다. application/json에 대한 템플릿이 정의되어 있지 않은 경우 API Gateway에서는 첫 번째 기존 템플릿을 선택한 후 이 템플릿을 기본값으로 사용하여 응답 페이로드를 매핑합니다. 마찬가지로 API Gateway에서는 지정된 Accept 헤더 값이 기존 템플릿 키와 일치하지 않을 경우 첫 번째 기존 템플릿을 사용합니다. 템플릿이 정의되어 있지 않은 경우 API Gateway에서는 매핑되지 않은 템플릿을 통해 응답 페이로드를 전달합니다.

예를 들어 API에 요청 페이로드에 대해 정의된 application/json 템플릿과 응답 페이로드에 대해 정의된 application/xml 템플릿이 있다고 가정합니다. 클라이언트가 요청에서 "Content-Type : application/json" 및 "Accept : application/xml" 헤더를 설정한 경우 요청 페이로드와 응답 페이로드는 모두 해당 매핑 템플릿에 따라 처리됩니다. Accept:application/xml 헤더가 없는 경우 application/xml 매핑 템플릿을 사용하여 응답 페이로드를 매핑합니다. 매핑되지 않은 응답 페이로드를 대신 반환하려면 application/json에 대해 빈 템플릿을 설정해야 합니다.

MIME 유형은 매핑 템플릿을 선택할 때 Accept 및 Content-Type 헤더에서만 사용됩니다. 예를 들어 "Content-Type: application/json; charset=UTF-8" 헤더에는 application/json 키가 선택된 요청 템플릿이 있습니다.