Amazon API Gateway (REST) の HTTP 統合で、統合先にクエリ文字列を転送するために必要な設定を確認してみた

いわさです。

Amazon API Gateway (REST) では様々な統合先を選択することが出来ますが、HTTP 統合機能を使うと簡単にプロキシ API を作成することが出来ます。

その際、多くの場合は次のように統合先の API 仕様に基づいてクエリ文字列も転送したいですよね。

API Gateway で HTTP 統合をするオプションはいくつかあって、その方法によってはクエリ文字列を勝手に転送してくれたり、意識してマッピングしないといけなかったりします。
この記事では HTTP 統合のいくつかの方法ごとにクエリ文字列を転送する方法を整理したので紹介します。

統合先バックエンドを用意

今回は統合先バックエンドも API Gateway のモック機能で用意します。冒頭の構成図でいう「HTTP Service」です。
次のようにリソースとメソッドを用意しました。

また、メソッドリクエストでは必須のクエリ文字列パラメータを定義し、リクエスト検証で必須チェックが有効になるようにします。

この API をステージにデプロイしリクエストしてみると次のようにクエリ文字列が設定されているかどうかで挙動が変わります。

クエリ文字列なし

エラーメッセージ「Missing required request parameters」が返ってきました。

% curl https://by84lo2sgk.execute-api.ap-northeast-1.amazonaws.com/stage/hoge
{"message": "Missing required request parameters: [aaa, bbb]"}
% curl https://by84lo2sgk.execute-api.ap-northeast-1.amazonaws.com/stage/fuga
{"message": "Missing required request parameters: [ccc]"}

クエリ文字列あり

必須のクエリ文字列を指定した場合はモックの統合レスポンスで指定した静的なレスポンスが返却されています。

% curl "https://by84lo2sgk.execute-api.ap-northeast-1.amazonaws.com/stage/hoge?aaa=111&bbb=222"
hoge result
% curl "https://by84lo2sgk.execute-api.ap-northeast-1.amazonaws.com/stage/fuga?ccc=111&ddd=222"
fuga result

プロキシ API を作成

ではここから前段のプロキシ用 API Gateway を作成します。
この記事では HTTP プロキシ統合と、プロキシリソース、そして HTTP 非プロキシ統合の 3 つを対象にしたいと思います。

HTTP プロキシ統合を使う場合

まずは次のように統合リクエストで先程 API Gateway で用意した統合先 API のエンドポイント URL をリソースパス込みでリソースごとに指定しつつ、「HTTP プロキシ統合の使用」を ON にします。

デプロイ後にリクエストを送信してみると次のようにエラーが発生せずに正常レスポンスが取得出来ています。

% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/hoge?aaa=111&bbb=222"
hoge result
% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/hoge?aaa=111&bbb=222&ccc=333"
hoge result

また、バックエンド側のアクセスログなどを確認してみると、次のようにクエリ文字列が転送されていることが確認出来ます。

(9a98d489-5a32-444f-8529-1012e80d9360) Method request query string: {aaa=111, bbb=222, ccc=333}

この HTTP プロキシ統合はその名のとおり統合先の HTTP エンドポイントへのプロキシを担うためにマッピングテンプレートなどを自動設定してくれるものなので、単純にプロキシするために使うのであればシンプルに設定することが可能です。

ただし HTTP プロキシ統合はマッピングテンプレートなどを自動設定してくれるので、次のように統合レスポンスの設定などを行うことは出来ません。
統合先からのレスポンスをプロキシ API がそのまま使える場合はこちらが使えると思います。

プロキシリソースを使う場合

次は先程のものとは少し比較対象が異なるのですが、プロキシリソースを使った際の挙動も確認しておきます。
先程の方法だとリソースやメソッドごとに統合設定が必要になるのですが、特定パス以下をパスパラメータやクエリ文字列を含めて全部パススルーしたいみたいな状況だとプロキシリソースを使うのが楽です。

次のようにリソース作成時にプロキシリソースとして作成し、統合タイプに HTTP プロキシを、エンドポイント URL へ統合エンドポイントにプロキシリソースのプレースホルダを埋め込んだ形で指定します。

そうすると次のように fuga リソースにアクセスした場合は統合先の fuga リソースへ、hoge リソースにアクセスした場合は統合先の hoge リソースへリクエストがプロキシされます。

% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/hoge"                        
{"message": "Missing required request parameters: [aaa, bbb]"}
% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/hoge?aaa=111&bbb=222"
hoge result
% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/fuga"                
{"message": "Missing required request parameters: [ccc]"}
% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/fuga?ccc=333"
fuga result

特に前段の API Gateway で入力検証は行っていないので上記の検証は全て統合先で行われています。
クエリ文字列が指定された場合は正常なレスポンスが取得され、必須のクエリ文字列が指定されなかった場合は統合先から検証エラーレスポンスが取得されています。

リソースもマッピングも何も指定しなくて良いので、特定のパス以下を全部統合先にプロキシしたいみたいな時にはこの機能が一番楽です。
特定パス以下をプロキシするが一部リソースのみプロキシしたいみたいな場合は先程の方法を、特定パス以下は全部プロキシする場合はこちらの方法が良いと思います。

マッピングの実態としては、先程と同様に HTTP_PROXY タイプで構成されています。
そのため統合レスポンスのカスタマイズは当然出来ないです。

HTTP プロキシ統合を使わない場合

最後が プロキシ統合を使わずに通常の HTTP 統合を使う場合です。
この場合は面倒ですがクエリ文字列の設定が個別に必要です。

コンテンツについてはパススルーされるのですが、各パラメータはパススルーされないので個別にマッピングが必要です。
上記では aaa と bbb のクエリ文字列パラメータをマッピングさせています。

こちらを構成しない場合は次のように前段の API に送信されたパラメータは捨てられて、統合リクエストに設定されている内容のみで統合先にリクエストが送信されます。

以下はクエリ文字列のパラメータマッピングを設定しなかった場合です。
必須のクエリ文字列を指定してもパラメータ不足でエラーレスポンスが返ってきますね。

% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/hoge"
{"message": "Missing required request parameters: [aaa, bbb]"}
% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/hoge?aaa=111&bbb=222"
{"message": "Missing required request parameters: [aaa, bbb]"}

一方で、パラメータマッピングをしてやると次のように正常なレスポンスを取得出来ました。

% curl "https://cdgjponr79.execute-api.ap-northeast-1.amazonaws.com/piyo/hoge?aaa=111&bbb=222"
hoge result

単純なプロキシするだけの API として考えるならば HTTP プロキシ統合を使うほうが楽だと思います。
しかし、この機能を使うと次のように統合レスポンスのカスタマイズが出来るようになります。

次のように統合先のリクエスト内容やレスポンス内容を API Gateway で少し加工したいとか、そういった場合に使うことが出来ます。

自動でマッピング設定はしてくれないのでパラメータの扱いが面倒にはなりますが、よりカスタマイズしたい場合はこちらを選択することになると思います。
勝手にパラメータは転送されないのでマッピング忘れないようにしましょう。

さいごに

本日は Amazon API Gateway (REST) の HTTP 統合で、統合先にクエリ文字列を転送するために必要な設定を確認してみました。

プロキシリソースやプロキシ統合を使う場合は自動でパラメータ転送してくれます。
一方で非プロキシ統合で独自にマッピングを管理する場合はリクエストで受け取ったパラメータは勝手に使われることはないので、マッピングのし忘れに注意しましょう。