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

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

非プロキシ統合

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

注記

MOCK またはプライベート統合の場合、AWS Management Consoleでは contentHandling プロパティの設定はサポートされていません。contentHandling プロパティを設定するには、AWS CLI、AWS CloudFormation、または SDK を使用する必要があります。

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 でのコンテンツタイプの変換」を参照してください。