# API Gateway의 REST API에 대한 이진 미디어 유형
API Gateway에서 API 요청과 응답은 텍스트 또는 이진 페이로드를 포함합니다. 텍스트 페이로드는 `UTF-8` 인코딩 형식의 JSON 문자열입니다. 이진 페이로드는 텍스트 페이로드를 제외한 페이로드입니다. 예를 들어 JPEG 파일, GZip 파일, XML 파일 등이 이진 페이로드가 될 수 있습니다. 이진 미디어를 지원하는 데 필요한 API 구성은 API가 프록시 통합을 사용하는지 아니면 비 프록시 통합을 사용하는지에 따라 달라집니다.
프록시 통합을 페이로드 응답 스트리밍과 함께 사용하는 경우 바이너리 미디어 유형을 구성할 필요가 없습니다. 자세한 내용은 [API Gateway에서 프록시 통합에 대한 통합 응답 스트리밍](response-transfer-mode.md) 섹션을 참조하세요.
## AWS Lambda 프록시 통합
AWS Lambda 프록시 통합을 위한 이진 페이로드를 처리하려면 함수의 응답을 base64로 인코딩해야 합니다. 또한 API에 대한 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)를 구성해야 합니다. API의 `binaryMediaTypes` 구성은 API가 이진 데이터로 처리하는 콘텐츠 유형 목록입니다. 이진 미디어 유형의 예로는 `image/png` 또는 `application/octet-stream` 등이 있습니다. 와일드카드 문자(`*`)를 사용하여 여러 미디어 유형을 처리할 수 있습니다.
API Gateway는 클라이언트의 첫 번째 `Accept` 헤더를 사용하여 응답이 이진 미디어를 반환해야 하는지 결정합니다. 브라우저의 요청과 같이 `Accept` 헤더 값의 순서를 제어할 수 없을 때 이진 미디어를 반환하려면 API의 이진 미디어 유형을 `*/*`로 설정합니다.
예제 코드는 [API Gateway의 Lambda 프록시 통합에서 이진 미디어 반환](lambda-proxy-binary-media.md) 항목을 참조하세요.
Lambda 프록시 통합을 페이로드 응답 스트리밍과 함께 사용하는 경우 바이너리 미디어 유형을 구성할 필요가 없습니다. 자세한 내용은 [API Gateway에서 페이로드 응답 스트리밍과 Lambda 프록시 통합 설정](response-transfer-mode-lambda.md) 섹션을 참조하세요.
## 비 프록시 통합
비 프록시 통합을 위한 이진 페이로드를 처리하려면 `RestApi` 리소스의 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) 목록에 미디어 유형을 추가합니다. API의 `binaryMediaTypes` 구성은 API가 이진 데이터로 처리하는 콘텐츠 유형 목록입니다. 또는 [통합(Integration)](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 및 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스에서 [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) 속성을 설정할 수 있습니다. `contentHandling` 값은 `CONVERT_TO_BINARY` 또는 `CONVERT_TO_TEXT`이거나 정의되지 않을 수 있습니다.
**참고**
`MOCK` 또는 프라이빗 통합의 경우 `contentHandling` 속성 설정은 AWS Management Console에서 지원되지 않습니다. `contentHandling` 속성을 설정하려면 AWS CLI, CloudFormation 또는 SDK를 사용해야 합니다.
`contentHandling` 값과 응답의 `Content-Type` 헤더 또는 수신 요청의 `Accept` 헤더가 `binaryMediaTypes` 목록의 항목과 일치하는지 여부에 따라 API Gateway에서 원시 이진 유형을 base64로 인코딩된 문자열로 인코딩하거나, base64로 인코딩된 문자열을 원시 바이트로 다시 디코딩하거나, 본문을 수정하지 않고 전달할 수 있습니다.
API Gateway에서 API에 대해 이진 페이로드를 지원하려면 API를 다음과 같이 구성해야 합니다.
+ [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스의 `binaryMediaTypes` 목록에 원하는 이진 미디어 형식을 추가합니다. 이 속성과 `contentHandling` 속성을 정의하지 않은 경우 페이로드는 UTF-8로 인코딩된 JSON 문자열로 처리됩니다.
+ [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스의 `contentHandling` 속성을 설정합니다.
+ 요청 페이로드를 base64로 인코딩된 문자열에서 이진 Blob로 변환하려면 속성을 `CONVERT_TO_BINARY`로 설정합니다.
+ 요청 페이로드를 이진 Blob에서 base64로 인코딩된 문자열로 변환하려면 속성을 `CONVERT_TO_TEXT`로 설정합니다.
+ 페이로드를 수정하지 않고 전달하려면 속성을 정의되지 않은 상태로 둡니다. 이진 페이로드를 수정하지 않고 전달하려면 `Content-Type`이 `binaryMediaTypes` 항목 중 하나와 일치하고 API에 대해 [패스스루 동작](integration-passthrough-behaviors.md)이 활성화되어 있어야 합니다.
+ [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스의 `contentHandling` 속성을 설정합니다. `contentHandling` 속성, 클라이언트 요청의 `Accept` 헤더 및 API `binaryMediaTypes`의 조합에 따라 API Gateway에서 콘텐츠 유형 변환을 처리하는 방법이 결정됩니다. 자세한 내용은 [API Gateway의 콘텐츠 유형 변환](api-gateway-payload-encodings-workflow.md) 단원을 참조하세요.
**중요**
요청의 `Accept` 헤더에 여러 미디어 유형이 포함되어 있는 경우 API Gateway에서는 첫 번째 `Accept` 미디어 유형만 인식합니다. `Accept` 미디어 유형의 순서를 제어할 수 없고 이진 콘텐츠의 미디어 유형이 목록의 맨 앞에 있지 않은 경우, API의 `Accept` 목록에서 첫 번째 `binaryMediaTypes` 미디어 유형을 추가합니다. API Gateway는 이 목록의 모든 콘텐츠 유형을 이진수로 처리합니다.
예를 들어 브라우저에서 `![]()
` 요소를 사용하여 JPEG 파일을 보내려는 경우 브라우저에서 요청에 `Accept:image/webp,image/*,*/*;q=0.8`을 전송할 수 있습니다. `image/webp`를 `binaryMediaTypes` 목록에 추가하여 엔드포인트에서 JPEG 파일을 이진 유형으로 수신합니다.
API Gateway에서 텍스트 및 이진 페이로드를 처리하는 방법에 대한 자세한 내용은 [API Gateway의 콘텐츠 유형 변환](api-gateway-payload-encodings-workflow.md) 단원을 참조하세요.