View a markdown version of this page

API Gateway REST API を使用したバイナリサポートの有効化 - Amazon API Gateway
サポートされるバイナリメディアタイプの API への追加と更新リクエストペイロード変換の設定レスポンスペイロード変換の設定バイナリデータをテキストデータに変換するテキストデータをバイナリペイロードに変換するバイナリペイロードを渡す

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

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

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

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

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/image~1jpeg"
  } 
 ]
}

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

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

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [{
    "op" : "replace",
    "path" : "/binaryMediaTypes/image~1jpeg",
    "value" : "application/octet-stream"
  },
  {
    "op" : "remove",
    "path" : "/binaryMediaTypes/image~1jpeg"
  }]
}

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

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

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/contentHandling",
    "value" : "CONVERT_TO_BINARY"
  }]
}

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

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

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 のバイナリペイロードサポートを有効にします。

    PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/application~1octet-stream"
  } 
 ]
}

  2. CONVERT_TO_TEXT リソースの contentHandling プロパティで Integration を設定し、バイナリデータの Base64 でエンコードされた文字列を JSON プロパティに割り当てるマッピングテンプレートを提供します。次の例では、JSON プロパティが body であり、$input.body には Base64 でエンコードされた文字列が保持されています。

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

    PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/application~1octet-stream",
  }]
}

  2. contentHandling リソースの Integration プロパティを CONVERT_TO_BINARY に設定します。マッピングテンプレートを定義しないでください。マッピングテンプレートを定義しない場合、API Gateway はパススルーテンプレートを呼び出して、Base64 でデコードされたバイナリ BLOB をイメージファイルとしてクライアントに返します。

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

    PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/application~1octet-stream"
  }
 ]
}

  2. contentHandling リソースの Integration プロパティで CONVERT_TO_BINARY を設定します。マッピングテンプレートを定義せずに、WHEN_NO_MATCH を passthroughBehavior プロパティとして設定します。これにより、API Gateway はパススルーテンプレートを呼び出すことができます。

    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"
    }
  ]
}