API Gateway의 콘텐츠 유형 변환

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

다음 표는 API Gateway에서 요청 Content-Type 헤더의 특정 구성, RestApi 리소스의 binaryMediaTypes 목록, 통합(Integration) 리소스의 contentHandling 속성 값에 대한 요청 페이로드를 변환하는 방법을 보여줍니다.

API Gateway의 API 요청 콘텐츠 유형 변환
메서드 요청 페이로드	요청 Content-Type 헤더	binaryMediaTypes	contentHandling	통합 요청 페이로드
텍스트 데이터	모든 데이터 형식	정의되지 않음	정의되지 않음	UTF8로 인코딩된 문자열
텍스트 데이터	모든 데이터 형식	정의되지 않음	CONVERT_TO_BINARY	Base64로 디코딩된 이진 BLOB
텍스트 데이터	모든 데이터 형식	정의되지 않음	CONVERT_TO_TEXT	UTF8로 인코딩된 문자열
텍스트 데이터	텍스트 데이터 형식	일치하는 미디어 유형이 있는 세트	정의되지 않음	텍스트 데이터
텍스트 데이터	텍스트 데이터 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_BINARY	Base64로 디코딩된 이진 BLOB
텍스트 데이터	텍스트 데이터 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_TEXT	텍스트 데이터
이진 데이터	이진 데이터 형식	일치하는 미디어 유형이 있는 세트	정의되지 않음	이진 데이터
이진 데이터	이진 데이터 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_BINARY	이진 데이터
이진 데이터	이진 데이터 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_TEXT	Base64로 인코딩된 문자열

다음 표는 API Gateway에서 요청 Accept 헤더의 특정 구성, RestApi 리소스의 binaryMediaTypes 목록, IntegrationResponse 리소스의 contentHandling 속성 값에 대한 응답 페이로드를 변환하는 방법을 보여줍니다.

중요

요청의 Accept 헤더에 여러 미디어 유형이 포함되어 있는 경우 API Gateway에서는 첫 번째 Accept 미디어 유형만 인식합니다. Accept 미디어 유형의 순서를 제어할 수 없고 이진 콘텐츠의 미디어 유형이 목록의 맨 앞에 있지 않은 경우, API의 binaryMediaTypes 목록에서 첫 번째 Accept 미디어 유형을 추가합니다. API Gateway는 이 목록의 모든 콘텐츠 유형을 이진수로 처리합니다.

예를 들어 브라우저에서 <img> 요소를 사용하여 JPEG 파일을 보내려는 경우 브라우저에서 요청에 Accept:image/webp,image/*,*/*;q=0.8을 전송할 수 있습니다. image/webp를 binaryMediaTypes 목록에 추가하여 엔드포인트에서 JPEG 파일을 이진 유형으로 수신합니다.

API Gateway 응답 콘텐츠 유형 변환
통합 응답 페이로드	요청 Accept 헤더	binaryMediaTypes	contentHandling	메서드 응답 페이로드
텍스트 또는 이진 데이터	텍스트 유형	정의되지 않음	정의되지 않음	UTF8로 인코딩된 문자열
텍스트 또는 이진 데이터	텍스트 유형	정의되지 않음	CONVERT_TO_BINARY	Base64로 디코딩된 BLOB
텍스트 또는 이진 데이터	텍스트 유형	정의되지 않음	CONVERT_TO_TEXT	UTF8로 인코딩된 문자열
텍스트 데이터	텍스트 유형	일치하는 미디어 유형이 있는 세트	정의되지 않음	텍스트 데이터
텍스트 데이터	텍스트 유형	일치하는 미디어 유형이 있는 세트	CONVERT_TO_BINARY	Base64로 디코딩된 BLOB
텍스트 데이터	텍스트 유형	일치하는 미디어 유형이 있는 세트	CONVERT_TO_TEXT	UTF8로 인코딩된 문자열
텍스트 데이터	이진수 형식	일치하는 미디어 유형이 있는 세트	정의되지 않음	Base64로 디코딩된 BLOB
텍스트 데이터	이진수 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_BINARY	Base64로 디코딩된 BLOB
텍스트 데이터	이진수 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_TEXT	UTF8로 인코딩된 문자열
이진 데이터	텍스트 유형	일치하는 미디어 유형이 있는 세트	정의되지 않음	Base64로 인코딩된 문자열
이진 데이터	텍스트 유형	일치하는 미디어 유형이 있는 세트	CONVERT_TO_BINARY	이진 데이터
이진 데이터	텍스트 유형	일치하는 미디어 유형이 있는 세트	CONVERT_TO_TEXT	Base64로 인코딩된 문자열
이진 데이터	이진수 형식	일치하는 미디어 유형이 있는 세트	정의되지 않음	이진 데이터
이진 데이터	이진수 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_BINARY	이진 데이터
이진 데이터	이진수 형식	일치하는 미디어 유형이 있는 세트	CONVERT_TO_TEXT	Base64로 인코딩된 문자열

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

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

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

이진 페이로드를 수정하지 않고 전달하려면 API에서 패스스루 동작을 활성화해야 합니다.