# API Gateway での REST API のバイナリメディアタイプ
<a name="api-gateway-payload-encodings"></a>

API Gateway では、API リクエストおよびレスポンスにテキストまたはバイナリペイロードがあります。テキストペイロードは `UTF-8` でエンコードされた JSON 文字列です。テキストペイロード以外のすべてはバイナリペイロードです。バイナリペイロードの例には、JPEG ファイル、GZip ファイル、XML ファイルなどがあります。バイナリメディアをサポートするために必要な API 設定は、API がプロキシ統合を使用するか非プロキシ統合を使用するかによって異なります。

ペイロードレスポンスのストリーミングに対応したプロキシ統合を使用する場合、バイナリメディアタイプを設定する必要はありません。詳細については、「[API Gateway でプロキシ統合の統合レスポンスをストリーミングする](response-transfer-mode.md)」を参照してください。

## AWS Lambda プロキシ統合
<a name="api-gateway-payload-encodings-proxy"></a>

AWS Lambda プロキシ統合のバイナリペイロードを処理するには、関数のレスポンスを base64 でエンコードする必要があります。また、API の [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) を設定する必要があります。API の `binaryMediaTypes` 設定は、API がバイナリデータとして扱うコンテンツタイプのリストです。バイナリメディアタイプの例には、`image/png` または `application/octet-stream` が含まれます。ワイルドカード文字 (`*`) を使用して、複数のメディアタイプを対象にすることができます。

API Gateway は、クライアントからの最初の `Accept` ヘッダーを使用して、レスポンスがバイナリメディアを返すかどうかを判断します。ブラウザからのリクエストなど、`Accept` ヘッダー値の順序を制御できない場合に、バイナリメディアを返すには、API のバイナリメディアタイプを `*/*` に設定します。

サンプルコードについては、「[API Gateway のLambda プロキシ統合からバイナリメディアを返す](lambda-proxy-binary-media.md)」を参照してください。

ペイロードレスポンスのストリーミングに対応した Lambda プロキシ統合を使用する場合、バイナリメディアタイプを設定する必要はありません。詳細については、「[API Gateway でペイロードレスポンスのストリーミングに対応した Lambda プロキシ統合を設定する](response-transfer-mode-lambda.md)」を参照してください。

## 非プロキシ統合
<a name="api-gateway-payload-encodings-non-proxy"></a>

非プロキシ統合のバイナリペイロードを処理するには、メディアタイプを `RestApi` リソースの [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) リストに追加します。API の `binaryMediaTypes` 設定は、API がバイナリデータとして扱うコンテンツタイプのリストです。[Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) リソースと [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) リソースに [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) プロパティを設定することもできます。`contentHandling` 値は、`CONVERT_TO_BINARY`、`CONVERT_TO_TEXT`、または未定義にすることができます。

**注記**  
`MOCK` またはプライベート統合の場合、AWS マネジメントコンソールでは `contentHandling` プロパティの設定はサポートされていません。`contentHandling` プロパティを設定するには、AWS CLI、CloudFormation、または SDK を使用する必要があります。

`contentHandling` 値の内容と、レスポンスの `Content-Type` ヘッダーと受信リクエストの `Accept` ヘッダーのどちらが `binaryMediaTypes` リストのエントリに一致するかどうかに応じて、API Gateway は raw バイナリバイトを base64 でエンコードされた文字列としてエンコードする、base64 でエンコードされた文字列をその raw バイトに戻す、または変更を加えずに本文を渡すことができます。

API Gateway で API のバイナリペイロードをサポートするには、次のように API を設定する必要があります。
+ [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースの `binaryMediaTypes` リストに必要なメディアタイプを追加します。このプロパティと `contentHandling` プロパティが定義されていない場合、ペイロードは UTF-8 でエンコードされた JSON 設定として処理されます。
+ [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) リソースの `contentHandling` プロパティを指定します。
  + リクエストペイロードを base64 でエンコードされた文字列からそのバイナリ BLOB に変換するには、プロパティを `CONVERT_TO_BINARY` に設定します。
  + リクエストペイロードをバイナリ BLOB から base64 でエンコードされた文字列に変換するには、プロパティを `CONVERT_TO_TEXT` に設定します。
  + ペイロードを変更せずにパススルーするには、プロパティを未定義のままにします。バイナリペイロードを変更せずにパススルーするには、`Content-Type` がいずれかの `binaryMediaTypes` エントリに一致し、API で[パススルー動作](integration-passthrough-behaviors.md)が有効になっていることも必要です。
+ [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) リソースの `contentHandling` プロパティを設定します。`contentHandling` プロパティ、クライアントリクエストの `Accept` ヘッダー、API の `binaryMediaTypes` の組み合わせによって、API Gateway がコンテンツタイプの変換を処理する方法が決まります。詳細については、「[API Gateway でのコンテンツタイプの変換](api-gateway-payload-encodings-workflow.md)」を参照してください。

**重要**  
リクエストの `Accept` ヘッダーに複数のメディアタイプが含まれている場合、API Gateway は最初の `Accept` メディアタイプのみ受け入れます。`Accept` メディアタイプの順序を制御できず、バイナリコンテンツのメディアタイプがリストの先頭にない場合は、API の `Accept` リストに最初の `binaryMediaTypes` メディアタイプを追加します。API Gateway は、このリスト内のすべてのコンテンツタイプをバイナリとして処理します。  
たとえば、ブラウザで `<img>` 要素を使用して JPEG ファイルを送信するため、ブラウザがリクエストで `Accept:image/webp,image/*,*/*;q=0.8` を送信することがあります。`image/webp` を `binaryMediaTypes` リストに追加することで、エンドポイントは JPEG ファイルをバイナリとして受け取ります。

API Gateway がテキストとバイナリペイロードを処理する方法の詳細については、「[API Gateway でのコンテンツタイプの変換](api-gateway-payload-encodings-workflow.md)」を参照してください。