テーマ別の解説テーマ:LambdaとAPI Gateway:入力・テスト・失敗調査
AWS Lambda入門:イベント・関数・権限・実行条件を図解
AWS Lambdaは、サーバーの準備・管理をAWSへ任せてコードを動かすサービスです。現在はEvent Functions、Web Functions、MicroVMsという実行形態があります。この入門では、イベントを受けてハンドラー(処理の入口)を動かすEvent Functionsの通常のLambda実行環境を学びます。呼び出せたことと、目的のデータ処理が成功したことを分けて確認します。
イベントとハンドラー、呼出し側と実行ロール、同期/非同期と再試行、実行時間と状態の条件を区別できる。
IAMの主体・操作・対象、S3の役割。実AWSの関数やトリガーは作らない。例は架空のreportIdを文字列へ変換するだけで、業務データを取得・保存しない。
イベントが届くと、ハンドラーが処理する
- 呼出し側 → ハンドラー必要な呼出し権限と入力形式を確認する。
- ハンドラー → 関数の応答同期呼出しでは処理の応答を待つ。非同期の受付とは異なる。
- 呼出し側
- 処理したい内容をイベントとして渡す。
- ハンドラー
- 入力を読み、定めたコードを実行する。
- 関数の応答
- 返った値やエラーを呼出し側が確認する。
| 言葉 | 意味 | 今回の例 |
|---|---|---|
| イベント | 関数へ渡される入力 | reportIdを持つJSONオブジェクト |
| ハンドラー | 実行されるコードの入口 | 入力を確かめ、ラベルを返す関数 |
| トリガー | 出来事を関数の呼出しへ結び付ける設定 | S3のイベント通知等。今回は作成しない |
| 実行ロール | 関数のコードがAWS資源を使う権限 | S3読取り等を追加するなら必要な権限を検討 |
誰が呼べるかと、関数が何を使えるかは別
| 問い | 確認する主体と対象 | 混同しないこと |
|---|---|---|
| 誰が関数を呼べる? | 呼出し主体、関数、必要なアクションと適用ポリシー | 実行ロールを付ければ誰でも呼べる、ではない |
| 関数は何を取得・更新できる? | 関数の実行ロール、S3等の対象資源と適用制御 | 呼出しに成功すればS3も読める、ではない |
実行ロールは、Lambdaが関数のために引き受けるIAMロールです。ログやS3等への必要最小限のアクセスを与えます。関数を呼ぶ権限には呼出し側のポリシーや関数のリソースベースポリシー等が関わり、方法やアカウントの境界で確認が変わります。アプリの保存先の制御や暗号化、通信条件も別に確認します。
選択すると、正誤と理由が表示されます。
同期・非同期・ポーリングでは、受付と再試行が違う
| 方式 | 呼出し側が見るもの | 確認する失敗の扱い |
|---|---|---|
| 同期 | 関数の応答やエラーを待つ | 直接呼出しでは関数エラーを呼出し側が扱う。連携サービス側の再試行も確認 |
| 非同期 | イベントの受付を先に返す | 受付は処理完了ではない。再試行・イベント期限・失敗先等を確認 |
| イベントソースマッピング | Lambdaがキューやストリームから読み、まとめて関数へ渡す | バッチの失敗・再試行・重複の扱いはソース等の条件を確認 |
冪等(べきとう)とは、同じ処理要求が繰り返されても、意図しない二重処理を避ける設計です。イベントソースマッピングでは重複した処理が起こり得ます。通知を受け付けた応答だけで「帳票を保存できた」と報告せず、関数の処理結果と業務上の成果を確認します。
選択すると、正誤と理由が表示されます。
小さな例:入力を確かめてラベルを返す
次はJavaScriptの純粋な変換例です。S3から帳票を読む処理や、保存・通知・ログ送信は含みません。 reportIdは1〜40文字の半角英数字とハイフンに限定します。実際のイベント形式は連携元ごとに異なるので、この独自形式をS3やAPI Gatewayの形式へ読み替えないでください。
export async function handler(event) {
if (!event || typeof event !== 'object' || Array.isArray(event) ||
!Object.hasOwn(event, 'reportId') ||
typeof event.reportId !== 'string' ||
!/^[A-Za-z0-9-]{1,40}$/.test(event.reportId)) {
throw new Error('Invalid reportId');
}
return { reportId: event.reportId, label: 'Report ' + event.reportId };
}| 入力 | 結果 | まだ行わないこと |
|---|---|---|
| {"reportId":"demo-001"} | reportIdと「Report demo-001」を返す | 帳票の検索・保存・読取り |
| 同じ入力をもう一度 | 同じ値を返す。追加の保存はしない | DB更新の重複排除を検証すること |
| reportIdなし / 配列 / 不正文字 | 入力不正としてエラー | 本番のリトライ先やHTTP応答への変換 |
戻り値・ログ・HTTP応答は、別の情報
テストイベントは、ハンドラーへ渡すJSON入力です。コンソールのテストは同期呼出しで、戻り値とログをそれぞれ確認します。戻り値は呼出し側へ返すデータ、ログは処理の出来事を記録する情報です。ログの内容が、そのまま戻り値やHTTP本文になるわけではありません。
- テストイベント → ハンドラーJSON入力を渡す
- ハンドラー → 戻り値returnでデータを返す
- ハンドラー → 診断ログ診断記録を別に出力する
- テストイベント
- 入力例はreportId。呼出し方式は同期。
- ハンドラー
- 入力を確かめ、処理する。ログは別に出力。
- 戻り値
- この例はreportIdとラベルを返す。
- 診断ログ
- この例は処理段階と要求の対応を記録。
| 読むもの | この例で与えた内容 | ここから言えること |
|---|---|---|
| 入力イベント | {"reportId":"demo-001"} | ハンドラーが受け取る入力。保存・通知の指示はない。 |
| ハンドラーの戻り値 | {"reportId":"demo-001","label":"Report demo-001"} | ラベルを作って返した。帳票の保存成功を表すデータではない。 |
| アプリの診断記録 | 要求の別名lambda-A / step: label-created / reportId: demo-001 | この別版ではラベル作成の段階を記録したと仮定。戻り値そのものではない。 |
| 基盤側の記録の要約 | 同じlambda-AについてSTART / END / REPORT | Lambdaの実行に関わる記録。レポート保存等の業務成果を自動で証明しない。 |
表のlambda-Aは文書用の別名です。対象は文書用アカウント111122223333、ap-northeast-1、関数report-labelのversion 7、2026-10-27 00:00:00 UTC付近とします。実調査では、アカウント・リージョン・関数/版・時刻の範囲をそろえ、LambdaのawsRequestId等で同じ呼出しの記録を照合します。近い時刻、同じreportId、同じログストリームだけで同一要求と決めません。
| 方式・観測 | この例の根拠 | 判断 |
|---|---|---|
| 直接のLambda Invoke / RequestResponse | StatusCodeは200だが、FunctionErrorあり。PayloadにはInvalid reportIdというエラー。 | 200だけで関数成功とは言わない。関数実行のエラー情報も読む。 |
| HTTP API → Lambda / payload format 2.0 | 別のハンドラーがstatusCode:200と、bodyにreportId/readyを明示して返した。 | 正常に受け渡された場合のHTTP応答は200。readyはアプリが定めた状態で、保存・通知の完了までは証明しない。 |
| 業務上の完了 | 目的の成果物や対象操作の結果を、要件に沿って別に確認。 | 関数の正常return、HTTPの2xx、目的の業務が完了したことを区別する。 |
HTTP APIでは、API GatewayのrequestContext.requestIdと、LambdaのawsRequestIdを同じ値と仮定しません。例えばAPI側api-AとLambda側lambda-Bは、対応関係が確認できた場合だけ結び付けます。別のlambda-Cが同じ時刻に見つかっただけでは代用できません。上の独自reportId入力も、HTTP APIのpayload format 2.0イベントへ自動で変わるわけではありません。
選択すると、正誤と理由が表示されます。
実行時間・同時実行・保存する状態を確認する
今回の通常のLambda実行環境のEvent Functionは、1回の実行が最大900秒(15分)です。同時実行にもリージョンやアカウント等のクォータがあります。時間上限、待ち時間、受け付ける量、下流のDBやAPIの処理能力を一緒に設計します。Managed Instancesの一部の呼出しやDurable Functions等の別方式へ、この15分の条件を一括適用しません。
実行環境は再利用されることがあり、メモリや/tmpの一時データが残る場合がありますが、永続的な保存先としては保証されません。前回の利用者データを共有の変数やキャッシュへ残さず、次の呼出しが同じ環境へ来る前提にも依存しません。 必要な状態は、目的に合う保存先と権限で管理します。
費用は、回数・メモリ・時間と周辺資源で考える
通常のEvent Functionsでは、リクエストと、メモリ設定・実行時間等が料金の要素です。再試行、同時実行の準備、追加の一時ストレージ、ログや他サービス等も条件に応じて確認します。「呼ばれない間はシステム全体が必ず無料」「EC2より必ず安い」とは判断しません。
- 入力元とイベント形式、処理の終わりを定義する。
- 呼出し権限と実行ロール、対象資源の制御を分ける。
- 同期/非同期/ポーリングと、再試行・重複・失敗の扱いを決める。
- 時間・同時実行・状態・下流の容量と費用を確認する。
- 同じ入力と不正入力でコードを確認し、実AWSで確認していないことは分けて記録する。
確認して、自分の言葉で説明する
- 呼出し、コード実行、業務上の完了を分けて説明する。
- 二つの権限の向きと、呼出し方式ごとの失敗を確認する。
- 対象の実行方式を明示して、時間・状態・費用を判断する。
理解を確かめる: Lambdaを呼べたら、関数が必要なAWS資源を使って処理を完了できたことになる?
ならない。呼出し権限、実行ロール、処理結果と成果物を分けて確認する。
非同期の受付や関数の起動は、保存や通知等の業務処理の成功を証明しません。対象と条件をそろえて結果を確認します。
出典と確認した条件
説明に用いた公式資料を、確認した内容・条件と本文の参照箇所に分けてまとめています。専門家による監修・実際のAWSとの比較検証は行っていません。
確認した内容・条件現行Event/Web/MicroVMsの区別。入門と比較は通常のEvent Functionsを中心にし、全方式へ一般化しない。
確認した内容・条件コードがAWS資源を使う実行ロールと最小権限。呼出し権限と区別。
参照した本文イベントが届くと、ハンドラーが処理する 誰が呼べるかと、関数が何を使えるかは別 実行時間・同時実行・保存する状態を確認する
確認した内容・条件主体・操作・対象・条件に基づくリソース側権限。実行ロールで呼出し権限を代用せず、実ポリシー変更なし。
参照した本文誰が呼べるかと、関数が何を使えるかは別
確認した内容・条件関数の応答を待つ方式。APIの受付成功だけで業務成功にしない。
確認した内容・条件処理前の受付/キューと、その後の処理結果を分離。受付を完了証明にしない。
参照した本文同期・非同期・ポーリングでは、受付と再試行が違う
確認した内容・条件ポーリング/バッチ・ソース別失敗・重複を確認。通知元のトリガーとマッピングを区別。
確認した内容・条件直接呼出しと非同期/ソース側再試行を分け冪等性を確認。厳密な一度だけの保証はしない。
参照した本文同期・非同期・ポーリングでは、受付と再試行が違う
- Lambda quotas確認日:
確認した内容・条件通常Event Functionの900秒とアカウント/リージョン等の同時実行条件。他の実行方式の条件と混同しない。
確認した内容・条件通常環境の再利用・初期化と一時メモリ/tmp。Managed Instances/Durable等の方式差を除外。
参照した本文実行時間・同時実行・保存する状態を確認する
確認した内容・条件入力検証・冪等性・再利用環境でのユーザーデータ保持回避、再帰と下流/費用を確認。
参照した本文実行時間・同時実行・保存する状態を確認する
確認した内容・条件通常Event Functionsの回数/メモリ時間と条件付き追加費用。他方式料金を分離。金額や常時最安を断定しない。
参照した本文費用は、回数・メモリ・時間と周辺資源で考える
確認した内容・条件テストイベントはJSON入力で、コンソールのテストは同期実行。例を実行したわけではなく、既存の独自reportId形式を維持する。
参照した本文戻り値・ログ・HTTP応答は、別の情報
確認した内容・条件実行roleのログ権限、保存先と反映待ちを確認。ログ未取得を未実行の証拠にせず、関連CloudWatch費用も別扱い。
参照した本文戻り値・ログ・HTTP応答は、別の情報
確認した内容・条件runtimeのSTART/END/REPORTとアプリ出力、JSONログのtimestamp/requestId/messageとlevelフィルタを確認。環境変数やevent全体を出力する公式例は採用しない。
参照した本文戻り値・ログ・HTTP応答は、別の情報
確認した内容・条件RequestResponseのAPI StatusCode 200はFunctionErrorの有無を表さない。FunctionError/PayloadとLogResultの別欄を確認。
参照した本文戻り値・ログ・HTTP応答は、別の情報
確認した内容・条件awsRequestIdはLambda呼出しのID。functionName/functionVersion/invokedFunctionArn等で対象を確認する。
参照した本文戻り値・ログ・HTTP応答は、別の情報
確認した内容・条件HTTP APIのpayload format 2.0と明示statusCode/body形式、API requestContext.requestIdを確認。直接Invokeや独自event形式と混同しない。
参照した本文戻り値・ログ・HTTP応答は、別の情報
確認した内容・条件Gateway requestId、統合側ID、Lambda側/関数側statusは別項目。異なる層のIDを同一値と仮定しない。
参照した本文戻り値・ログ・HTTP応答は、別の情報
確認した内容・条件関数が整形して返すHTTPエラーと、関数例外/不正形式の違いを確認。正常returnをHTTP 2xxや業務成功と同一視しない。
参照した本文戻り値・ログ・HTTP応答は、別の情報