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

API Gateway REST API を使用したバイナリサポートの有効化

次のタスクは、API Gateway REST API コールを使用してバイナリサポートを有効にする方法を示します。

サポートされるバイナリメディアタイプの API への追加と更新

API Gateway が新しいバイナリメディアタイプをサポートするようにするには、RestApi リソースの binaryMediaTypes リストにバイナリメディアタイプを追加する必要があります。たとえば、API Gateway が JPEG イメージを処理するようにするには、PATCH リクエストを RestApi リソースに送信します。

Copy
PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/image~1jpeg" } ] }

path プロパティ値の一部となっている image/jpeg の MIME タイプの指定は、image~1jpeg としてエスケープされます。

サポートされるバイナリメディアタイプを更新するには、RestApi リソースの binaryMediaTypes リストにあるメディアタイプを置き換えるか、削除します。たとえば、バイナリサポートを JPEG ファイルから raw バイトに変更するには、次のように PATCH リクエストを RestApi リソースに送信します。

Copy
PATCH /restapis/<restapi_id> { "patchOperations" : [{ "op" : "replace", "path" : "/binaryMediaTypes/image~1jpeg", "value" : "application/octet-stream" }, { "op" : "remove", "path" : "/binaryMediaTypes/image~1jpeg" }] }

リクエストペイロード変換の設定

エンドポイントにバイナリ入力が必要な場合、Integration リソースの contentHandling プロパティを CONVERT_TO_BINARY に設定します。そのためには、次に示すように PATCH リクエストを送信します。

Copy
PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] }

レスポンスペイロード変換の設定

クライアントが、エンドポイントから返された Base64 でエンコードされたペイロードの代わりにバイナリ BLOB として結果を受け入れる場合、次に示すように PATCH リクエストを送信することで、IntegrationResponse リソースの contentHandling プロパティを CONVERT_TO_BINARY に設定します。

Copy
PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code> { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] }

バイナリデータのテキストデータへの変換

バイナリデータを、API Gateway を通じて AWS Lambda または Kinesis への入力の JSON プロパティとして送信するには、以下の操作を実行します。

  1. application/octet-stream の新しいバイナリメディアタイプを API の binaryMediaTypes リストに追加することで、API のバイナリペイロードサポートを有効にします。

    Copy
    PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] }
  2. Integration リソースの contentHandling プロパティで CONVERT_TO_TEXT を設定し、バイナリデータの Base64 でエンコードされた文字列を JSON プロパティに割り当てるマッピングテンプレートを提供します。次の例では、JSON プロパティが body であり、$input.body には Base64 でエンコードされた文字列が保持されています。

    Copy
    PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_TEXT" }, { "op" : "add", "path" : "/requestTemplates/application~1octet-stream", "value" : "{\"body\": \"$input.body\"}" } ] }

テキストデータのバイナリペイロードへの変換

Lambda 関数がイメージファイルを Base64 でエンコードされた文字列として返すとします。API Gateway を通じてこのバイナリ出力をクライアントに渡すには、以下の操作を実行します。

  1. application/octet-stream のバイナリメディアを追加することで API の binaryMediaTypes リストを更新します (まだリストにない場合)。

    Copy
    PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream", }] }
  2. Integration リソースの contentHandling プロパティを CONVERT_TO_BINARY に設定します。マッピングテンプレートを定義しないでください。マッピングテンプレートを定義しない場合、API Gateway はパススルーテンプレートを呼び出して、Base64 でデコードされたバイナリ BLOB をイメージファイルとしてクライアントに返します。

    Copy
    PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code> { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" } ] }

バイナリペイロードを渡す

API Gateway を使用して Amazon S3 バケットにイメージを保存するには、以下の操作を実行します。

  1. application/octet-stream のバイナリメディアを追加することで API の binaryMediaTypes リストを更新します (まだリストにない場合)。

    Copy
    PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] }
  2. Integration リソースの contentHandling プロパティで CONVERT_TO_BINARY を設定します。マッピングテンプレートを定義せずに、WHEN_NO_MATCHpassthroughBehavior プロパティとして設定します。これにより、API Gateway がパススルーテンプレートを呼び出すことができるようになります。

    Copy
    PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }, { "op" : "replace", "path" : "/passthroughBehaviors", "value" : "WHEN_NO_MATCH" } ] }