Lambda Web AdapterでSQSイベントを処理する
目次
Lambda Web Adapterを使って、SQSのような非HTTPイベントをWebアプリで処理してみました。
HTTPリクエスト以外のイベントをどのように変換して扱うのか、部分的なバッチレスポンスの実装方法まで紹介します。
この記事は、クラウドビルダーズ Advent Calendar 2025の記事です。
1. この記事の要約
- Lambda Web Adapterは、SQSなどの非HTTPイベントもWebアプリで処理できる
- イベントは
POST /eventsのHTTPリクエストに変換される - 部分的なバッチレスポンスは、レスポンスボディに
batchItemFailuresを設定して実現 - レスポンスストリーミングモードはオフにする必要がある(デフォルトはオフ)
2. Lambda Web Adapterとは?
Lambda Web Adapter(LWA)は、任意のウェブアプリケーションをコード変更なしでAWS Lambda上で動作させるためのツールです。
Lambda Extensionとしてデプロイされ、LambdaへのイベントをHTTPリクエストに変換してWebアプリに転送します。
基本的な仕組みについては、前回の記事で詳しく解説しています。
また、builders.flashの記事と図がわかりやすく解説しています。

https://aws.amazon.com/jp/builders-flash/202301/lambda-web-adapter/
この図を見ると、ALB、API Gateway、CloudFront(+ Function URL)からのHTTPリクエストを処理する様子がわかります。
では、これ以外のイベントソース(例えばSQSのイベントソースマッピング)からのイベントは、どのように変換されるのでしょうか。
3. 非HTTPイベントとは?
非HTTPイベントとは、SQSやS3のようなHTTPリクエストではないイベントのことです。
LambdaはHTTPリクエスト以外にも、様々なAWSサービスからイベントを受け取れます。
主な非HTTPイベントソースの例です。
- SQS(Simple Queue Service)
- S3(Object Created/Deletedイベント)
- DynamoDB Streams
- EventBridge
- SNS
これらのイベントは、それぞれ固有のJSON構造を持っています。
4. LWAによる非HTTPイベントの変換
4-1. 変換の仕組み
LWAは、非HTTPイベントを以下のルールでHTTPリクエストに変換します。
- メソッド:
POST固定 - パス:
/events(デフォルト) - ボディ: Lambdaが受け取ったイベントの内容がそのまま入る
- ヘッダー:
Content-Type: application/json
4-2. 実際の変換例
SQSイベントの場合、Webアプリのミドルウェアでログを出力すると、以下のようなHTTPリクエストに変換されていることがわかります。
{
"method": "POST",
"url": "http://127.0.0.1:3000/events",
"headers": {
"content-type": "application/json"
},
"requestBody": {
"Records": [
{
"messageId": "XXX",
"receiptHandle": "XXX",
"body": "{\"data\": \"failure message\", \"shouldFail\": true}",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "XXX",
"SenderId": "XXX",
"ApproximateFirstReceiveTimestamp": "1765884146090"
},
"messageAttributes": {},
"md5OfMessageAttributes": null,
"md5OfBody": "d703a728d0e48d5496d87914cf5860c6",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:ap-northeast-1:XXX:tanstack-start-queue",
"awsRegion": "ap-northeast-1"
}
]
}
}このように、SQSとLambdaを普通に統合したときのeventの内容が、そのままHTTPリクエストのボディに入ります。
5. Webアプリでの実装方法
TanStack Startでの実装例を示しています。
5-1. 基本的な実装
WebアプリでPOST /eventsのルートを作成すれば、SQSイベントを受け取れます。
TanStack Startでの実装例です。
// /src/routes/events.ts
import { createFileRoute } from "@tanstack/react-router";
import { json } from "@tanstack/react-start";
import type { SQSEvent } from "aws-lambda";
export const Route = createFileRoute("/events")({
server: {
handlers: {
POST: async ({ request }) => {
try {
// 簡易的にcastしているが、本来はvalidateすべき
const event = (await request.json()) as SQSEvent;
// イベント処理
await processEvent(event);
// 成功時は200を返す
return json({}, { status: 200 });
} catch (error) {
// 失敗時は500を返す
return json({}, { status: 500 });
}
},
},
},
});5-2. 失敗のハンドリング
失敗を通知するには、AWS_LWA_ERROR_STATUS_CODES環境変数で失敗とみなすステータスコードを定義します。
例えば、以下のように設定します。
AWS_LWA_ERROR_STATUS_CODES=500,503この設定により、ステータスコード500または503を返すと、Lambdaは実行失敗として扱われます。
6. 部分的なバッチレスポンスの実装
6-1. 部分的なバッチレスポンスとは?
SQSでは、複数のメッセージをバッチで受け取り、一部のメッセージだけ処理を失敗させることができます。
これを「部分的なバッチレスポンス」と呼びます。
詳細は以下の記事で解説されています。
https://qiita.com/omochi_1190/items/0e75c08970f290656b30
部分的なバッチレスポンスを使用すると、以下のメリットがあります。
- 成功したメッセージは再処理されない
- 失敗したメッセージだけがキューに戻される
- 処理効率が向上する
6-2. レスポンスの形式
部分的なバッチレスポンスを返すには、レスポンスボディにbatchItemFailuresを設定します。
{
"batchItemFailures": [
{
"itemIdentifier": "失敗したメッセージID"
}
]
}6-3. 実装例
TanStack Startでの実装例です。
import { createFileRoute } from "@tanstack/react-router";
import { json } from "@tanstack/react-start";
import type { SQSEvent, SQSRecord } from "aws-lambda";
// Lambda部分的なバッチレスポンスの型定義
interface BatchItemFailure {
itemIdentifier: string;
}
interface SQSBatchResponse {
batchItemFailures: BatchItemFailure[];
}
export const Route = createFileRoute("/events")({
server: {
handlers: {
POST: async ({ request }) => {
try {
const event = (await request.json()) as SQSEvent;
logger.info({
msg: "Received SQS event",
recordCount: event.Records.length,
});
// 失敗したメッセージのIDを収集
const batchItemFailures: BatchItemFailure[] = [];
// 各メッセージを個別に処理
// Promise.allSettledを使用して並列処理しつつ、エラーでも継続
const results = await Promise.allSettled(
event.Records.map(async (record: SQSRecord) => {
try {
await processSQSMessage(record);
logger.info({
msg: "Message processed successfully",
messageId: record.messageId,
});
return { messageId: record.messageId, status: "success" };
} catch (error) {
logger.error({
msg: "Message processing failed",
messageId: record.messageId,
error: error instanceof Error ? error.message : String(error),
});
// 失敗したメッセージのIDを記録
batchItemFailures.push({
itemIdentifier: record.messageId,
});
throw error;
}
}),
);
const successCount = results.filter(
(r) => r.status === "fulfilled",
).length;
const failureCount = results.filter(
(r) => r.status === "rejected",
).length;
logger.info({
msg: "Processing complete",
successCount,
failureCount,
totalCount: event.Records.length,
});
if (batchItemFailures.length > 0) {
logger.warn({
msg: "Returning failed messages",
failedCount: batchItemFailures.length,
failedMessageIds: batchItemFailures.map((f) => f.itemIdentifier),
});
}
// batchItemFailuresを返す(空の配列でも可)
// Lambda Web Adapterがこのレスポンスボディを使って
// Lambdaのレスポンスを構築します
const response: SQSBatchResponse = {
batchItemFailures,
};
// 部分的な失敗でも200を返す
return json(response, { status: 200 });
} catch (error) {
logger.error({
msg: "Critical error processing SQS event",
error: error instanceof Error ? error.message : String(error),
stack: error instanceof Error ? error.stack : undefined,
});
// クリティカルエラーの場合は全メッセージを失敗として扱う
return json(
{
status: "error",
message: error instanceof Error ? error.message : "Unknown error",
},
{ status: 500 },
);
}
},
},
},
});この実装のポイントは以下の通りです。
Promise.allSettledで各メッセージを並列処理- 失敗したメッセージのIDを
batchItemFailures配列に追加 - 部分的な失敗でもステータスコード200を返す
- レスポンスボディに
batchItemFailuresを含める
7. はまりポイント:レスポンスストリーミング
7-1. レスポンスストリーミングをオフにする
部分的なバッチレスポンスを使用する場合、Lambda Web Adapterのレスポンスストリーミングオプションはオフにする必要があります。
デフォルトではオフになっていますが、Dockerfileや環境変数で以下の設定になっていないか確認してください。
# この設定は避ける
AWS_LWA_INVOKE_MODE=response_stream7-2. なぜオフにする必要があるのか?
おそらく、内部的にチャンク化されたレスポンスがLWAからLambdaに返されており、AWSがこれを正しく処理できないためと考えられます。
レスポンスストリーミングモードがオンの場合、以下のような問題が発生する可能性があります。
batchItemFailuresが正しくパースされない- 部分的なバッチレスポンスが機能しない
- 予期しないエラーが発生する
7-3. オフにすることの影響
部分的なバッチレスポンスためにレスポンスストリーミングをオフにする必要がある点で、Lambda Web Adapterで非HTTPイベントを処理するのは非現実的な選択肢だな・・・と感じました。
最近のフロントエンドフレームワークはレスポンスストリーミングを前提にしていることが多く、レスポンスストリーミングをオフにすると、せっかくの機能や性能を活かせなくなってしまいます。
8. Lambda Web Adapterで非HTTPイベントを扱うメリットとデメリット
8-1. メリット
- 既存のWebフレームワークの知識が活用できる
- ミドルウェアが使える
- テストがしやすい
8-2. デメリット
- Lambda固有の機能が使いにくい
- 部分的なバッチレスポンスためにレスポンスストリーミングをオフにする必要がある
- 非HTTPイベントのルーティングは1個しか設定できない。
AWS_LWA_PASS_THROUGH_PATHで/events以外のパスでも処理できますが、あくまで1つ固定です。- つまり、SQSやS3などの複数のイベントソースと統合する場合、/eventsの中で処理を分岐する必要があります。
- 設定の注意点が多い
さいごに
本記事では、Lambda Web Adapterを使って非HTTPイベント(SQS)をWebアプリで処理する方法を紹介しました。
本番で使うのは微妙かもしれませんが、一つのWebアプリ、一つのLambdaで、画面・APIだけでなく、イベント処理までを賄えるのは面白いですね。
PoCとかでは有用かもしれないです。