💭

AWS APIGWのプロキシ統合とマッピングについて

2024/07/14に公開

AWS

はじめに

AWSのAPIGWを使うときに、ヘッダー名の書き換えをしたい要件があり、関連設定の仕様について調査した

結論

プロキシ統合：APIGWが受け付けたリクエスト(レスポンス)を、そのままバックエンド(クライアント)に転送する機能。ユーザでのカスタマイズが不要であれば、利用を推奨したい。
非プロキシ統合：リクエスト(レスポンス)を1つ1つマッピングする必要がある。柔軟性がある一方で、抜け漏れのないマッピング作業が必要になってしまう。

実機での設定内容の概要

alt text

統合リクエスト
- プロキシ統合をOFFにする。
- URLパスパラメータ/クエリ文字列パラメータ/リクエストヘッダーのパラメータ/マッピングテンプレート　を設定する。
  例えば、クエリ文字列パラメータの場合には、名前にバックエンドに転送するパラメータ名を、マッピング元にクライアントからのリクエストのパラメータ名を設定する。クエリ文字列の場合には、method.request.querystring.<PRAMNAME>が設定される。
メソッドリクエスト
- マッピング元となるリクエストの種別を設定する。本来順番的には、統合プロキシをOFFにしてから本設定をするべきである。
- 先ほどのクエリ文字列を例とすると、名前にtestと設定したとする。また、統合リクエスト側では、名前にtest1としたとする。マッピング元は上記のまま。
- その場合、クライアントから受け付けたtestというパラメータ名を、test1に変換してバックエンドに転送することになる。これが、リクエストのマッピングである。
メソッドレスポンス
- 考え方は、リクエストの時と同じ。
- ただしレスポンスの場合は、ステータスコードによって、返却する内容が変わる可能性がある。例えば、200で返す時のヘッダーと401で返す時のヘッダーが異なるなど。
- 上記を考慮して、レスポンスごとにクライアントに返却するヘッダー/ボディーを定義できる。
統合レスポンス
- バックエンドからのレスポンスを、どのようにクライアントへのレスポンスにマッピングさせるかを定義する箇所である。
- 画像では、https://www.google.co.jp をバックエンドにしたときに、Googleから返ってくるX-Frame-Optionsというカスタムヘッダーを、x-trackにマッピングさせた例である。
- また、HTTPエラーの正規表現が300になっている。この意味として、バックエンドからのステータスコード300を、クライアントに返却するときには200に変換しますよ　というマッピングを示している。
- APIGW では、メソッドレスポンスのステータスコードが200の時には、空がデフォルト状態である。これは明示的に定義しない限りはすべてのレスポンスが200に変換されることを意味するため注意が必要である。

ざっくりイメージ

メソッドリクエストで、クライアントからどんなリクエストを受け付けるかの定義をして、バックエンド側に渡すときのマッピングを統合リクエストで実施する。
逆に、メソッドレスポンスで、クライアントへどんなレスポンスを転送するかの定義を行い、バックエンド側からのマッピングを統合レスポンスで実施する。

注意点

APIGWの仕様として、ヘッダーのマッピングができないレスポンスヘッダー名が存在する。x-amzn*系のヘッダー名など。
アプリケーションでカスタム出力しているヘッダーをマッピングさせたい場合のみ、ヘッダーマッピングは利用できると考えてよいだろう。

触ってみた感想

直観的に、プロキシ統合をOFFにする機会はあまり無いと感じた。
マッピング作業が必要になるため、抜け漏れのない設計とテストが必要になる。マネージドにできる方に倒すのがよいだろう。