AWS EmulatorでSQSのメッセージを送受信して消す方法
AWS Emulator を手元で動かすと、Amazon SQS のキューを作り、メッセージを送って、受け取って、消すまでを、AWS のアカウントなしで試せます。ジョブキューや非同期処理のように、SQS にたまった仕事を取り出して片付けるプログラムを、ローカル環境や CI でテストしたいときの手順です。SQS では、受け取っただけではメッセージは消えません。消さないとしばらくして戻ってくる動きも、AWS CLI の出力で確かめます。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.385(2026年11月14日リリース)、AWS CLI 2.40.3 です。AWS のアカウントと認証情報は使っていません。本物の Amazon SQS での動き(ショートポーリングで一部のメッセージしか返らないこと、削除したメッセージがまれにもう一度届くこと、PurgeQueue に最大60秒かかることなど)と料金は確かめておらず、記事で触れるところは公式ドキュメントを出どころにしています。試したのは標準キューだけで、FIFO キュー、デッドレターキュー、SDK(Boto3 など)からの呼び出しは試していません。
エミュレーターを起動して、AWS CLI を向ける
AWS Emulator の入れ方は公式の Linux 向けの手順のとおりです。起動は aws-emulator で、-t off はテレメトリーを切る指定です。
aws-emulator -t off
エミュレーターを動かしたまま別の端末を開き、公式ドキュメントにある環境変数を設定し、AWS CLI の送り先と認証情報をエミュレーターに向けます。
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
aws sts get-caller-identity の ARN が user/emulator になっていれば、エミュレーターに届いています。以下の出力では、12桁のアカウントIDを <12桁のアカウントID> に置き換えています。
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
キューを作る
キューは create-queue で作ります。FifoQueue の属性を付けなければ、標準キューになります(CreateQueue のリファレンス)。
$ aws sqs create-queue --queue-name example-queue
{
"QueueUrl": "https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue"
}
返ってきたキューの URL は、本物の SQS と同じ sqs.us-east-1.amazonaws.com の形でした。SQS のコマンドでは、この URL でキューを指定します。AWS CLI の送り先は AWS_ENDPOINT_URL で決まるので、この URL を渡しても、リクエストはエミュレーターに届きます。AWS の認証情報を置いていない検証環境で、以下のコマンドはどれもエミュレーターに届き、応答が返りました。
URL は毎回書くと長いので、get-queue-url で取り出して変数に入れておきます。あとでシェルスクリプトからも使うので、export を付けます。
$ aws sqs get-queue-url --queue-name example-queue --query QueueUrl --output text
https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue
$ export Q=$(aws sqs get-queue-url --queue-name example-queue --query QueueUrl --output text)
キューの設定を見ると、受け取ったメッセージが見えなくなる時間(visibility timeout)は30秒、メッセージを残しておく期間は345,600秒(4日)、受け取るときに待つ時間は0秒でした。どれも CreateQueue のリファレンスにある既定値と同じです。
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names VisibilityTimeout MessageRetentionPeriod ReceiveMessageWaitTimeSeconds
{
"Attributes": {
"VisibilityTimeout": "30",
"MessageRetentionPeriod": "345600",
"ReceiveMessageWaitTimeSeconds": "0"
}
}
メッセージを送る
send-message で本文を送ると、メッセージ ID と、本文の MD5 が返ります。
$ aws sqs send-message --queue-url "$Q" --message-body "注文 1001 を処理する"
{
"MD5OfMessageBody": "158318dcd88d3816169d4ce4b4c87082",
"MessageId": "9ea8542d-7a6b-42e8-b8a3-10a68385ace4"
}
返ってきた MD5 は、手元で md5sum を使って本文から計算した値と同じでした。
$ printf %s "注文 1001 を処理する" | md5sum
158318dcd88d3816169d4ce4b4c87082 -
キューの中の件数は get-queue-attributes で見られます。ApproximateNumberOfMessages は受け取れるメッセージの数、ApproximateNumberOfMessagesNotVisible は受け取られたあと、まだ消されていないメッセージの数です(GetQueueAttributes のリファレンス)。送った直後は、受け取れるものが1件でした。
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessages": "1",
"ApproximateNumberOfMessagesNotVisible": "0"
}
}
名前に Approximate(おおよその)と付いているとおり、本物の SQS では、メッセージの送信が止まってから1分以上たたないと数が合わないことがあるとリファレンスに書かれています。
受け取る:メッセージはキューに残ったまま見えなくなる
receive-message で受け取ります。ここでは、見えなくなる時間を --visibility-timeout 10 で10秒にしました。--message-system-attribute-names で、何回受け取られたか(ApproximateReceiveCount)と送った時刻(SentTimestamp、ミリ秒)も出しています。長い ReceiptHandle は途中を … で省いています。
$ aws sqs receive-message --queue-url "$Q" --visibility-timeout 10 --message-system-attribute-names ApproximateReceiveCount SentTimestamp
{
"Messages": [
{
"MessageId": "9ea8542d-7a6b-42e8-b8a3-10a68385ace4",
"ReceiptHandle": "YmI4YWY3MGQtOWQ5OS00NGQxLWEyYmQt…",
"MD5OfBody": "158318dcd88d3816169d4ce4b4c87082",
"Body": "注文 1001 を処理する",
"Attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1794706208353"
}
}
]
}
あとで消すときに使うのが ReceiptHandle(受信ハンドル)です。件数を見ると、受け取れるものが0件、見えないものが1件になりました。受け取ってもキューからは消えず、見えなくなっただけです。
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessagesNotVisible": "1",
"ApproximateNumberOfMessages": "0"
}
}
見えない間にもう一度 receive-message を実行すると、何も出力されずに終わりました(終了コードは0)。
$ aws sqs receive-message --queue-url "$Q"; echo "(出力ここまで)"
(出力ここまで)
SQS 開発者ガイドにある visibility timeout の説明のとおりの動きです。受け取ったメッセージはキューに残ったまま、ほかの受け手からしばらく見えなくなり、その間に処理して消すことになっています。

消さないと、時間がたって戻ってくる
消さずに10秒より長く待ってから受け取ると、同じメッセージ ID のメッセージがまた届きました。ApproximateReceiveCount は 2 に増えています。
$ sleep 11; aws sqs receive-message --queue-url "$Q" --visibility-timeout 10 --message-system-attribute-names ApproximateReceiveCount
{
"Messages": [
{
"MessageId": "9ea8542d-7a6b-42e8-b8a3-10a68385ace4",
"ReceiptHandle": "YmI4YWY3MGQtOWQ5OS00NGQxLWEyYmQt…",
"MD5OfBody": "158318dcd88d3816169d4ce4b4c87082",
"Body": "注文 1001 を処理する",
"Attributes": {
"ApproximateReceiveCount": "2"
}
}
]
}
途中を省いた表示では先頭が同じに見えますが、1回目と2回目の受信ハンドルを cmp で比べると、違う値でした(長さはどちらも165バイト)。受け取るたびに受信ハンドルが新しくなります。
処理の途中でプログラムが落ちても、メッセージは消えずにまた届く、ということです。逆に言うと、受け取ったあと消し忘れると、同じ仕事を何度も処理することになります。
受信ハンドルで消す
delete-message には、メッセージ ID ではなく受信ハンドルを渡します。DeleteMessage のリファレンスでは、同じメッセージを何度か受け取ったときは、いちばん新しい受け取りの受信ハンドルを使うように書かれています。
検証環境では、エミュレーターが古い受信ハンドルをどう扱うかを見るために、わざと1回目の受信ハンドルで先に消してみました。delete-message は何も出力せずに成功し(終了コードは0)、受け取れるもの・見えないものとも0件になりました。10秒より長く待って受け取っても、何も届きませんでした。
aws sqs delete-message --queue-url "$Q" --receipt-handle "<1回目に受け取った ReceiptHandle>"
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessages": "0",
"ApproximateNumberOfMessagesNotVisible": "0"
}
}
$ sleep 11; aws sqs receive-message --queue-url "$Q"; echo "(出力ここまで)"
(出力ここまで)
続けて2回目の受信ハンドルでも delete-message を実行すると、メッセージはもう消えていましたが、エラーにならずに成功しました。最新の受信ハンドルで消す書き方は、このあとのロングポーリングの例と、キューを空にするスクリプトで使っています。ロングポーリングの例で消したあとに3件送ると、件数は受け取れるもの3件・見えないもの0件で、前のメッセージは残っていませんでした。スクリプトで消したあとも、受け取れるもの・見えないものとも0件でした。
エミュレーターでは古い受信ハンドルでもメッセージが消えましたが、本物の SQS では、古い受信ハンドルではリクエストが成功してもメッセージが消えないことがあるとリファレンスに書かれています。エミュレーターで通ったテストでも、本物では同じメッセージがまた届くことがあるので、プログラムは最後に受け取ったときの受信ハンドルで消すように書いておきます。
受信ハンドルとしてでたらめな文字列を渡すと、ReceiptHandleIsInvalid のエラーになりました。終了コードは254です。
$ aws sqs delete-message --queue-url "$Q" --receipt-handle not-a-real-handle
aws: [ERROR]: An error occurred (ReceiptHandleIsInvalid) when calling the DeleteMessage operation: The input receipt handle is invalid.
処理をあきらめて、すぐに戻す
受け取ったけれど、この受け手では処理しないと決めたときは、見えなくなる時間が終わるのを待たずに戻せます。visibility timeout の説明には、ChangeMessageVisibility で時間を0秒にすると、すぐにほかの受け手が受け取れるようになると書かれています。
新しいメッセージを1件送って受け取り、その受信ハンドルで change-message-visibility --visibility-timeout 0 を実行しました(何も出力されずに成功)。続けてすぐに受け取ると、同じメッセージが受信回数2で届きました。
aws sqs change-message-visibility --queue-url "$Q" --receipt-handle "<受け取った ReceiptHandle>" --visibility-timeout 0
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[0].[Body,Attributes.ApproximateReceiveCount]" --output text
あきらめる例 2
テストの後片付けで、キューの中身をまとめて捨てたいときは purge-queue です。見えなくなっているメッセージも含めて消えます。検証環境では、実行した直後に受け取れるもの・見えないものとも0件になりました。PurgeQueue のリファレンスによると、本物の SQS では消し終わるまで最大60秒かかり、消したメッセージは取り戻せません。
$ aws sqs purge-queue --queue-url "$Q"
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessagesNotVisible": "0",
"ApproximateNumberOfMessages": "0"
}
}
メッセージが来るまで待って受け取る
receive-message は、既定ではメッセージがなくてもすぐに返ります(ショートポーリング)。--wait-time-seconds を付けると、その秒数までメッセージが来るのを待ちます(ロングポーリング)。ショートポーリングとロングポーリングの説明によると、待てる時間は最大20秒で、空の応答を減らせるので費用を抑えられることがあります。
空のキューで3秒待たせると、3秒あまりたってから、何も出力せずに戻りました。
$ time aws sqs receive-message --queue-url "$Q" --wait-time-seconds 3; echo "(出力ここまで)"
real 0m3.670s
user 0m0.606s
sys 0m0.059s
(出力ここまで)
10秒待たせている間に、別のプロセスから2秒後にメッセージを送ると、10秒を待たずに2.7秒ほどで戻り、送ったメッセージを受け取れました。受け取ったメッセージは、このあと受信ハンドルで消しています。
$ (sleep 2; aws sqs send-message --queue-url "$Q" --message-body "あとから届いた" > /dev/null) & time aws sqs receive-message --queue-url "$Q" --wait-time-seconds 10 --query "Messages[0].[Body,ReceiptHandle]" --output text > r4.txt; wait; cut -f1 r4.txt
real 0m2.709s
user 0m1.229s
sys 0m0.140s
あとから届いた
受け取りと削除をくり返して、キューを空にする
ここまでの「受け取る」と「消す」を、シェルスクリプトでくり返す形にしてみます。1回に最大10件まで受け取れるので(--max-number-of-messages 10。ReceiveMessage のリファレンスでは1〜10、既定は1)、受け取ったものを1件ずつ処理して、そのときの受信ハンドルで消します。何も返らなくなったら終わります。JSON の取り出しに jq を使っています。
# メッセージを受け取り、本文を表示してから、受け取ったときの受信ハンドルで消す。空になったら終わる
while :; do
msg=$(aws sqs receive-message --queue-url "$Q" --max-number-of-messages 10 --wait-time-seconds 1 --output json)
[ -z "$msg" ] && break
echo "$msg" | jq -c '.Messages[]' | while read -r m; do
echo "受け取った: $(echo "$m" | jq -r .Body)"
aws sqs delete-message --queue-url "$Q" --receipt-handle "$(echo "$m" | jq -r .ReceiptHandle)"
done
done
echo "キューが空になりました"
3件送ってから実行すると、3件を受け取って消し、終わったあとは受け取れるもの・見えないものとも0件でした。
$ bash consume.sh
受け取った: まとめて 1
受け取った: まとめて 2
受け取った: まとめて 3
キューが空になりました
このスクリプトは1秒のロングポーリングで受け取り、空で返ったら終わります。ショートポーリングとロングポーリングの説明によると、本物の SQS では、待ち時間を短くすると、メッセージが残っていても空で返ることがまれにあります。本物の SQS に向けるときは、待ち時間を長めにするなど、空の応答が出ても困らない作りにしておきます。DeleteMessage のリファレンスには、標準キューでは消したメッセージがまれにもう一度届くことがあるとも書かれており、同じメッセージを2回処理しても困らないように作るよう勧めています。
キューを消す
delete-queue でキューを消すと、list-queues は何も出さなくなり、get-queue-url はキューがないというエラーになりました。
$ aws sqs delete-queue --queue-url "$Q"
$ aws sqs list-queues; echo "(出力ここまで)"
(出力ここまで)
$ aws sqs get-queue-url --queue-name example-queue
aws: [ERROR]: An error occurred (AWS.SimpleQueueService.NonExistentQueue) when calling the GetQueueUrl operation: The specified queue does not exist.
CreateQueue のリファレンスによると、本物の SQS では、キューを消してから同じ名前のキューを作り直すには60秒以上待つ必要があります。
エミュレーターはリソースをメモリーにだけ置いていて、止めるとすべて消えると公式ドキュメントに書かれています。テストのたびに起動し直せば、空のキューから始められます。どこまで本物と同じに動くかはサービスや機能ごとに違い、忠実度(Fidelity)のページによると、今はリソースを作ったり一覧を出したりする API がいちばん本物に近いとされています。メッセージの送受信のような、サービスの本来の働きの部分は、サービスによって差があります。サービスごとの忠実度のスコアは GitHub のリリースページに載っています。



