API Gateway Lambda プロキシ統合とは？標準統合との違いとイベントオブジェクトへの影響を徹底解説
API Gateway で Lambda 関数を呼び出す方法を調べると、必ず『プロキシ統合』と『標準統合（非プロキシ統合）』という2つの選択肢に行き当たる。設定画面でチェックボックスひとつの違いに見えるが、Lambda 関数が受け取る event オブジェクトの構造、そしてレスポンスの返し方が根本的に変わる。どちらを選ぶかを誤ると、関数側でリクエストヘッダーが取れない、ステータスコードが固定されてしまうといった問題が本番環境で表面化する。 TL;DR — Lambda プロキシ統合 vs 標準統合 観点 Lambda プロキシ統合 標準統合（非プロキシ） マッピングテンプレート 不要（API Gateway が自動生成） 必須（VTL で自分で定義） event オブジェクト 固定スキーマ（headers, pathParameters, body など） テンプレートで自由に成形 HTTP ステータスコード制御 関数の戻り値で指定 API Gateway のメソッドレスポンスで設定 レスポンス変換 関数が JSON 構造を返す責務を持つ API Gateway 側でマッピング可能 向いているユースケース REST API の新規開発、マイクロサービス 既存バックエンドとの統合、レガシー変換 Lambda プロキシ統合の仕組みを理解する プロキシ統合を有効にすると、API Gateway は受信した HTTP リクエストをほぼそのまま Lambda に転送する。『ほぼそのまま』というのがポイントで、実際には API Gateway が決められたスキーマの JSON オブジェクトに変換して Lambda を呼び出す。このスキーマが Lambda プロキシ統合イベント と呼ばれる構造だ。 逆方向も同様で、Lambda 関数は API Gateway が期待する特定の JSON 構造をレスポンスとして返さなければならない。この構造を満たさない場合、API Gateway はクライアントに 502 Bad Gateway を返す。 graph LR Client[...