# API Gateway REST API를 사용하여 이진 지원 활성화
<a name="api-gateway-payload-encodings-configure-with-control-service-api"></a>

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

**Topics**
+ [지원되는 이진 미디어 지원을 API에 추가 및 업데이트](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [요청 페이로드 변환 구성](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [응답 페이로드 변환 구성](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [이진 데이터를 텍스트 데이터로 변환](#api-gateway-payload-encodings-convert-binary-to-string)
+ [텍스트 데이터를 이진 페이로드로 변환](#api-gateway-payload-encodings-convert-string-to-binary)
+ [이진 페이로드 패스스루](#api-gateway-payload-encodings-pass-binary-as-is)

## 지원되는 이진 미디어 지원을 API에 추가 및 업데이트
<a name="api-gateway-payload-encodings-setup-with-api-set-encodings-map"></a>

API Gateway에서 새로운 이진 미디어 유형을 지원하도록 활성화하려면 이진 미디어 유형을 `binaryMediaTypes` 리소스의 `RestApi` 목록에 추가해야 합니다. 예를 들어 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"
  }]
}
```

## 요청 페이로드 변환 구성
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding"></a>

엔드포인트에 이진 입력이 필요한 경우 `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"
  }]
}
```

## 응답 페이로드 변환 구성
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding"></a>

클라이언트에서 엔드포인트에서 반환되는 Base64로 인코딩된 페이로드가 아닌 이진 BLOB 형태의 결과를 수락하는 경우, `contentHandling` 리소스의 `IntegrationResponse` 속성을 `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"
  }]
}
```

## 이진 데이터를 텍스트 데이터로 변환
<a name="api-gateway-payload-encodings-convert-binary-to-string"></a>

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"
     } 
    ]
   }
   ```

1. `CONVERT_TO_TEXT` 리소스의 `contentHandling` 속성에서 `Integration`를 설정하고 매핑 템플릿을 제공하여 이진 데이터의 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\"}"
       }
     ]
   }
   ```

## 텍스트 데이터를 이진 페이로드로 변환
<a name="api-gateway-payload-encodings-convert-string-to-binary"></a>

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

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

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

1.  `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"
       }
     ]
   }
   ```

## 이진 페이로드 패스스루
<a name="api-gateway-payload-encodings-pass-binary-as-is"></a>

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

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

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

1. `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"
       }
     ]
   }
   ```