# 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 ファイルから raw バイトに変更するには、次のように `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"
       }
     ]
   }
   ```