KMSに続いて、AWS EmulatorでSQSを試したので、仕組みと使い方を残しておきます。
エミュレーターの起動方法とAWS CLIのつなぎ方は、以下の記事に書いています。
AWS EmulatorをWindowsのDockerで動かす(S3をオフラインで試す)
KMSの記事はこちら
AWS KMSの仕組みと使い方をAWS Emulatorで試す
SQSとは
Amazon SQS(Simple Queue Service)は、メッセージを一時的に預かっておくキューのサービスです。
送る側がキューにメッセージを入れて、受け取る側があとからキューに取りに行きます。

送る側と受け取る側が直接やり取りしないので、受け取る側が止まっていてもメッセージはキューに残ります。
公式ドキュメントでは、アップロードされた画像や動画の変換をバックグラウンドで処理する、という例が挙がっていました。
受け取っただけでは、メッセージは消えません。処理が終わったら、受け取る側が自分で削除します
削除しなかったメッセージは、保持期間が過ぎると自動で消えます。初期設定は4日で、1分から14日の間で変えられます。
キューの種類
キューには標準キューとFIFOキューの2種類があります。
| 標準キュー | FIFOキュー | |
|---|---|---|
| 届く順番 | だいたい送った順(保証はない) | 同じグループの中では送った順 |
| 重複 | 同じメッセージが2回以上届くことがある | 重複しない |
| 処理できる量 | ほぼ無制限 | APIごとに1秒300回まで(増やす設定あり) |
| 料金(100万リクエストあたり) | 0.40ドル | 0.50ドル |
標準キューでは、届く順番が前後したり、同じメッセージが2回届いたりすることがあります。なので、同じメッセージを2回処理しても問題ないように作っておく必要があります。
順番が大事なときや、重複すると困るときはFIFOキューを使います。
料金はリクエストの数で決まり、毎月100万リクエストまでは無料です。表は米国東部(バージニア北部)の料金で、東京リージョンも同じでした(2026年11月時点)。
1回のリクエストで送れるのは1MiBまでで、64KBごとに1リクエストとして数えられます。1MiBのメッセージを送ると16リクエスト分です。
今回もエミュレーターなので、料金はかかりません。
試した環境
- Windows 11
- AWS Emulator 1.0.338(Docker)
- AWS CLI 2.40.2
AWS CLIの環境変数は、前回の記事と同じものを設定しています。
キューを作る
以下のコマンドでキューを作ります。
$q = aws sqs create-queue --queue-name blog-queue --query QueueUrl --output text
$q
https://sqs.us-east-1.amazonaws.com/000000000000/blog-queue
SQSではキューをURLで指定するので、変数に入れておきます。
本物のAWSと同じ形のURLが返ってきますが、環境変数の AWS_ENDPOINT_URL でエミュレーターを指定しているので、AWS CLIはエミュレーターに接続します。
キューの設定を見てみます。
aws sqs get-queue-attributes --queue-url $q --attribute-names All
{
"Attributes": {
"ApproximateNumberOfMessagesDelayed": "0",
"ReceiveMessageWaitTimeSeconds": "0",
"ApproximateNumberOfMessages": "0",
"ApproximateNumberOfMessagesNotVisible": "0",
"CreatedTimestamp": "1794846804",
"MessageRetentionPeriod": "345600",
"MaximumMessageSize": "1048576",
"LastModifiedTimestamp": "1794846804",
"QueueArn": "arn:aws:sqs:us-east-1:000000000000:blog-queue",
"VisibilityTimeout": "30",
"SqsManagedSseEnabled": "true",
"DelaySeconds": "0"
}
}
主な設定は以下です。
| 属性 | 値 | 意味 |
|---|---|---|
VisibilityTimeout |
30 | 可視性タイムアウト(秒)。あとで試します |
MessageRetentionPeriod |
345600 | メッセージの保持期間(秒)。4日 |
MaximumMessageSize |
1048576 | メッセージの最大サイズ(バイト)。1MiB |
ReceiveMessageWaitTimeSeconds |
0 | 受信するときに待つ時間(秒)。ロングポーリングのところで試します |
SqsManagedSseEnabled |
true | SQSが管理する鍵で暗号化する設定 |
メッセージを送る
aws sqs send-message --queue-url $q --message-body "hello sqs"
{
"MD5OfMessageBody": "3b7bef57d06c0021d0aafe8f6d587241",
"MessageId": "6c8bc83d-f21b-493e-8aa2-680c9c3481dd"
}
MessageId が送ったメッセージのIDです。
メッセージを受け取る
aws sqs receive-message --queue-url $q --message-system-attribute-names ApproximateReceiveCount
{
"Messages": [
{
"MessageId": "6c8bc83d-f21b-493e-8aa2-680c9c3481dd",
"ReceiptHandle": "MzZhNzQxZmYtMWQ1OC00NWU1LThlN2YtODc0OTY4NGYyZGE4IDRlYzkwNWRmLTgwM2YtNGRjZC05YzFkLTYxMDI3MThiYjlkOSBhcm46YXdzOnNxczp1cy1lYXN0LTE6MDAwMDAwMDAwMDAwOmJsb2ctcXVldWU=",
"MD5OfBody": "3b7bef57d06c0021d0aafe8f6d587241",
"Body": "hello sqs",
"Attributes": {
"ApproximateReceiveCount": "1"
}
}
]
}
Body が送った本文です。ApproximateReceiveCount はこのメッセージを受信した回数で、1回目なので1になっています。
ReceiptHandle は、あとでメッセージを削除するときに使う値です。同じメッセージでも、受信するたびに変わります。
受け取ったメッセージはしばらく見えなくなる
続けてもう一度受信すると、何も表示されませんでした。
aws sqs receive-message --queue-url $q
aws sqs get-queue-attributes --queue-url $q --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessages": "0",
"ApproximateNumberOfMessagesNotVisible": "1"
}
}
ApproximateNumberOfMessagesNotVisible が1になっています。メッセージは消えたわけではなく、キューに残ったまま見えなくなっています。
これが可視性タイムアウトです。受信したメッセージは、一定の時間ほかの受信には返されなくなります。初期設定は30秒です。

受け取る側が処理している間に、別の受け取る側が同じメッセージを処理してしまわないための仕組みです。
30秒待ってから受信すると、同じメッセージがまた返ってきました。
Start-Sleep 30
$m = aws sqs receive-message --queue-url $q --message-system-attribute-names ApproximateReceiveCount | ConvertFrom-Json
$m.Messages[0].MessageId
$m.Messages[0].Attributes.ApproximateReceiveCount
6c8bc83d-f21b-493e-8aa2-680c9c3481dd
2
MessageId が同じで、受信回数が2になっています。
受け取る側が処理の途中で落ちても、時間がたてばメッセージがキューに戻ってくるので、ほかの受け取る側がやり直せます。
可視性タイムアウトは最大12時間まで設定できます。受信するときに --visibility-timeout を付けると、その受信で受け取ったメッセージだけ時間を変えることもできます。
ただし標準キューでは、可視性タイムアウトの間に同じメッセージが2回届かないことまでは保証されていないそうです。
処理が終わったら削除する
処理が終わったら、ReceiptHandle を指定してメッセージを削除します。
aws sqs delete-message --queue-url $q --receipt-handle $m.Messages[0].ReceiptHandle
aws sqs get-queue-attributes --queue-url $q --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessages": "0",
"ApproximateNumberOfMessagesNotVisible": "0"
}
}
delete-message は成功しても何も表示されません。
削除には、最後に受信したときの ReceiptHandle を使います。古い ReceiptHandle を使うと、コマンドは成功してもメッセージが消えないことがあるそうです。
ロングポーリング
receive-message は、メッセージがなければすぐに空で返ってきます。これをショートポーリングといいます。
ショートポーリングは一部のサーバーだけを見に行くので、キューにメッセージがあっても返ってこないことがあるそうです。
--wait-time-seconds を付けると、メッセージが届くまで最大20秒待ってくれます。これがロングポーリングです。
空のキューで試すと、約20秒待ってから返ってきました。
(Measure-Command { aws sqs receive-message --queue-url $q --wait-time-seconds 20 }).TotalSeconds
20.886691
待っている間にメッセージが届いたらどうなるか、PowerShellを2つ開いて試しました。2つ目のPowerShellにも、環境変数と $q を同じように設定しておきます。
1つ目のPowerShellで受信を待ちます。
Get-Date -Format HH:mm:ss.fff
$m = aws sqs receive-message --queue-url $q --wait-time-seconds 20 | ConvertFrom-Json
Get-Date -Format HH:mm:ss.fff
$m.Messages[0].Body
aws sqs delete-message --queue-url $q --receipt-handle $m.Messages[0].ReceiptHandle
待っている間に、2つ目のPowerShellからメッセージを送ります。
aws sqs send-message --queue-url $q --message-body "late message" --query MessageId --output text
Get-Date -Format HH:mm:ss.fff
1つ目のPowerShellの結果です。
01:34:27.671
01:34:40.385
late message
2つ目のPowerShellの結果です。
8bca8e2e-ff80-46d2-aa66-51ae791eb015
01:34:40.438
送信のコマンドが終わる(40.438秒)より前に、受信が返ってきています。20秒待ち切らずに、メッセージが届いた時点で返ってきました。
待てるのは20秒までで、21を指定するとエラーになりました。
aws: [ERROR]: An error occurred (InvalidParameterValue) when calling the ReceiveMessage operation: Value 21 for parameter WaitTimeSeconds is invalid. Reason: Must be >= 0 and <= 20, if provided.
キューの ReceiveMessageWaitTimeSeconds を設定しておけば、毎回 --wait-time-seconds を付けなくてもロングポーリングになります。
空の返事が減るぶんリクエストの数も減るので、料金も下がる、と公式ドキュメントに書かれていました。
デッドレターキュー
処理に失敗し続けるメッセージは、削除されないので、可視性タイムアウトが過ぎるたびにキューに戻ってきます。このままだと、受信して失敗するのをずっと繰り返すことになります。
そこで、決まった回数受信されたメッセージを、別のキューに移す設定があります。移す先のキューをデッドレターキュー(DLQ)といいます。

元のキュー(work-queue)と、デッドレターキュー(work-dlq)を作ります。
$wq = aws sqs create-queue --queue-name work-queue --query QueueUrl --output text
$dlq = aws sqs create-queue --queue-name work-dlq --query QueueUrl --output text
$dlqArn = aws sqs get-queue-attributes --queue-url $dlq --attribute-names QueueArn --query Attributes.QueueArn --output text
$dlqArn
arn:aws:sqs:us-east-1:000000000000:work-dlq
元のキューに RedrivePolicy を設定します。maxReceiveCount は、デッドレターキューに移すまでに受信できる回数です。
RedrivePolicy はJSONの中にJSONを文字列で入れる形でややこしいので、PowerShellで組み立ててファイルに書き出しています。
$redrive = @{ deadLetterTargetArn = $dlqArn; maxReceiveCount = "3" } | ConvertTo-Json -Compress
@{ RedrivePolicy = $redrive } | ConvertTo-Json | Out-File -Encoding ascii redrive.json
aws sqs set-queue-attributes --queue-url $wq --attributes file://redrive.json
aws sqs get-queue-attributes --queue-url $wq --attribute-names RedrivePolicy
{
"Attributes": {
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:000000000000:work-dlq\",\"maxReceiveCount\":3}"
}
}
処理に失敗する想定のメッセージを送って、削除しないまま受信を4回繰り返します。毎回30秒待つのは長いので、--visibility-timeout 2 で2秒後にキューに戻るようにしています。
aws sqs send-message --queue-url $wq --message-body "broken job" --query MessageId --output text
foreach ($i in 1..4) {
aws sqs receive-message --queue-url $wq --visibility-timeout 2 --message-system-attribute-names ApproximateReceiveCount --query "Messages[0].[Body,Attributes.ApproximateReceiveCount]" --output text
Start-Sleep 3
}
e29105c4-7d51-4f4b-98e3-bbbed665b19c
broken job 1
broken job 2
broken job 3
None
3回目までは受信できて、4回目は何も返ってきませんでした(None は --query で何も取れなかったときの表示です)。
デッドレターキューから受信すると、メッセージが移っていました。
aws sqs receive-message --queue-url $dlq --visibility-timeout 0 --message-system-attribute-names DeadLetterQueueSourceArn
{
"Messages": [
{
"MessageId": "e29105c4-7d51-4f4b-98e3-bbbed665b19c",
"ReceiptHandle": "YTkyY2QyNTYtYjEwZC00Zjc5LWE2NzYtZmYwYTliM2I5M2NjIDZhNjdjYTM5LTg5NTEtNDI2Mi1iOTE5LTBlZTQ0YWNkYzBkZiBhcm46YXdzOnNxczp1cy1lYXN0LTE6MDAwMDAwMDAwMDAwOndvcmstZGxx",
"MD5OfBody": "de04771a32582ef7b78162a05c2bb7fd",
"Body": "broken job",
"Attributes": {
"DeadLetterQueueSourceArn": "arn:aws:sqs:us-east-1:000000000000:work-queue"
}
}
]
}
DeadLetterQueueSourceArn に、どのキューから移ってきたかが入っています。
--visibility-timeout 0 は、受信したあとすぐに見える状態に戻すための指定です。このあとメッセージを元のキューに戻すので付けました。
原因を直したら、start-message-move-task でデッドレターキューのメッセージを元のキューに戻せます。--destination-arn を指定しなければ、元のキューに戻ります。
aws sqs start-message-move-task --source-arn $dlqArn
Start-Sleep 3
aws sqs list-message-move-tasks --source-arn $dlqArn --query "Results[0].[Status,ApproximateNumberOfMessagesMoved]" --output text
aws sqs receive-message --queue-url $wq --query "Messages[0].Body" --output text
{
"TaskHandle": "eyJ0YXNrSWQiOiI3ZTM4MmI2Yy03YTdjLTQ1YTQtYTY2MS04Nzc5OWJkY2UwZjAiLCJzb3VyY2VBcm4iOiJhcm46YXdzOnNxczp1cy1lYXN0LTE6MDAwMDAwMDAwMDAwOndvcmstZGxxIn0="
}
COMPLETED 1
broken job
1件移動して、元のキューから受信できるようになりました。
ちなみに、デッドレターキューの保持期間は元のキューより長くしておくのがおすすめだそうです。標準キューでは、デッドレターキューに移ったあとも、最初に送られた時刻から保持期間を数えるためです。
FIFOキュー
FIFOキューは、名前の最後を .fifo にする決まりがあります。付けないとエラーになります。
aws sqs create-queue --queue-name orders --attributes FifoQueue=true
aws: [ERROR]: An error occurred (InvalidParameterValue) when calling the CreateQueue operation: The name of a FIFO queue can only include alphanumeric characters, hyphens, or underscores, must end with .fifo suffix and be 1 to 80 in length.
.fifo を付けて作り直します。
$f = aws sqs create-queue --queue-name orders.fifo --attributes FifoQueue=true --query QueueUrl --output text
FIFOキューに送るときは、メッセージグループIDが必要です。
aws sqs send-message --queue-url $f --message-body A-1
aws: [ERROR]: An error occurred (MissingParameter) when calling the SendMessage operation: The request must contain the parameter MessageGroupId.
グループIDを付けても、まだエラーになりました。重複を見分けるための重複排除IDも必要です。
aws sqs send-message --queue-url $f --message-body A-1 --message-group-id user-a
aws: [ERROR]: An error occurred (InvalidParameterValue) when calling the SendMessage operation: The queue should either have ContentBasedDeduplication enabled or MessageDeduplicationId provided explicitly
エラーにあるとおり、キューのコンテンツベースの重複排除を有効にしておけば、重複排除IDは省略できます(後で試します)。
user-a のグループに3つ、user-b のグループに1つ送ります。
aws sqs send-message --queue-url $f --message-body "A-1" --message-group-id user-a --message-deduplication-id a1 --query MessageId --output text
aws sqs send-message --queue-url $f --message-body "A-2" --message-group-id user-a --message-deduplication-id a2 --query MessageId --output text
aws sqs send-message --queue-url $f --message-body "A-3" --message-group-id user-a --message-deduplication-id a3 --query MessageId --output text
aws sqs send-message --queue-url $f --message-body "B-1" --message-group-id user-b --message-deduplication-id b1 --query MessageId --output text
784d6c39-6387-4071-9cc0-2685a6ce0387
8483aebb-cbc0-4d63-a0a0-64c40505f02b
f1bdfc0c-08ed-480f-9487-dd504c9fec5f
fc742eb9-3250-4e7a-8d8d-cfd67c37ac6d
重複したメッセージは入らない
a1 と同じ重複排除IDで、もう一度送ってみます。
aws sqs send-message --queue-url $f --message-body "A-1" --message-group-id user-a --message-deduplication-id a1 --query MessageId --output text
aws sqs get-queue-attributes --queue-url $f --attribute-names ApproximateNumberOfMessages
784d6c39-6387-4071-9cc0-2685a6ce0387
{
"Attributes": {
"ApproximateNumberOfMessages": "4"
}
}
1回目と同じ MessageId が返ってきて、キューのメッセージは4つのままでした。
同じ重複排除IDのメッセージは、5分の間は重複として扱われます。送信がタイムアウトして送り直したときに、同じメッセージが2つ入らないようにするためのものです。
グループの中は順番どおり
1つずつ受信してみます。
$m1 = aws sqs receive-message --queue-url $f | ConvertFrom-Json
$m1.Messages[0].Body
$m2 = aws sqs receive-message --queue-url $f | ConvertFrom-Json
$m2.Messages[0].Body
aws sqs receive-message --queue-url $f
A-1
B-1
1回目は A-1、2回目は A-2 ではなく B-1 が返ってきました。3回目は何も返ってきません。

同じグループのメッセージは順番に処理されるので、A-1 が処理中(受信して、まだ削除していない状態)の間は A-2 が返ってきません。別のグループの B-1 は関係なく受信できます。
A-1 を削除すると、A-2 が返ってきました。
aws sqs delete-message --queue-url $f --receipt-handle $m1.Messages[0].ReceiptHandle
$m4 = aws sqs receive-message --queue-url $f | ConvertFrom-Json
$m4.Messages[0].Body
A-2
ユーザーごとや注文ごとにグループを分けておけば、グループの中の順番を守りながら、グループ同士は並行して処理できます。
本文で重複を判定する
ContentBasedDeduplication=true を付けて作ったキューでは、本文のSHA-256ハッシュが重複排除IDの代わりになります。
$f2 = aws sqs create-queue --queue-name orders2.fifo --attributes FifoQueue=true,ContentBasedDeduplication=true --query QueueUrl --output text
aws sqs send-message --queue-url $f2 --message-body "same body" --message-group-id g --query MessageId --output text
aws sqs send-message --queue-url $f2 --message-body "same body" --message-group-id g --query MessageId --output text
aws sqs get-queue-attributes --queue-url $f2 --attribute-names ApproximateNumberOfMessages --query Attributes.ApproximateNumberOfMessages --output text
a0227a40-1ba5-4885-96ff-a3c6ca2624c1
a0227a40-1ba5-4885-96ff-a3c6ca2624c1
1
同じ本文を2回送っても、キューに入ったのは1つだけでした。
S3にファイルが置かれたらSQSに通知する
前回までの記事でS3を使ったので、組み合わせてみます。S3のバケットにファイルが置かれたら、SQSにメッセージが届くようにします。
通知を受けるキューとバケットを作ります。
$n = aws sqs create-queue --queue-name upload-events --query QueueUrl --output text
$nArn = aws sqs get-queue-attributes --queue-url $n --attribute-names QueueArn --query Attributes.QueueArn --output text
aws s3 mb s3://sqs-test-bucket
通知の設定ファイルを作って、バケットに設定します。s3:ObjectCreated:* は、ファイルが作られたとき全部、という意味です。
@"
{
"QueueConfigurations": [
{ "QueueArn": "$nArn", "Events": ["s3:ObjectCreated:*"] }
]
}
"@ | Out-File -Encoding ascii notification.json
aws s3api put-bucket-notification-configuration --bucket sqs-test-bucket --notification-configuration file://notification.json
aws: [ERROR]: An error occurred (InvalidArgument) when calling the PutBucketNotificationConfiguration operation: Unable to validate the following destination configurations
エラーになりました。キューの側で、S3からのメッセージを受け付ける設定(キューポリシー)をしていないのが原因です。
キューポリシーを設定します。S3のドキュメントの例に合わせて、sqs-test-bucket からの送信だけを許可しています。
$policy = @"
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Service": "s3.amazonaws.com" },
"Action": "sqs:SendMessage",
"Resource": "$nArn",
"Condition": {
"ArnLike": { "aws:SourceArn": "arn:aws:s3:::sqs-test-bucket" },
"StringEquals": { "aws:SourceAccount": "000000000000" }
}
}]
}
"@
@{ Policy = $policy } | ConvertTo-Json | Out-File -Encoding ascii policy.json
aws sqs set-queue-attributes --queue-url $n --attributes file://policy.json
aws s3api put-bucket-notification-configuration --bucket sqs-test-bucket --notification-configuration file://notification.json
今度はエラーなく設定できました。
aws:SourceAccount の 000000000000 はエミュレーターのアカウントIDです。本物のAWSでは、自分のアカウントIDにします。
設定が終わると、S3からテスト用のメッセージが届きます。
aws sqs receive-message --queue-url $n --wait-time-seconds 5 --query "Messages[0].Body" --output text
{"Service":"Amazon S3","Event":"s3:TestEvent","Time":"2026-11-16T16:35:41.638052Z","Bucket":"sqs-test-bucket","RequestId":"A59B124EA73B04E6","HostId":"a59b124ea73b04e6d354d6dfd59ae20cf8b41fef99f606f4dfe50323029e2e51"}
ファイルをアップロードしてみます。
"hello" | Out-File -Encoding ascii report.txt
aws s3 cp report.txt s3://sqs-test-bucket/reports/report.txt
$ev = aws sqs receive-message --queue-url $n --wait-time-seconds 10 | ConvertFrom-Json
$rec = ($ev.Messages[0].Body | ConvertFrom-Json).Records[0]
$rec.eventName
$rec.s3.bucket.name
$rec.s3.object | Format-List
ObjectCreated:Put
sqs-test-bucket
key : reports/report.txt
sequencer : 18E893C94AFD2908
size : 7
eTag : af5597c29467a96523a70787c319f4db
アップロードしたファイルの名前とサイズが届いています。受け取る側でこのメッセージを見て、ファイルを処理する、という使い方ができます。
ちなみに、S3の通知の送り先にFIFOキューは使えません。
また、S3の通知は少なくとも1回届く作りで、普通は数秒で届くけれど1分以上かかることもある、とS3のドキュメントに書かれていました。同じ通知が2回届くこともあるので、受け取る側はそれを前提に作る必要があります。
エミュレーターで試すときの注意
AWS Emulatorの公式ドキュメントに、IAMポリシーとリソースベースのポリシーはAWSと同じようには評価しない、と書かれています。
今回はキューポリシーがないとS3の通知の設定がエラーになりましたが、エミュレーターで通ったからといって、ポリシーが正しいとは限りません。ポリシーは本物のAWSで確かめる必要があります。

コメント