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

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

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

API Gateway が新しいバイナリメディアタイプをサポートするようにするには、RestApi リソースの binaryMediaTypes リストにバイナリメディアタイプを追加する必要があります。たとえば、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 として結果を受け入れる場合、IntegrationResponse リソースの contentHandling プロパティを 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. Integration リソースの contentHandling プロパティで CONVERT_TO_TEXT を設定し、バイナリデータの 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"
       }
     ]
   }