API Gateway でのコンテンツタイプの変換
API の binaryMediaTypes、クライアントリクエストのヘッダー、統合の contentHandling プロパティの組み合わせによって、API Gateway がペイロードをエンコードする方法が決まります。
次の表に、API Gateway がリクエストの Content-Type ヘッダーの特定の設定のリクエストペイロード、RestApi リソースの binaryMediaTypes リスト、Integration リソースの contentHandling プロパティ値を変換する方法を示します。
| メソッドリクエストペイロード | リクエスト Content-Type ヘッダー |
binaryMediaTypes |
contentHandling |
統合リクエストペイロード |
|---|---|---|---|---|
| テキストデータ | 任意のデータ型 | 未定義 | 未定義 | UTF8 でエンコードされた文字列 |
| テキストデータ | 任意のデータ型 | 未定義 | CONVERT_TO_BINARY |
Base64 でデコードされたバイナリ BLOB |
| テキストデータ | 任意のデータ型 | 未定義 | CONVERT_TO_TEXT |
UTF8 でエンコードされた文字列 |
| テキストデータ | テキストデータ型 | 一致するメディアタイプで設定 | 未定義 | テキストデータ |
| テキストデータ | テキストデータ型 | 一致するメディアタイプで設定 | CONVERT_TO_BINARY |
Base64 でデコードされたバイナリ BLOB |
| テキストデータ | テキストデータ型 | 一致するメディアタイプで設定 | CONVERT_TO_TEXT |
テキストデータ |
| バイナリデータ | バイナリデータ型 | 一致するメディアタイプで設定 | 未定義 | バイナリデータ |
| バイナリデータ | バイナリデータ型 | 一致するメディアタイプで設定 | CONVERT_TO_BINARY |
バイナリデータ |
| バイナリデータ | バイナリデータ型 | 一致するメディアタイプで設定 | CONVERT_TO_TEXT |
Base64 でエンコードされた文字列 |
次の表に、API Gateway がリクエストの Accept ヘッダーの特定の設定のレスポンスペイロード、RestApi リソースの binaryMediaTypes リスト、IntegrationResponse リソースの contentHandling プロパティ値を変換する方法を示します。
重要
リクエストの Accept ヘッダーに複数のメディアタイプが含まれている場合、API Gateway は最初の Accept メディアタイプのみ受け入れます。Accept メディアタイプの順序を制御できず、バイナリコンテンツのメディアタイプがリストの先頭にない場合は、API の binaryMediaTypes リストに最初の Accept メディアタイプを追加します。API Gateway は、このリスト内のすべてのコンテンツタイプをバイナリとして処理します。
たとえば、ブラウザで <img> 要素を使用して JPEG ファイルを送信するため、ブラウザがリクエストで Accept:image/webp,image/*,*/*;q=0.8 を送信することがあります。image/webp を binaryMediaTypes リストに追加することで、エンドポイントは JPEG ファイルをバイナリとして受け取ります。
| 統合レスポンスペイロード | リクエスト Accept ヘッダー |
binaryMediaTypes |
contentHandling |
メソッドレスポンスペイロード |
|---|---|---|---|---|
| テキストまたはバイナリデータ | テキスト型 | 未定義 | 未定義 | UTF8 でエンコードされた文字列 |
| テキストまたはバイナリデータ | テキスト型 | 未定義 | CONVERT_TO_BINARY |
Base64 でデコードされた BLOB |
| テキストまたはバイナリデータ | テキスト型 | 未定義 | CONVERT_TO_TEXT |
UTF8 でエンコードされた文字列 |
| テキストデータ | テキスト型 | 一致するメディアタイプで設定 | 未定義 | テキストデータ |
| テキストデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT_TO_BINARY |
Base64 でデコードされた BLOB |
| テキストデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT_TO_TEXT |
UTF8 でエンコードされた文字列 |
| テキストデータ | バイナリ型 | 一致するメディアタイプで設定 | 未定義 | Base64 でデコードされた BLOB |
| テキストデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT_TO_BINARY |
Base64 でデコードされた BLOB |
| テキストデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT_TO_TEXT |
UTF8 でエンコードされた文字列 |
| バイナリデータ | テキスト型 | 一致するメディアタイプで設定 | 未定義 | Base64 でエンコードされた文字列 |
| バイナリデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT_TO_BINARY |
バイナリデータ |
| バイナリデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT_TO_TEXT |
Base64 でエンコードされた文字列 |
| バイナリデータ | バイナリ型 | 一致するメディアタイプで設定 | 未定義 | バイナリデータ |
| バイナリデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT_TO_BINARY |
バイナリデータ |
| バイナリデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT_TO_TEXT |
Base64 でエンコードされた文字列 |
テキストペイロードをバイナリ BLOB に変換するとき、API Gateway はテキストデータが Base64 でエンコードされた文字列であるとみなし、バイナリデータを Base64 でデコードされた BLOB として出力します。変換に失敗した場合、API 設定エラーを示す 500 レスポンスを返します。そのような変換のマッピングテンプレートは提供しませんが、API でパススルー動作を有効にする必要があります。
バイナリペイロードをテキスト文字列に変換した場合、API Gateway は常にバイナリデータに Base64 エンコードを適用します。そのようなペイロードのマッピングテンプレートを定義できますが、サンプルマッピングテンプレートの次の抜粋に示すように、マッピングテンプレート内の Base64 でエンコードされた文字列には $input.body を通じてのみアクセスできます。
{ "data": "$input.body" }
バイナリペイロードが変更されずに渡されるようにするには、API でパススルー動作を有効にする必要があります。
