AWS EmulatorでSQSからLambdaを動かす方法
AWS Emulator でも、SQS のキューと Lambda 関数をイベントソースマッピングでつなぐと、キューに送ったメッセージで関数が動きます。キューを使った非同期処理(注文の受け付け、画像の後処理など)を、AWS のアカウントなしでローカル環境や CI で確かめたいときの手順です。つなぎ方に加えて、関数が失敗したときにメッセージがキューに戻る様子と、ReportBatchItemFailures で失敗した分だけを戻す設定も、検証環境で実行したコマンドと出力を、そのまま載せます(長い出力は一部を省きます)。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.487(2026年11月17日リリース、Debian パッケージ)、AWS CLI 2.40.4 です。AWS のアカウントと認証情報は使っていません。本物の AWS Lambda と Amazon SQS での動き、料金、待ち時間や同時実行数の増え方は確かめておらず、記事で触れるところは公式ドキュメントを出どころにしています。FIFO キュー、デッドレターキュー、フィルター、最大同時実行数の設定、Python 以外のランタイムは試していません。

エミュレーターを起動して、AWS CLI を向ける
AWS Emulator は、公式ガイドにある Linux での入れ方のとおりに Debian パッケージで入れました。1つ目の端末で aws-emulator -t off を実行して起動します。-t off は、使用状況のデータ(テレメトリー)を送らない指定です。
2つ目の端末で、AWS CLI の接続先をエミュレーターに向ける環境変数を設定します。AWS_PAGER は、出力をページャーで開かずにそのまま表示するために足しました。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
export AWS_PAGER=""
関数とキューを用意する
まず、Lambda が引き受けられる実行ロールを作ります。信頼ポリシーを trust.json に書きました。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Service": "lambda.amazonaws.com" },
"Action": "sts:AssumeRole"
}
]
}
$ aws iam create-role --role-name example-sqs-role --assume-role-policy-document file://trust.json --query Role.Arn --output text
arn:aws:iam::<12桁のアカウントID>:role/example-sqs-role
出力の中のアカウントIDは、<12桁のアカウントID> に置き換えています。
関数のコードは fn/lambda_function.py に書きました。受け取ったメッセージの本文と受信回数(ApproximateReceiveCount)をログに出します。あとで失敗のときの動きを見るために、本文が boom で始まるメッセージを1回目に受け取ったときは例外を出し、bad で始まるものは1回目だけ失敗として batchItemFailures に入れて返します。2回目は成功させて、再配信がいつまでも続かないようにしています。
import json
def lambda_handler(event, context):
records = event["Records"]
print(f"records={len(records)}")
failures = []
for r in records:
body = r["body"]
count = r["attributes"]["ApproximateReceiveCount"]
print(f"body={body} receiveCount={count}")
if body == "hello":
print(json.dumps(event))
# 1回目に受け取ったときだけ失敗させる(2回目は成功させて、繰り返しを止める)
if count == "1" and body.startswith("boom"):
raise RuntimeError(f"failed: {body}")
if count == "1" and body.startswith("bad"):
failures.append({"itemIdentifier": r["messageId"]})
return {"batchItemFailures": failures}
zip にまとめて関数を作ります。タイムアウトは 10 秒にしました。
$ zip -j function.zip fn/lambda_function.py
adding: lambda_function.py (deflated 40%)
$ aws lambda create-function --function-name example-consumer --runtime python3.12 --handler lambda_function.lambda_handler --role arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/example-sqs-role --zip-file fileb://function.zip --timeout 10 --query '{State:State,Timeout:Timeout}'
{
"State": "Pending",
"Timeout": 10
}
$ aws lambda wait function-active-v2 --function-name example-consumer
キューは、可視性タイムアウト(受け取ったメッセージをほかから見えなくしておく時間)を 15 秒にして作りました。既定の 30 秒のままだと、失敗したメッセージが戻るのを待つ時間が長くなるためです。
$ aws sqs create-queue --queue-name example-queue --attributes VisibilityTimeout=15
{
"QueueUrl": "https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue"
}
ロールに SQS の権限がないと、マッピングを作れない
キューと関数をつなぐのが、イベントソースマッピングです。Lambda と SQS の説明によると、Lambda がキューを読み、メッセージをまとめた1つのイベントで関数を同期的に呼び、成功したらメッセージをキューから消します。
ロールに何も付けないまま create-event-source-mapping を実行すると、エミュレーターは次のエラーを返しました。
$ aws lambda create-event-source-mapping --function-name example-consumer --event-source-arn arn:aws:sqs:us-east-1:$(aws sts get-caller-identity --query Account --output text):example-queue --batch-size 10 --maximum-batching-window-in-seconds 2
aws: [ERROR]: An error occurred (InvalidParameterValueException) when calling the CreateEventSourceMapping operation: The function execution role does not have permissions to call ReceiveMessage on SQS
(以下は省略)
マッピングの設定の説明のとおり、AWS 管理ポリシー AWSLambdaSQSQueueExecutionRole を実行ロールに付けます。このポリシーの中身は、SQS の ReceiveMessage、DeleteMessage、GetQueueAttributes と、CloudWatch Logs への書き込みの許可です。付けたあとは、同じコマンドでマッピングを作れました。
$ aws iam attach-role-policy --role-name example-sqs-role --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaSQSQueueExecutionRole
$ aws lambda create-event-source-mapping --function-name example-consumer --event-source-arn arn:aws:sqs:us-east-1:$(aws sts get-caller-identity --query Account --output text):example-queue --batch-size 10 --maximum-batching-window-in-seconds 2
{
"UUID": "e49214ac-62ed-41b4-8e56-1638dacd3dcd",
"BatchSize": 10,
"MaximumBatchingWindowInSeconds": 2,
(中略)
"State": "Creating",
"StateTransitionReason": "USER_INITIATED",
"FunctionResponseTypes": [],
(以下は省略)
}
--batch-size 10 は、1回の呼び出しで渡すメッセージの上限です。--maximum-batching-window-in-seconds 2 は、呼び出す前にメッセージを集めて待つ最大の秒数で、まとめて送ったメッセージが1回の呼び出しに入るように付けました。CreateEventSourceMapping の API リファレンスでは、SQS のときの既定値は、バッチサイズが 10、待つ時間が 0 秒です。
返ってきた直後の State は Creating でした。get-event-source-mapping で1秒ごとに確かめると、1回目で Enabled になっていました。
エミュレーターは IAM のポリシーを AWS と同じようには判定しません。ここで権限のエラーが出たからといって、本物の AWS で同じロールが通るかどうかの確認にはなりません。
メッセージを送ると、関数が呼ばれる
メッセージを1件送り、8秒待ってから関数のログを CloudWatch Logs から読みました。--start-time には、送る直前の時刻をミリ秒で表した値(date +%s000 の出力)を渡しています。
$ aws sqs send-message --queue-url https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue --message-body hello
{
"MD5OfMessageBody": "5d41402abc4b2a76b9719d911017c592",
"MessageId": "0992b2c9-a985-45ee-9f03-f9b19893afe6"
}
$ aws logs filter-log-events --log-group-name /aws/lambda/example-consumer --start-time 1794906126000 --query 'events[].message' --output text | tr '\t' '\n' | grep -v '^{'
START RequestId: 549151ad-57d9-45ae-ae91-a9749eb5d7e3 Version: $LATEST
records=1
body=hello receiveCount=1
END RequestId: 549151ad-57d9-45ae-ae91-a9749eb5d7e3
(以下は省略)
関数が受け取ったイベントは次のとおりです。receiptHandle は長いので後半を省きました。Records の配列に、メッセージ ID、本文、受信回数などが入っています。公式ドキュメントにあるイベントの例と同じ項目が並んでいました。
{
"Records": [
{
"messageId": "0992b2c9-a985-45ee-9f03-f9b19893afe6",
"receiptHandle": "MzBjMTJlYzMtOTEy...",
"body": "hello",
"attributes": {
"ApproximateFirstReceiveTimestamp": "1794906127120",
"ApproximateReceiveCount": "1",
"SenderId": "AIDAH5I7GEMO7ADXNFAZU",
"SentTimestamp": "1794906126903"
},
"messageAttributes": {},
"md5OfBody": "5d41402abc4b2a76b9719d911017c592",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-queue",
"awsRegion": "us-east-1"
}
]
}
関数が正常に終わったあと、キューのメッセージ数(ApproximateNumberOfMessages と ApproximateNumberOfMessagesNotVisible)はどちらも 0 でした。成功したメッセージは、マッピングがキューから消しています。
関数が例外を出すと、成功した分もキューに戻る
3件を send-message-batch でまとめて送りました。2件目の boom2 で関数が例外を出します。
$ aws sqs send-message-batch --queue-url https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue --entries Id=1,MessageBody=ok1 Id=2,MessageBody=boom2 Id=3,MessageBody=ok3 --query 'length(Successful)'
3
6秒後の時点で、3件とも見えない状態(ApproximateNumberOfMessagesNotVisible が 3)でした。可視性タイムアウトの 15 秒が過ぎるのを待ってからログを読むと、3件をまとめた呼び出しが2回あり、2回目は3件とも受信回数が 2 でした。1回目で ok1 は処理を終えていましたが、キューに戻って、もう一度届いています。
$ aws logs filter-log-events --log-group-name /aws/lambda/example-consumer --start-time 1794906137000 --query 'events[].message' --output text | tr '\t' '\n' | grep -E '^(records|body)'
records=3
body=ok1 receiveCount=1
body=boom2 receiveCount=1
records=3
body=ok1 receiveCount=2
body=boom2 receiveCount=2
body=ok3 receiveCount=2
SQS のエラー処理の説明にも、関数がバッチの処理中にエラーになると、うまく処理できたものも含めてバッチのすべてのメッセージが再び見えるようになる、と書かれています。同じメッセージが2回以上届くことがあるので、Lambda と SQS の説明にある警告では、関数を同じメッセージで何度呼ばれても困らない作り(冪等)にするよう勧めています。
ReportBatchItemFailures で、失敗した分だけを戻す
失敗したメッセージだけをキューに戻すには、マッピングに ReportBatchItemFailures を設定し、関数の戻り値の batchItemFailures に、失敗したメッセージの messageId を itemIdentifier として入れます。
先に、設定がないまま batchItemFailures を返したときを試しました。ok4 と bad5 を送ると、関数は bad5 を失敗として返しましたが、25秒待っても呼び出しは1回だけで、キューは空でした。
$ aws sqs send-message-batch --queue-url https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue --entries Id=1,MessageBody=ok4 Id=2,MessageBody=bad5 --query 'length(Successful)'
2
$ aws logs filter-log-events --log-group-name /aws/lambda/example-consumer --start-time 1794906168000 --query 'events[].message' --output text | tr '\t' '\n' | grep -E '^(records|body)'
records=2
body=ok4 receiveCount=1
body=bad5 receiveCount=1
$ aws sqs get-queue-attributes --queue-url https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessagesNotVisible": "0",
"ApproximateNumberOfMessages": "0"
}
}
検証環境(AWS Emulator)では、マッピングに ReportBatchItemFailures がないと、batchItemFailures で失敗を返した bad5 もキューから消えました。関数のコードとマッピングの設定の両方をそろえて使います。
次に、既存のマッピングを update-event-source-mapping で更新しました。
$ aws lambda update-event-source-mapping --uuid e49214ac-62ed-41b4-8e56-1638dacd3dcd --function-response-types ReportBatchItemFailures --query '{State:State,FunctionResponseTypes:FunctionResponseTypes}'
{
"State": "Updating",
"FunctionResponseTypes": [
"ReportBatchItemFailures"
]
}
State が Enabled に戻ってから、ok6、bad7、ok8 を送りました。6秒後に見えない状態のメッセージは1件だけで、15 秒が過ぎたあとのログでは、2回目の呼び出しに入っていたのは bad7 だけでした。
$ aws logs filter-log-events --log-group-name /aws/lambda/example-consumer --start-time 1794906197000 --query 'events[].message' --output text | tr '\t' '\n' | grep -E '^(records|body)'
records=3
body=ok6 receiveCount=1
body=bad7 receiveCount=1
body=ok8 receiveCount=1
records=1
body=bad7 receiveCount=2
可視性タイムアウトが関数のタイムアウトより短いと、作れない
可視性タイムアウトを 5 秒にしたキュー example-short を作り、タイムアウトが 10 秒の関数とつなごうとすると、エラーになりました。
$ aws sqs create-queue --queue-name example-short --attributes VisibilityTimeout=5 --query QueueUrl --output text
https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-short
$ aws lambda create-event-source-mapping --function-name example-consumer --event-source-arn arn:aws:sqs:us-east-1:$(aws sts get-caller-identity --query Account --output text):example-short
aws: [ERROR]: An error occurred (InvalidParameterValueException) when calling the CreateEventSourceMapping operation: Queue visibility timeout: 5 seconds is less than Function timeout: 10 seconds
(以下は省略)
マッピングの設定の説明でも、関数のタイムアウトはキューの可視性タイムアウト以下でなければならず、マッピングを作るときや更新するときに確かめられる、とされています。同じページでは、可視性タイムアウトを関数のタイムアウトの6倍以上にすることを勧めています。この記事のキューは、再配信を早く見るために 15 秒にしています。
マッピングを止めると、メッセージはキューに残る
--no-enabled でマッピングを止めると、State は Updating を経て Disabled になりました。その間に送ったメッセージは、10秒待ってもキューに残ったまま(ApproximateNumberOfMessages が 1)で、関数のログも出ませんでした。--enabled で再開すると、残っていたメッセージで関数が呼ばれ、キューは空になりました。
$ aws lambda update-event-source-mapping --uuid e49214ac-62ed-41b4-8e56-1638dacd3dcd --enabled --query State
"Updating"
$ aws logs filter-log-events --log-group-name /aws/lambda/example-consumer --start-time 1794906231000 --query 'events[].message' --output text | tr '\t' '\n' | grep -E '^(records|body)'
records=1
body=while-disabled receiveCount=1
CreateEventSourceMapping の API リファレンスでも、Enabled を false にすると、Lambda はキューの読み取りと関数の呼び出しを止める、と説明されています。設定を残したまま呼び出しだけを一時的に止めたいときは、マッピングを消さずに --no-enabled で止められます。
後片付け
マッピング、関数、キューの順に消します。マッピングは delete-event-source-mapping で State が Deleting になり、3秒後の一覧では空でした。
$ aws lambda delete-event-source-mapping --uuid e49214ac-62ed-41b4-8e56-1638dacd3dcd --query State
"Deleting"
$ aws lambda list-event-source-mappings --function-name example-consumer
{
"EventSourceMappings": []
}
$ aws lambda delete-function --function-name example-consumer
{
"StatusCode": 204
}
$ aws sqs delete-queue --queue-url https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue; aws sqs delete-queue --queue-url $(aws sqs get-queue-url --queue-name example-short --query QueueUrl --output text); aws sqs list-queues
キューを消したあとの list-queues は、何も表示しませんでした。
エミュレーターは作ったリソースをメモリーに置き、止めると消します。テストのたびに空の状態から始めたいときは、エミュレーターを起動し直すだけでも片付きます。





