# API Gateway의 콘텐츠 유형 변환
<a name="api-gateway-payload-encodings-workflow"></a>

 API `binaryMediaTypes`, 클라이언트 요청의 헤더 및 통합 `contentHandling` 속성의 조합에 따라 API Gateway에서 페이로드를 인코딩하는 방법이 결정됩니다.

다음 표는 API Gateway가 요청 `Content-Type` 헤더의 특정 구성, [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스의 `binaryMediaTypes` 목록 및 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스의 `contentHandling` 속성 값에 대한 요청 페이로드를 어떻게 변환하는지 보여 줍니다.


| 메서드 요청 페이로드 | 요청 `Content-Type` 헤더 | `binaryMediaTypes` | `contentHandling` | 통합 요청 페이로드 | 
| --- | --- | --- | --- | --- | 
| 텍스트 데이터 | 모든 데이터 형식 | 정의되지 않음 | 정의되지 않음 | UTF8로 인코딩된 문자열 | 
| 텍스트 데이터 | 모든 데이터 형식 | 정의되지 않음 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 이진 BLOB | 
| 텍스트 데이터 | 모든 데이터 형식 | 정의되지 않음 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 | 
| 텍스트 데이터 | 텍스트 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 텍스트 데이터 | 
| 텍스트 데이터 | 텍스트 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 이진 BLOB | 
| 텍스트 데이터 | 텍스트 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | 텍스트 데이터 | 
| 이진 데이터 | 이진 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 이진 데이터 | 
| 이진 데이터 | 이진 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | 이진 데이터 | 
| 이진 데이터 | 이진 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | Base64로 인코딩된 문자열 | 

다음 표는 API Gateway가 요청 `Accept` 헤더의 특정 구성, [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스의 `binaryMediaTypes` 목록 및 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스의 `contentHandling` 속성 값에 대한 응답 페이로드를 어떻게 변환하는지 보여 줍니다.

**중요**  
 요청의 `Accept` 헤더에 여러 미디어 유형이 포함되어 있는 경우 API Gateway에서는 첫 번째 `Accept` 미디어 유형만 인식합니다. `Accept` 미디어 유형의 순서를 제어할 수 없고 이진 콘텐츠의 미디어 유형이 목록의 맨 앞에 있지 않은 경우, API의 `Accept` 목록에서 첫 번째 `binaryMediaTypes` 미디어 유형을 추가합니다. API Gateway는 이 목록의 모든 콘텐츠 유형을 이진수로 처리합니다.  
예를 들어 브라우저에서 `<img>` 요소를 사용하여 JPEG 파일을 보내려는 경우 브라우저에서 요청에 `Accept:image/webp,image/*,*/*;q=0.8`을 전송할 수 있습니다. `image/webp`를 `binaryMediaTypes` 목록에 추가하여 엔드포인트에서 JPEG 파일을 이진 유형으로 수신합니다.


| 통합 응답 페이로드 | 요청 `Accept` 헤더 | `binaryMediaTypes` | `contentHandling` | 메서드 응답 페이로드 | 
| --- | --- | --- | --- | --- | 
| 텍스트 또는 이진 데이터 | 텍스트 유형 | 정의되지 않음 | 정의되지 않음 | UTF8로 인코딩된 문자열 | 
| 텍스트 또는 이진 데이터 | 텍스트 유형 | 정의되지 않음 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 BLOB | 
| 텍스트 또는 이진 데이터 | 텍스트 유형 | 정의되지 않음 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 | 
| 텍스트 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 텍스트 데이터 | 
| 텍스트 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 BLOB | 
| 텍스트 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 | 
| 텍스트 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | Base64로 디코딩된 BLOB | 
| 텍스트 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 BLOB | 
| 텍스트 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 | 
| 이진 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | Base64로 인코딩된 문자열 | 
| 이진 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | 이진 데이터 | 
| 이진 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | Base64로 인코딩된 문자열 | 
| 이진 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 이진 데이터 | 
| 이진 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | 이진 데이터 | 
| 이진 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | Base64로 인코딩된 문자열 | 

텍스트 페이로드를 이진 BLOB으로 변환할 때 API Gateway에서는 텍스트 데이터가 Base64로 인코딩된 문자열인 것으로 간주하고 이진 데이터를 Base64로 디코딩된 BLOB으로 출력합니다. 변환에 실패하면 API 구성 오류를 나타내는 `500` 응답이 반환됩니다. API에 대해 [패스스루 동작](integration-passthrough-behaviors.md)을 활성화해야 하되, 이러한 변환에 대해 매핑 템플릿을 제공하지 않습니다.

이진 페이로드를 텍스트 문자열로 변환할 경우 API Gateway에서는 항상 이진 데이터에 Base64 인코딩을 적용합니다. 다음과 같은 예제 매핑 템플릿에 표시된 것처럼 이러한 페이로드에 대해 매핑 템플릿을 정의할 수 있지만, `$input.body`를 통해서만 매핑 템플릿의 Base64로 인코딩된 문자열에 액세스할 수 있습니다.

```
{   
    "data": "$input.body"
}
```

이진 페이로드를 수정하지 않고 전달하려면 API에서 [패스스루 동작](integration-passthrough-behaviors.md)을 활성화해야 합니다.