メニュー
Amazon API Gateway
開発者ガイド

API Gateway でのバイナリペイロードのサポートの有効化

API Gateway では、API リクエストおよびレスポンスにテキストまたはバイナリペイロードを使用できます。テキストペイロードは UTF-8 でエンコードされた JSON 文字列です。バイナリペイロードはテキストペイロード以外のすべてです。バイナリペイロードの例には、JPEG ファイル、GZip ファイル、XML ファイルなどがあります。

デフォルトでは、API Gateway はメッセージ本文をテキストペイロードとして扱い、事前設定されたマッピングテンプレートを適用して JSON 文字列を変換します。マッピングテンプレートが指定されていない場合、パススルー動作が API メソッドで有効になっていれば、API Gateway は統合エンドポイントを通じて、または統合エンドポイントから、テキストペイロードを変更せずに渡すことができます。バイナリペイロードの場合、API Gateway はメッセージをそのまま渡します。

API Gateway がバイナリペイロードを渡すようにするには、メディアタイプを RestApi リソースの binaryMediaTypes リストに追加するか、Integration リソースと IntegrationResponse リソースで contentHandling プロパティを設定します。contentHandling 値は、CONVERT_TO_BINARYCONVERT_TO_TEXT、または未定義にすることができます。contentHandling 値の内容と、レスポンスの Content-Type ヘッダーと受信リクエストの Accept ヘッダーのどちらが binaryMediaTypes リストのエントリに一致するかどうかに応じて、API Gateway は raw バイナリバイトを Base64 でエンコードされた文字列としてエンコードする、Base64 でエンコードされた文字列をその raw バイトに戻す、または変更を加えずに本文を渡すことができます。

API Gateway で API のバイナリペイロードをサポートするには、次のように API を設定する必要があります。

  • RestApi リソースの binaryMediaTypes リストに必要なメディアタイプを追加します。このプロパティと contentHandling プロパティが定義されていない場合、ペイロードは UTF-8 でエンコードされた JSON 設定として処理されます。

  • Integration リソースの contentHandling プロパティを CONVERT_TO_BINARY に設定して、リクエストペイロードが Base64 でエンコードされた文字列からそのバイナリ BLOB に変換されるようにするか、プロパティを CONVERT_TO_TEXT に設定して、リクエストペイロードがバイナリ BLOB から Base64 でエンコードされた文字列に変換されるようにします。このプロパティが定義されていない場合、API Gateway は変更を加えずにペイロードを渡します。これは、Content-Type ヘッダー値が binaryMediaTypes エントリのいずれかに一致し、API の パススルー動作も有効になっている場合に発生します。

  • IntegrationResponse リソースの contentHandling プロパティを CONVERT_TO_BINARY に設定して、レスポンスペイロードが Base64 でエンコードされた文字列からそのバイナリ BLOB に変換されるようにするか、プロパティを CONVERT_TO_TEXT に設定して、リクエストペイロードがバイナリ BLOB から Base64 でエンコードされた文字列に変換されるようにします。contentHandling が定義されておらず、レスポンスの Content-Type ヘッダーと元のリクエストの Accept ヘッダーが binaryMediaTypes リストのエントリに一致する場合、API Gateway は本文をパススルーします。これは、Content-Type ヘッダーと Accept ヘッダーが同じ場合に発生します。それ以外の場合、API Gateway はレスポンス本文を Accept ヘッダーで指定されたタイプに変換します。