API Gateway での REST API のバイナリメディアタイプ - Amazon API Gateway
AWS Lambda プロキシ統合非プロキシ統合

API Gateway での REST API のバイナリメディアタイプ

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

AWS Lambda プロキシ統合

AWS Lambda プロキシ統合のバイナリペイロードを処理するには、関数のレスポンスを base64 でエンコードする必要があります。また、API の binaryMediaTypes を設定する必要があります。API の binaryMediaTypes 設定は、API がバイナリデータとして扱うコンテンツタイプのリストです。バイナリメディアタイプの例には、image/png または application/octet-stream が含まれます。ワイルドカード文字 (*) を使用して、複数のメディアタイプを対象にすることができます。例えば、*/* にはすべてのコンテンツタイプが含まれます。

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

非プロキシ統合

非プロキシ統合のバイナリペイロードを処理するには、メディアタイプを RestApi リソースの binaryMediaTypes リストに追加します。API の binaryMediaTypes 設定は、API がバイナリデータとして扱うコンテンツタイプのリストです。Integration リソースと IntegrationResponse リソースに contentHandling プロパティを設定することもできます。contentHandling 値は、CONVERT_TO_BINARY、CONVERT_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 プロパティを指定します。

    • リクエストペイロードを base64 でエンコードされた文字列からそのバイナリ BLOB に変換するには、プロパティを CONVERT_TO_BINARY に設定します。

    • リクエストペイロードをバイナリ BLOB から base64 でエンコードされた文字列に変換するには、プロパティを CONVERT_TO_TEXT に設定します。

    • ペイロードを変更せずにパススルーするには、プロパティを未定義のままにします。バイナリペイロードを変更せずにパススルーするには、Content-Type がいずれかの binaryMediaTypes エントリに一致し、API でパススルー動作が有効になっていることも必要です。

  • IntegrationResponse リソースの contentHandling プロパティを設定します。contentHandling プロパティ、クライアントリクエストの Accept ヘッダー、API の binaryMediaTypes の組み合わせによって、API Gateway がコンテンツタイプの変換を処理する方法が決まります。詳細については、「API Gateway でのコンテンツタイプの変換」を参照してください。

重要

リクエストの Accept ヘッダーに複数のメディアタイプが含まれている場合、API Gateway は最初の Accept メディアタイプのみ受け入れます。Accept メディアタイプの順序を制御できず、バイナリコンテンツのメディアタイプがリストの先頭にない場合は、API の binaryMediaTypes リストに最初の Accept メディアタイプを追加します。API Gateway は、このリスト内のすべてのコンテンツタイプをバイナリとして処理します。

たとえば、ブラウザで <img> 要素を使用して JPEG ファイルを送信するため、ブラウザがリクエストで Accept:image/webp,image/*,*/*;q=0.8 を送信することがあります。image/webp を binaryMediaTypes リストに追加することで、エンドポイントは JPEG ファイルをバイナリとして受け取ります。

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