API Gateway でのコンテンツタイプの変換 - Amazon API Gateway

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 でパススルー動作を有効にする必要があります。