← AWSサービスの内部原理 コース
39. 4段のリクエストパイプライン — メソッドリクエストから統合レスポンスまで
API Gateway の REST API が 1 リクエストを 4 段のパイプラインでどう変換して返すかを、図で順番に追っていきます。
① 4段のパイプライン — 行きで2回、帰りで2回
クライアント
① メソッドリクエスト入口の契約
メソッド/パス・必須パラメータ・認可・モデル検証を宣言② 統合リクエストバックエンド向けに変換
帰り
バックエンドLambda / HTTPエンドポイント / AWSサービス(DynamoDB等)
③ 統合レスポンスクライアント向けに変換
④ メソッドレスポンス返す形の宣言
ステータスコード・ヘッダ・ボディクライアントへ返却
- ①④(メソッド側)= クライアント契約のインターフェイス
- ②③(統合側)= 実装(バックエンド)に接続する境界
- 間に変換層を挟むので、バックエンドの都合を変えてもクライアント契約を保てる(インターフェイスと実装の分離)
REST API の 1 リクエストは API Gateway 内で 4 段を順番に通る。メソッド側がクライアントに見せるインターフェイス、統合側がバックエンドという実装への境界。
② 変換が効くのは「非プロキシ統合」だけ
統合タイプの選択
非プロキシなら
プロキシ統合ほぼ素通し・変換なし
AWS推奨: セットアップが簡潔でバックエンドの変化に追従しやすい非プロキシ統合4段の変換が本領発揮
レベル1: パラメータマッピング
レベル2: マッピングテンプレート
プロキシ統合ではリクエスト/レスポンスはほぼ素通しで、変換は基本行われない。以降の 2 レベルの変換は、契約とバックエンドの形を意図的にずらしたい非プロキシ統合の話。
③ レベル1: パラメータマッピング — パス・クエリ・ヘッダの付け替え
x-version ヘッダクライアントが送信
触れる範囲は?
app-version ヘッダ統合リクエストで読み替えてバックエンドへ
パス / クエリ / ヘッダ○ 対象
ボディ× 対象外
ステータスコード× 対象外
- 逆方向(統合レスポンス→メソッドレスポンスのヘッダ写し、例: CORS用固定ヘッダ)も可能だが、レスポンス側は非プロキシ統合が前提
- 200→204 のようなステータスコード書き換えは不可 → マッピングテンプレートのオーバーライド、または選択パターンによる振り分けで行う
- ヘッダ・ボディ・ステータスコードが別々の要素という HTTP メッセージの構造が、そのまま設計に効いている
VTL のスクリプトを書かずに、パスパラメータ・クエリ文字列・ヘッダ値を付け替える。触れるのはこの 3 つだけで、ボディとステータスコードは対象外。
④ レベル2: マッピングテンプレート — ボディまで書き換える VTL
入力ペイロードJSONPath式で値を取り出す
出力文字列を生成
VTLテンプレートContent-Type ヘッダで選択
行き=クライアントのリクエストの Content-Type / 帰り=バックエンド応答の Content-Type別の形のJSONなどボディごと書き換え可能
- パラメータの条件付きオーバーライド・新しいヘッダ値の作成・ステータスコードの上書きも可能
- Content-Type に一致するテンプレートが 1 つも無いとき、そのまま通すか拒否するかの設定 = 統合パススルー挙動
- 使い分けの目安: ボディを変えたい・条件付きの上書き → テンプレート / パス・クエリ・ヘッダの付け替えで済む → パラメータマッピング
VTL + JSONPath で入力ペイロードから値を取り出し、別の形の JSON を組み立てる。テンプレートエンジンという計算モデルそのもの。
⑤ デフォルトのメソッドレスポンス — 未知の応答を安全側に倒す
バックエンドの応答2XX / 4XX / 5XX … 将来何を返すかは事前に全部は知れない
定義済みメソッドレスポンス明示的にマッチした応答を返す
デフォルト = 500マッチしない未知の応答の受け皿
AWSが良い習慣とする設定- メソッドレスポンスが 0 個 → 成功していても API Gateway は 500 を返す
- 想定外はサーバーエラーとして扱う=未知の入力に安全側に倒す、堅牢なインターフェイス設計の一般原則の具体例
非プロキシ統合ではメソッドレスポンスを最低 1 つ設定しないと、バックエンドが成功していてもクライアントには 500 が返る。将来の応答を全部は予測できないので、デフォルトを 1 つ置く。