テーマ別の解説テーマ:LambdaとAPI Gateway:入力・テスト・失敗調査
API Gateway入門:HTTP APIとLambdaの連携・認可を図解
Amazon API Gatewayは、アプリからのAPI要求を受け取り、設定した処理先へつなぐAWSサービスです。 Lambdaが処理を実行し、API Gatewayは要求の振り分けやアクセス制御、HTTP応答への受け渡しを担います。「レポートを1件取得する」例で、入口から応答までを追いましょう。
用途に合うAPI種別を選び、HTTP APIの1要求について、ルート・認可・Lambda統合・応答を説明し、失敗した段階を根拠から区別できる。
Lambdaのイベント・ハンドラー・戻り値とログの違い・実行ロールと、HTTP要求にメソッド・パス・応答コードがあること。必要な用語は本文でも説明します。AWSアカウントや課金操作は不要です。固定の架空例を読み、選択問題で確かめます。実APIの作成・呼出しやトークン入力は行いません。
何を公開したいかで、APIの種類を選ぶ
APIは、アプリ同士が決めた形式で要求と応答をやり取りするための窓口です。ここでは「GETで指定したレポートの情報を返す」という約束を作ります。API Gateway自体がレポートの業務判断や保存をすべて引き受けるわけではありません。
| 種類 | 選ぶ理由の例 | この教材での扱い |
|---|---|---|
| HTTP API | HTTPの要求・応答でLambdaへつなぎ、JWTによるアクセス制御を使いたい。 | この教材の中心。必要な機能が足りることを確認して選ぶ。 |
| REST API | private API endpoint、AWS WAF連携、リクエスト検証や利用プラン等が必要。 | HTTP APIとの差を知る。構築手順は扱わない。 |
| WebSocket API | 接続を維持し、チャット等でサーバー側からもメッセージを送りたい。 | 1要求1応答とは異なる用途として区別する。 |
LambdaをHTTPで呼ぶ方式にはfunction URLもあります。この教材は、ルートとJWT authorizerを持つHTTP APIを選んだ場合を学びます。Lambdaを使うならAPI Gatewayが必須、とはしません。
選択すると、正誤と理由が表示されます。
ルートは「何を求めたか」、統合は「どこで処理するか」
| 用語 | 意味 | 固定例 |
|---|---|---|
| メソッド / パス | 何の操作を、どの対象へ求めるか。GETは取得の要求。 | GET /reports/demo-001 |
| ステージ(stage) | デプロイしたAPIを利用する環境・参照先。ルートの照合より先に選ばれる。 | この例では到達すべきステージが選択済み。 |
| ルート(route) | HTTPメソッドとパスの組合せで、受け付ける要求を表す。 | GET /reports/{reportId} |
| 統合(integration) | 選ばれたルートを、処理するLambda等のbackendへつなぐ設定。 | この例はLambda proxy integration、payload format 2.0。 |
- アプリの要求 → API GatewayHTTP要求
- API Gateway → Lambda同期呼出し
- アプリの要求
- GET /reports/demo-001を要求する。
- API Gateway
- ルートを照合し、この例のJWT認可を確認。
- Lambda
- 渡されたイベントを処理し、応答を返す。
図の矢印は要求の向きです。応答は逆に、Lambdaの応答 → API Gateway → 呼び出したアプリへ返ります。API Gatewayは同期呼出しの結果を待って、HTTP応答へ受け渡します。Lambdaからアプリへ直接接続し直す図ではありません。
選択すると、正誤と理由が表示されます。
固定例:要求がイベントになり、応答がHTTPになる
イベントはLambdaへ渡す入力です。このHTTP APIでは、イベントと応答の形式であるpayload format 2.0を選びます。GET /reports/demo-001のdemo-001は、pathParameters.reportIdに入ります。任意のevent.reportIdを自動で作るわけではありません。API種別やformat versionを変えると入力形式も変わるので、混ぜて読みません。
{
"version": "2.0",
"routeKey": "GET /reports/{reportId}",
"pathParameters": {
"reportId": "demo-001"
},
"requestContext": {
"http": {
"method": "GET"
},
"authorizer": {
"jwt": {
"claims": {
"sub": "reader-demo"
},
"scopes": [
"reports:read"
]
}
}
}
}Lambdaのハンドラーは、reportIdの形式、利用者にそのレポートを見せてよいか、対象データがあるかを判断します。この例ではdemo-001が閲覧可能で、状態readyを返すという与件です。返すのはレポートの情報で、PDF本体ではありません。保存先への接続や実データの検索は実装・実行しません。
{
"statusCode": 200,
"headers": {
"content-type": "application/json"
},
"body": "{\"reportId\":\"demo-001\",\"state\":\"ready\"}",
"isBase64Encoded": false
}| 項目 | 意味 |
|---|---|
| statusCode: 200 | HTTPの応答コード。この例では正常な取得応答と指定した。 |
| headers | content-typeで本文をJSONとして扱うことを示す。 |
| body | JSON文書を表す文字列。外側のJSONでは引用符がエスケープされる。 |
| isBase64Encoded: false | この例のbodyはBase64符号化ではない。 |
選択すると、正誤と理由が表示されます。
同じエラーコードでも、どこで止まったかを確かめる
| 段階 | 例 | 確認する根拠 |
|---|---|---|
| API / stage / route | 到達先やメソッド/パスが合わない。該当routeなしはNot Found。 | 到達先、stage、定義したroute、fallbackの有無。 |
| JWT authorizer | 無効なaudience等で401の応答。 | JWT authorizer設定、応答のwww-authenticate等。生トークンを共有しない。 |
| Lambdaの呼出し | Lambda APIがinvoke要求を拒否した場合は500。 | 対象関数・invoke許可と、利用可能な統合エラー情報。 |
| 関数 / 応答形式 | 関数エラーや不正な応答形式では502。 | 同じ要求に対応する関数の記録、返した形式、統合情報。 |
| アプリが意図して返すHTTP結果 | 許可された検索範囲に対象がなく、正しい形式で404を返す等。 | アプリの判定と明示したstatusCode。関数呼出し自体の失敗とは別。 |
| 例 | 与えられた条件 | 読み取ること |
|---|---|---|
| R2 | R1設計へPOSTで要求。一致するrouteなし。Lambdaは呼ばれていない。 | 入口のメソッド/routeの不一致。レポートDBを直す根拠はまだない。 |
| R3 | GET routeと認可が一致。Lambdaは実行済み。対象がなく、関数が明示的な404応答を返した。 | アプリの対象検索の結果。GET routeがないという結論ではない。 |
実調査では時刻・対象API/stage・requestId等を揃え、設定したアクセスログと関数側の記録を照合します。ログはstageごとに別途有効化するもので、見つからないことだけで「呼ばれていない」とは断定しません。表の500/502も、世の中の全500/502を一意に診断する表ではありません。API GatewayのrequestContext.requestIdとLambdaのawsRequestIdを同じ値と仮定せず、対象・版・時刻と、確認できた要求の対応関係から照合します。
選択すると、正誤と理由が表示されます。
待てる時間と、システム全体の費用を確認する
| 対象 | 仕様値 | 読み違えないこと |
|---|---|---|
| HTTP APIのintegration timeout | 最大30秒、増加不可。 | Lambdaのtimeoutを長くしても、この待ち時間の上限は伸びない。 |
| HTTP APIのpayload | 10 MB。 | Lambda連携全体で10 MBの本文を必ず送れるわけではない。 |
| 通常の同期Event Function | timeout最大900秒。buffered要求/応答は各6 MB。 | イベントの包みや符号化にもサイズが必要。HTTP APIの待ち時間や受入容量を上書きしない。 |
HTTP APIとREST APIはAPI呼出しや外向きデータ転送、WebSocket APIはメッセージと接続時間が費用要因です。Lambdaの要求数・実行時間、ログ等の関連サービス費用も別に考えます。この教材を読むためのAWS利用はありませんが、同じ構成を実AWSに作れば無料とは限りません。地域・利用量・アカウントの無料枠やcredit条件は、実装前に最新の料金資料で確認します。
選択すると、正誤と理由が表示されます。
確認して、自分の言葉で説明する
- GET /reports/demo-001を、メソッド・パス・stage・route・integrationに分けて説明する。
- 利用者のJWT認可、API Gatewayのinvoke許可、関数の実行ロール、対象レポートの認可を分ける。
- R2/R3の失敗段階と、R4の待ち時間の不適合を、与えられた根拠から説明する。
理解を確かめる: レポート取得用のHTTP APIを設計するとき、Lambdaを選んだだけでは決まらないものは?
受け付けるメソッドとパス、stage/routeと統合、利用者と対象の認可、サービス間権限、イベント/応答形式、期限・容量・費用を決める。
Lambdaは業務処理を動かす部分です。APIへの到達、許可、データの受け渡し、HTTPの結果を別々に設計すると、失敗した段階も根拠から調べられます。
出典と確認した条件
説明に用いた公式資料を、確認した内容・条件と本文の参照箇所に分けてまとめています。専門家による監修・実際のAWSとの比較検証は行っていません。
確認した内容・条件Gateway requestIdと統合側の要求ID/状態は別の項目。Lambda側との対応を値の同一だけで決めない。
参照した本文同じエラーコードでも、どこで止まったかを確かめる
確認した内容・条件awsRequestIdはLambda呼出しのID。関数/版/呼出し先と時刻の範囲をそろえる。
参照した本文同じエラーコードでも、どこで止まったかを確かめる
確認した内容・条件HTTP APIとREST APIはどちらもRESTful。private API endpoint、WAF、利用プラン等の差とHTTP APIのJWT authorizerを確認。private integrationとprivate APIを混同しない。
参照した本文何を公開したいかで、APIの種類を選ぶ
確認した内容・条件双方向・接続維持・サービスからのpushという選択軸を確認。実装手順や再接続保証は対象外。
参照した本文何を公開したいかで、APIの種類を選ぶ
確認した内容・条件stage選択後のmethod/path照合、パス変数、ANY/$default、該当routeなしの応答を確認。例はGETのみ・fallbackなし。
確認した内容・条件payload format 2.0のpathParameters、JWT claims、明示statusCode/headers/body/isBase64Encodedを確認。例は抜粋で完全イベントではない。
参照した本文何を公開したいかで、APIの種類を選ぶ ルートは「何を求めたか」、統合は「どこで処理するか」 固定例:要求がイベントになり、応答がHTTPになる 同じエラーコードでも、どこで止まったかを確かめる
確認した内容・条件署名・発行者・宛先・時刻条件とroute scopeを確認。複数scopeは少なくとも一つ。トークン値やログイン実装は掲載しない。
参照した本文ルートは「何を求めたか」、統合は「どこで処理するか」 固定例:要求がイベントになり、応答がHTTPになる 利用者の認可と、AWS側の権限を分ける
確認した内容・条件同期呼出し、Lambda resource-based policyのinvoke許可と範囲、function URLという別方式を確認。公式のOpen作成手順を実行・転載しない。
参照した本文何を公開したいかで、APIの種類を選ぶ ルートは「何を求めたか」、統合は「どこで処理するか」 利用者の認可と、AWS側の権限を分ける
確認した内容・条件関数からAWS資源への実行roleと最小権限を確認。利用者JWTやAPI Gatewayのinvoke許可と区別する。
確認した内容・条件Lambda APIの呼出し拒否500、関数エラー/不正形式502、整形した独自HTTP応答、API Gatewayによる再試行なしを確認。全500/502の原因を断定しない。
参照した本文同じエラーコードでも、どこで止まったかを確かめる
確認した内容・条件401の例とwww-authenticateのaudience情報を確認。生JWTを外部サイトへ貼る手順は採用しない。
参照した本文同じエラーコードでも、どこで止まったかを確かめる
確認した内容・条件stageごとのアクセスログ設定とrequestId/routeKey/statusを確認。ログが自動的に全て残るとはしない。
参照した本文同じエラーコードでも、どこで止まったかを確かめる
確認した内容・条件CORSのブラウザによるcross-origin制御と、認可/サーバー処理との境界を確認。許可元を全開放する手順は追加しない。
参照した本文利用者の認可と、AWS側の権限を分ける
確認した内容・条件HTTP APIのintegration timeout最大30秒・増加不可とpayload 10 MBを確認。REST/WebSocketへ一般化しない。
参照した本文待てる時間と、システム全体の費用を確認する
- Lambda quotas確認日:
確認した内容・条件通常の同期Event Functionの最大900秒、buffered同期payloadは要求/応答各6 MBという別制約を確認。Web Functions等の別モデルへ一般化しない。
参照した本文待てる時間と、システム全体の費用を確認する
確認した内容・条件HTTP/RESTは呼出しと外向き転送、WebSocketはメッセージと接続時間、Lambda等の追加費用を確認。地域単価や無料枠適格性は断定しない。
参照した本文待てる時間と、システム全体の費用を確認する
確認した内容・条件API keyを認証/認可に使わないことと、usage plan quota/throttleがbest effortであることを確認。HTTP APIの機能とはしない。