# API Gateway에서 REST API의 데이터 변환 매핑
<a name="models-mappings"></a>

매핑 템플릿 변환은 매핑 템플릿을 사용하여 통합 요청 또는 통합 응답을 수정합니다. *매핑 템플릿*이란 [Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)로 표현된 스크립트로, [JSONPath](https://goessner.net/articles/JsonPath/)를 사용하여 `Content-type` 헤더 기반 페이로드에 적용됩니다. 매핑 템플릿 변환을 사용할 경우 매핑 템플릿을 사용합니다. 이 섹션에서는 매핑 템플릿과 관련된 개념 정보를 설명합니다.

다음 다이어그램은 PetStore 통합 엔드포인트와 통합된 `POST /pets` 리소스의 요청 수명 주기를 보여줍니다. 이 API에서 사용자는 반려동물에 대한 데이터를 전송하고 통합 엔드포인트는 반려동물과 관련된 입양 요금을 반환합니다. 이 요청 수명 주기에서 매핑 템플릿 변환은 요청 본문을 통합 엔드포인트로 필터링하고 통합 엔드포인트에서 응답 본문을 필터링합니다.

![\[요청 수명 주기 예제\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/mapping-template-transforms.png)


다음 섹션에서는 요청 및 응답 수명 주기를 설명합니다.

## 메서드 요청 및 통합 요청
<a name="models-mappings-request"></a>

이전 예제에서 메서드 요청으로 전송된 요청 본문인 경우:

```
POST /pets
    HTTP/1.1
    Host:abcd1234.us-west-2.amazonaws.com
    Content-type: application/json
    
  {
    "id": 1,
    "type": "dog",
    "Age": 11,
  }
```

이 요청 본문은 통합 엔드포인트에서 사용할 올바른 형식이 아니므로 API Gateway는 매핑 템플릿 변환을 수행합니다. API Gateway는 콘텐츠 유형 `application/json`에 대해 정의된 매핑 템플릿이 있으므로 매핑 템플릿 변환만 수행합니다. 콘텐츠 유형에 대한 매핑 템플릿을 정의하지 않으면 기본적으로 API Gateway는 통합 요청을 통해 본문을 통합 엔드포인트로 전달합니다. 이 동작을 수정하려면 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하시기 바랍니다.

다음 매핑 템플릿은 통합 엔드포인트로 전송되기 전에 통합 요청의 메서드 요청 데이터를 변환합니다.

```
#set($inputRoot = $input.path('$'))
  {
    "dogId" : "dog_"$elem.id,
    "Age": $inputRoot.Age
  }
```

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

1. `dog`는 사용자의 `id`와 문자열 값의 연결입니다.

1. `Age`는 메서드 요청 본문에서 가져온 것입니다.

그런 다음, 다음 출력이 통합 엔드포인트로 전달됩니다.

```
{
    "dogId" : "dog_1",
    "Age": 11
  }
```

## 통합 응답 및 메서드 응답
<a name="models-mappings-response"></a>

통합 엔드포인트에 대한 요청이 성공하면 엔드포인트는 API Gateway의 통합 응답에 응답을 보냅니다. 다음은 통합 엔드포인트의 예제 출력 데이터입니다.

```
{
    "dogId" : "dog_1",
    "adoptionFee": 19.95,
}
```

메서드 응답은 통합 응답에서 반환되는 것과 다른 페이로드를 예상합니다. API Gateway는 매핑 템플릿 변환을 수행합니다. API Gateway는 콘텐츠 유형 `application/json`에 대해 정의된 매핑 템플릿이 있으므로 매핑 템플릿 변환만 수행합니다. 콘텐츠 유형에 대한 매핑 템플릿을 정의하지 않으면 기본적으로 API Gateway는 메서드 응답을 통해 통합 응답으로 본문을 전달합니다. 이 동작을 수정하려면 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하시기 바랍니다.

```
#set($inputRoot = $input.path('$'))
  {
    "adoptionFee" : $inputRoot.adoptionFee,
  }
```

다음은 메서드 응답으로 전송된 출력입니다.

```
{"adoptionFee": 19.95}
```

그러면 예제 매핑 템플릿 변환이 완료됩니다. 가능하면 매핑 템플릿 변환을 사용하는 대신 프록시 통합을 사용하여 데이터를 변환하는 것이 좋습니다. 자세한 내용은 [API Gateway API 통합 유형 선택](api-gateway-api-integration-types.md) 섹션을 참조하세요.