API Gateway REST API를 사용하여 이진 지원 활성화

다음 작업에서는 API Gateway REST API 호출을 사용하여 이진 지원을 활성화하는 방법을 보여 줍니다.

지원되는 이진 미디어 지원을 API에 추가 및 업데이트

API Gateway에서 새로운 이진 미디어 유형을 지원하도록 활성화하려면 이진 미디어 유형을 RestApi 리소스의 binaryMediaTypes 목록에 추가해야 합니다. 예를 들어 API Gateway에서 JPEG 이미지를 처리하도록 하려면 PATCH 요청을 RestApi 리소스에 제출합니다.

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/image~1jpeg"
  } 
 ]
}

image/jpeg 속성 값의 일부인 path의 MIME 유형 사양은 image~1jpeg로 이스케이프됩니다.

지원되는 이진 미디어 유형을 업데이트하려면 binaryMediaTypes 리소스의 RestApi 목록에서 미디어 유형을 교체하거나 제거합니다. 예를 들어 이진 지원을 JPEG 파일에서 원시 바이트로 변경하려면 다음과 같이 PATCH 요청을 RestApi 리소스에 제출합니다.

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [{
    "op" : "replace",
    "path" : "/binaryMediaTypes/image~1jpeg",
    "value" : "application/octet-stream"
  },
  {
    "op" : "remove",
    "path" : "/binaryMediaTypes/image~1jpeg"
  }]
}

요청 페이로드 변환 구성

엔드포인트에 이진 입력이 필요한 경우 contentHandling 리소스의 Integration 속성을 CONVERT_TO_BINARY로 설정합니다. 이렇게 하려면 다음과 같이 PATCH 요청을 제출합니다.

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/contentHandling",
    "value" : "CONVERT_TO_BINARY"
  }]
}

응답 페이로드 변환 구성

클라이언트에서 엔드포인트에서 반환되는 Base64로 인코딩된 페이로드가 아닌 이진 BLOB 형태의 결과를 수락하는 경우, IntegrationResponse 리소스의 contentHandling 속성을 CONVERT_TO_BINARY로 설정합니다. 이렇게 하려면 다음과 같이 PATCH 요청을 제출합니다.

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code>

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/contentHandling",
    "value" : "CONVERT_TO_BINARY"
  }]
}

이진 데이터를 텍스트 데이터로 변환

API Gateway를 통해 이진 데이터를 AWS Lambda 또는 Kinesis에 대한 입력의 JSON 속성으로 전송하려면 다음을 수행합니다.

1. application/octet-stream의 새 이진 미디어 유형을 API의 binaryMediaTypes 목록에 추가하여 API의 이진 페이로드 지원을 활성화합니다.

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream"
     } 
    ]
   }
   

2. Integration 리소스의 contentHandling 속성에서 CONVERT_TO_TEXT를 설정하고 매핑 템플릿을 제공하여 이진 데이터의 Base64로 인코딩된 문자열을 JSON 속성에 할당합니다. 다음 예제에서 JSON 속성은 body이고 $input.body는 Base64로 인코딩된 문자열을 보유합니다.

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_TEXT"
       },
       {
         "op" : "add",
         "path" : "/requestTemplates/application~1octet-stream",
         "value" : "{\"body\": \"$input.body\"}"
       }
     ]
   }

텍스트 데이터를 이진 페이로드로 변환

Lambda 함수가 이미지 파일을 Base64로 인코딩된 문자열로 반환한다고 가정합니다. API Gateway를 통해 이 이진 출력을 클라이언트에 전달하려면 다음을 수행합니다.

1. binaryMediaTypes의 이진 미디어 유형을 추가하여(목록에 아직 없는 경우) API의 application/octet-stream 목록을 업데이트합니다.

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream",
     }]
   }
   

2. contentHandling 리소스의 Integration 속성을 CONVERT_TO_BINARY로 설정합니다. 매핑 템플릿을 정의하지 마세요. 매핑 템플릿을 정의하지 않을 경우, API Gateway에서 패스스루 템플릿을 호출하여 Base64로 디코딩된 이진 BLOB을 클라이언트에 이미지 파일로 반환합니다.

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code>
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_BINARY"
       }
     ]
   }

이진 페이로드 패스스루

API Gateway를 사용하여 Amazon S3 버킷에 이미지를 저장하려면 다음을 수행합니다.

1. binaryMediaTypes의 이진 미디어 유형을 추가하여(목록에 아직 없는 경우) API의 application/octet-stream 목록을 업데이트합니다.

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream"
     }
    ]
   }
   

2. contentHandling 리소스의 Integration 속성을 CONVERT_TO_BINARY로 설정합니다. 매핑 템플릿을 정의하지 않고 WHEN_NO_MATCH를 passthroughBehavior 속성 값으로 설정합니다. 그러면 API Gateway에서 패스스루 템플릿을 호출할 수 있습니다.

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_BINARY"
       },
       {
         "op" : "replace",
         "path" : "/passthroughBehaviors",
         "value" : "WHEN_NO_MATCH"
       }
     ]
   }