REST API용 매핑 템플릿 - Amazon API Gateway
매핑 템플릿 예시복잡한 매핑 템플릿 예시

REST API용 매핑 템플릿

API Gateway에서 API 메서드 요청 또는 응답은 통합 요청 페이로드 또는 응답에서 여러 유형의 페이로드를 취할 수 있습니다.

데이터를 다음과 같이 변환할 수 있습니다.

  • 페이로드를 API 지정 형식에 일치시킵니다.

  • API의 요청 및 응답 파라미터와 상태 코드를 재정의합니다.

  • 클라이언트가 선택한 응답 헤더를 반환합니다.

  • HTTP 프록시 또는 AWS 서비스 프록시의 메서드 요청에 경로 파라미터, 쿼리 문자열 파라미터 또는 헤더 파라미터를 연결합니다.

  • Amazon DynamoDB 또는 Lambda 함수 또는 HTTP 엔드포인트와 같은 AWS 서비스와의 통합을 사용하여 전송할 데이터를 선택합니다.

매핑 템플릿을 사용하여 데이터를 변환할 수 있습니다. 매핑 템플릿이란 Velocity Template Language(VTL)로 표현된 스크립트로, JSONPath를 사용하여 페이로드에 적용됩니다.

이 섹션에서는 매핑 템플릿과 관련된 개념 정보를 설명합니다. API Gateway REST API의 매핑 템플릿을 생성하는 방법에 대한 지침은 API Gateway에서 데이터 변환 설정 섹션을 참조하세요.

매핑 템플릿 예시

다음 예시는 통합 요청에 대한 입력 데이터입니다.

[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

다음 예시는 통합 요청 데이터를 변환하기 위한 매핑 템플릿입니다.

#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]

다음 예시는 변환의 출력 데이터입니다.

[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]

다음 다이어그램은 이 매핑 템플릿의 세부 정보를 보여줍니다.

매핑 템플릿 예시

  1. $inputRoot 변수는 이전 단원에서 다룬 원본 JSON 데이터의 루트 객체를 나타냅니다. 지시어는 # 기호로 시작됩니다.

  2. foreach 루프는 원래 JSON 데이터의 각 객체를 반복합니다.

  3. 설명은 Pet의 id와 원래 JSON 데이터의 type를 결합한 것입니다.

  4. askingPrice는 원래 JSON 데이터의 price입니다.

1 #set($inputRoot = $input.path('$'))
2 [
3 #foreach($elem in $inputRoot)
4  {
5    "description" : "Item $elem.id is a $elem.type.",
6    "askingPrice" : $elem.price
7  }#if($foreach.hasNext),#end
8 #end
9 ]

이 매핑 템플릿은 다음과 같습니다.

  1. 1번째 줄에서 $inputRoot 변수는 이전 섹션에서 다룬 원래 JSON 데이터의 루트 객체를 나타냅니다. 지시어는 # 기호로 시작됩니다.

  2. 3번째 줄의 foreach 루프는 원래 JSON 데이터의 각 객체를 반복합니다.

  3. 5번째 줄의 description은 Pet의 id와 원래 JSON 데이터의 type를 결합한 것입니다.

  4. 6번째 줄의 askingPrice는 원래 JSON 데이터의 price입니다.

VTL(Velocity Template Language)에 대한 자세한 내용은 Apache Velocity - VTL 참조를 참조하십시오. JSONPath에 대한 자세한 내용은 JSONPath - JSON용 XPath를 참조하십시오.

매핑 템플릿은 JSON 객체를 기본 데이터로 간주합니다. 이 데이터를 위한 모델을 정의할 필요는 없습니다. 그러나 출력 데이터에 대한 모델을 사용하면 이전 데이터를 언어별 객체로 반환할 수 있습니다. 자세한 내용은 REST API에 대한 데이터 모델 단원을 참조하십시오.

복잡한 매핑 템플릿 예시

또한 더 복잡한 매핑 템플릿을 생성할 수 있습니다. 다음 예시에서는 반려동물을 살 여력이 있는지 확인하기 위해 참조 연결과 컷오프 100을 사용하는 것을 보여줍니다.

다음 예시는 통합 요청에 대한 입력 데이터입니다.

[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

다음 예시는 통합 요청 데이터를 변환하기 위한 매핑 템플릿입니다.

#set($inputRoot = $input.path('$'))
#set($cheap = 100)
[
#foreach($elem in $inputRoot)
  {
#set($name = "${elem.type}number$elem.id")
    "name" : $name,
    "description" : "Item $elem.id is a $elem.type.",
    #if($elem.price > $cheap )#set ($afford = 'too much!') #{else}#set ($afford = $elem.price)#end
"askingPrice" : $afford
  }#if($foreach.hasNext),#end
  
#end
]

다음 예시는 변환의 출력 데이터입니다.

[
  {
    "name" : dognumber1,
    "description" : "Item 1 is a dog.",
    "askingPrice" : too much!
  },  
  {
    "name" : catnumber2,
    "description" : "Item 2 is a cat.",
    "askingPrice" : too much!
  },  
  {
    "name" : fishnumber3,
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }  
]

더 복잡한 데이터 모델도 확인할 수 있습니다. API Gateway용 데이터 모델 및 매핑 템플릿 예시 섹션을 참조하세요.