AWS SQSの仕組みと使い方をAWS Emulatorで試す

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秒たつとキューに戻る図

受け取る側が処理している間に、別の受け取る側が同じメッセージを処理してしまわないための仕組みです。

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)といいます。

受信が3回を超えたメッセージがデッドレターキューに移り、start-message-move-taskで元のキューに戻す図

元のキュー(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回目は何も返ってきません。

グループuser-aのA-1が処理中の間はA-2が出てこず、別グループのB-1は受信できる図

同じグループのメッセージは順番に処理されるので、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で確かめる必要があります。

コメント

タイトルとURLをコピーしました