API Gateway「Lambda プロキシ統合」と 「カスタム統合（非プロキシ統合）」のリクエストデータの比較

oishi.t

はじめに

API GatewayのLambdaプロキシ統合を使用したことはありましたが、カスタム統合の場合はどのようにLambdaへデータが送られるのか検証してみました。

ざっくりとそれぞれの違い

Lambdaカスタム統合（非プロキシ統合）

  • 統合リクエストでマッピングテンプレート（Velocity Template Language: VTL）を使用して、Lambdaのリクエスト・レスポンスの内容を自由に変換・構成できる。
  • マッピングテンプレートを使用しないとリクエストボディがそのまま送られる。（クエリパラメーターやヘッダーが渡らない）

Lambdaプロキシ統合

  • Lambdaへ渡すデータ構造が決まっているが、カスタマイズをしなくてもリクエストのeventデータを自動である程度構造化してくれる。

※ここでいう「決まった構造」はAWSのドキュメントで公開されていますので、下記を参照ください。
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format

※Lambdaプロキシ統合は出力に関しても構造が決まっています。
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format

HTTPリクエストに対してのそれぞれのLambdaへの渡し方の違い

ここではあるリクエストを「Lambdaカスタム統合」「Lambdaプロキシ統合」に送った際にどのような構造体でLambdaに届くか実際にAPIを作成し、比較してみます。

共通のHTTPリクエスト

  • URL クエリ文字列パラメータ：user
  • リクエストbody: message
    • 例）{ "message" : "メッセージです。"}

Lambdaカスタム統合（非プロキシ統合）

まずサンプルのLambdaを作成していきます。
CloudWatch Logsにeventを出力するようにしています。

def lambda_handler(event, context):
    print("Received event:", event)
    return {
        'statusCode': 200,
        'body': 'Lambda received the event.'
    }

次にAPI GatewayでREST APIを作成していきます。
メソッドタイプはPOST、Lambda プロキシ統合はオフにしておきましょう。
また、先ほど作成したLambdaを指定します。

次にマッピングテンプレートを作成します。
コンテンツタイプを「application/json」にして、下記を記述してください。

{
  "username": "$input.params('user')",
  "message": $input.json('$.message')
}

これでLambdaカスタム統合（非プロキシ統合）のAPIが完成しました。
テストしてみましょう。
以下を実行するし、CloudWatchのログを確認すると、

curl -X POST \
  'https://xxxxxxx.execute-api.ap-northeast-1.amazonaws.com/prod/custom-togo?user=taro' \
  -H 'content-type: application/json' \
  -d '{
    "message": "Hi!!"
}'

マッピングテンプレートで指定した構造でLambdaに渡っていることがわかります。

ちなみにマッピングテンプレートを指定しないとリクエストbodyだけがそのまま送られます。

Lambdaプロキシ統合

先ほどと同じく、APIを作ります。
今回はLambda プロキシ統合にチェックを入れましょう。

これだけでAPIの設定は完了です。

ではテストしていきます。リソース名だけ変えて、下記を実行していきます。

curl -X POST \
  'https://xxxxxxx.execute-api.ap-northeast-1.amazonaws.com/prod/proxy-togo?user=taro' \
  -H 'content-type: application/json' \
  -d '{
    "message": "Hi!!"
}'

CloudWatchのログを見ると
明らかにカスタム統合とは違いますね！
簡単に多くの情報を扱うことができそうです。

おわりに

以上、Lambdaカスタム統合とプロキシ統合のLambdaへのデータの渡し方の比較でした。
プロキシ統合を使えばサクッとAPIが作れて、シンプルなAPIを使うときによさそうですね。
一方、カスタム統合はあらかじめLambdaへ渡す構造が決まっている場合などに使う必要がありそうです。

参考

https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/models-mappings.html
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/getting-started-lambda-non-proxy-integration.html
https://dev.classmethod.jp/articles/for-beginner-build-apigateway-with-noproxy-and-proxy-lambda/#note-514573-1
https://blog.usize-tech.com/aws-apigateway-lambda-proxy/

Last modified: 2025-05-27

Author