API Gateway의 REST API에 대한 이진 미디어 유형 - Amazon API Gateway

API Gateway의 REST API에 대한 이진 미디어 유형

API Gateway에서 API 요청과 응답은 텍스트 또는 이진 페이로드를 포함합니다. 텍스트 페이로드는 UTF-8 인코딩 형식의 JSON 문자열입니다. 이진 페이로드는 텍스트 페이로드를 제외한 페이로드입니다. 예를 들어 JPEG 파일, GZip 파일, XML 파일 등이 이진 페이로드가 될 수 있습니다. 이진 미디어를 지원하는 데 필요한 API 구성은 API가 프록시 통합을 사용하는지 아니면 비 프록시 통합을 사용하는지에 따라 달라집니다.

AWS Lambda 프록시 통합

AWS Lambda 프록시 통합을 위한 이진 페이로드를 처리하려면 함수의 응답을 base64로 인코딩해야 합니다. 또한 API에 대한 binaryMediaTypes를 구성해야 합니다. API의 binaryMediaTypes 구성은 API가 이진 데이터로 처리하는 콘텐츠 유형 목록입니다. 이진 미디어 유형의 예로는 image/png 또는 application/octet-stream 등이 있습니다. 와일드카드 문자(*)를 사용하여 여러 미디어 유형을 처리할 수 있습니다. 예를 들어 */*에는 모든 콘텐츠 유형이 포함됩니다.

예제 코드는 API Gateway의 Lambda 프록시 통합에서 이진 미디어 반환 항목을 참조하세요.

비 프록시 통합

비 프록시 통합을 위한 이진 페이로드를 처리하려면 RestApi 리소스의 binaryMediaTypes 목록에 미디어 유형을 추가합니다. API의 binaryMediaTypes 구성은 API가 이진 데이터로 처리하는 콘텐츠 유형 목록입니다. 또는 통합(Integration)IntegrationResponse 리소스에서 contentHandling 속성을 설정할 수 있습니다. contentHandling 값은 CONVERT_TO_BINARY 또는 CONVERT_TO_TEXT이거나 정의되지 않을 수 있습니다.

contentHandling 값과 응답의 Content-Type 헤더 또는 수신 요청의 Accept 헤더가 binaryMediaTypes 목록의 항목과 일치하는지 여부에 따라 API Gateway에서 원시 이진 유형을 base64로 인코딩된 문자열로 인코딩하거나, base64로 인코딩된 문자열을 원시 바이트로 다시 디코딩하거나, 본문을 수정하지 않고 전달할 수 있습니다.

API Gateway에서 API에 대해 이진 페이로드를 지원하려면 API를 다음과 같이 구성해야 합니다.

  • RestApi 리소스의 binaryMediaTypes 목록에 원하는 이진 미디어 형식을 추가합니다. 이 속성과 contentHandling 속성을 정의하지 않은 경우 페이로드는 UTF-8로 인코딩된 JSON 문자열로 처리됩니다.

  • Integration 리소스의 contentHandling 속성을 설정합니다.

    • 요청 페이로드를 base64로 인코딩된 문자열에서 이진 Blob로 변환하려면 속성을 CONVERT_TO_BINARY로 설정합니다.

    • 요청 페이로드를 이진 Blob에서 base64로 인코딩된 문자열로 변환하려면 속성을 CONVERT_TO_TEXT로 설정합니다.

    • 페이로드를 수정하지 않고 전달하려면 속성을 정의되지 않은 상태로 둡니다. 이진 페이로드를 수정하지 않고 전달하려면 Content-TypebinaryMediaTypes 항목 중 하나와 일치하고 API에 대해 패스스루 동작이 활성화되어 있어야 합니다.

  • IntegrationResponse 리소스의 contentHandling 속성을 설정합니다. contentHandling 속성, 클라이언트 요청의 Accept 헤더 및 API binaryMediaTypes의 조합에 따라 API Gateway에서 콘텐츠 유형 변환을 처리하는 방법이 결정됩니다. 자세한 내용은 API Gateway의 콘텐츠 유형 변환 단원을 참조하세요.

중요

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

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

API Gateway에서 텍스트 및 이진 페이로드를 처리하는 방법에 대한 자세한 내용은 API Gateway의 콘텐츠 유형 변환 단원을 참조하세요.