AWS EmulatorでS3のイベント通知をSQSで受け取る方法

​​AWS Emulator​Amazon S3,Amazon SQS,AWS CLI,テスト

AWS Emulator の中で、SQS のキューのポリシーで S3 からの送信を許可し、バケットに通知の設定を入れると、オブジェクトを置いたり消したりしたときのイベントがキューに届きます。画像のアップロードをきっかけにサムネイルを作るような、S3 のイベントで動く処理を、AWS のアカウントなしでローカル環境や CI で試したいときの手順です。ポリシーがないと設定そのものが拒まれること、届く JSON の形、キーの URL エンコード、接頭辞と接尾辞での絞り込みを、検証環境で実行したコマンドと出力のまま載せます。

補足

検証環境は Ubuntu 24.04.5(x86_64)、AWS Emulator 1.0.385(2026年11月14日リリース、Debian パッケージ)、AWS CLI 2.40.3、jq 1.7 です。AWS のアカウントは使わず、リクエストはすべて手元のエミュレーターに送りました。本物の AWS での動き(通知が届くまでの時間、重複や順番の入れ替わり、料金など)は確かめておらず、触れるところは公式ドキュメントを出どころにしています。SNS や Lambda や EventBridge に送る設定、KMS で暗号化したキュー、別のアカウントのキュー、SDK からの呼び出しは試していません。

準備:エミュレーターを起動して、AWS CLI を向ける

エミュレーターは、公式ガイドの Linux 向けの手順のとおり、Debian パッケージの署名を gpg で確かめてから入れました。テレメトリーを切って起動し、別の端末で公式ドキュメントにある環境変数を設定します。

bash
aws-emulator -t off
bash
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

検証では、エミュレーターをスクリプトの中でバックグラウンドで起動し、標準出力を emu.out というファイルに書き出しました。アカウントIDの0の並びは、以下 <12桁の0> と書いています。

バケットとキューを作り、キューの ARN を調べる

aws s3api put-object でオブジェクトを置くと、バケットの通知の設定でイベントの種類とキーの絞り込みに合うものだけが SQS キューに入り、receive-message で受け取る流れ。前提として、キューのポリシーで S3 からの送信を許可していないと通知の設定が拒まれる
オブジェクトを置いてから、キューで受け取るまでの流れ

S3 のユーザーガイドにある、通知の送り先に権限を与える説明のとおり、キューのポリシーで S3 からの送信を許可しておく必要があります。この記事では、ポリシーがないときの様子を先に見るため、許可より先に通知の設定を入れています。

text
$ aws s3api create-bucket --bucket uploads-bucket
{
    "Location": "/uploads-bucket",
    "BucketArn": "arn:aws:s3:::uploads-bucket"
}
$ aws sqs create-queue --queue-name uploads-queue
{
    "QueueUrl": "https://sqs.us-east-1.amazonaws.com/<12桁の0>/uploads-queue"
}

通知の設定には、キューの URL ではなく ARN を書きます。あとのコマンドで使うので、URL と ARN を変数に入れておきます。

bash
QUEUE_URL=$(aws sqs get-queue-url --queue-name uploads-queue --query QueueUrl --output text)
QUEUE_ARN=$(aws sqs get-queue-attributes --queue-url "$QUEUE_URL" --attribute-names QueueArn --query Attributes.QueueArn --output text)
text
$ echo "$QUEUE_URL"; echo "$QUEUE_ARN"
https://sqs.us-east-1.amazonaws.com/<12桁の0>/uploads-queue
arn:aws:sqs:us-east-1:<12桁の0>:uploads-queue

キューのポリシーがないと、通知の設定が拒まれる

バケットの通知の設定は JSON で書きます。QueueConfigurations にキューの ARN と、通知するイベントの種類を入れます。s3:ObjectCreated:* は、オブジェクトが作られたときのイベントをまとめて指す書き方です。QUEUE_ARN の値を埋め込んで notification.json に保存しました。

json
{
  "QueueConfigurations": [
    {
      "Id": "uploads-to-sqs",
      "QueueArn": "arn:aws:sqs:us-east-1:<12桁の0>:uploads-queue",
      "Events": ["s3:ObjectCreated:*"]
    }
  ]
}

これを put-bucket-notification-configuration で入れると、InvalidArgument のエラーになりました。

text
$ aws s3api put-bucket-notification-configuration --bucket uploads-bucket --notification-configuration file://notification.json

aws: [ERROR]: An error occurred (InvalidArgument) when calling the PutBucketNotificationConfiguration operation: Unable to validate the following destination configurations

直後に get-bucket-notification-configuration を実行しても何も出力されず、設定は残っていませんでした。エミュレーターのログ(1行ずつの JSON)の fields を jq で取り出すと、キューの権限が S3 からの通知を許していないため、設定を記録せずに拒んだと書かれています。

text
$ grep "do not validate" emu.out | jq .fields
{
  "message": "this notification configuration names destinations that do not validate; it is refused rather than recorded",
  "bucket": "uploads-bucket",
  "destinations": "[(\"arn:aws:sqs:us-east-1:<12桁の0>:uploads-queue\", \"Permissions on the destination queue do not allow S3 to publish notifications from this bucket\")]"
}

PutBucketNotificationConfiguration の API リファレンスには、設定を入れると S3 が送り先にテストのメッセージを送り、それが失敗すると設定全体が失敗して、バケットに追加されないと書かれています。エミュレーターでも、設定が丸ごと拒まれました。

キューのポリシーで、S3 からの SendMessage を許可する

送り先に権限を与える説明にある SQS のキューのポリシーの例にならい、Principal を S3 のサービス(s3.amazonaws.com)にして sqs:SendMessage を許可します。条件の aws:SourceArn で送り元をこのバケットに、aws:SourceAccount でバケットの持ち主のアカウントに限ります。

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "s3.amazonaws.com" },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:us-east-1:<12桁の0>:uploads-queue",
      "Condition": {
        "ArnLike": { "aws:SourceArn": "arn:aws:s3:::uploads-bucket" },
        "StringEquals": { "aws:SourceAccount": "<12桁の0>" }
      }
    }
  ]
}

これを policy.json に保存し、jq の tostring でポリシーを文字列にしてから、キューの Policy という属性に入れます。そのあと、さきほど拒まれた通知の設定をもう一度入れると、今度は何も出力せずに成功しました。

text
$ jq -c "{Policy: tostring}" policy.json > attributes.json && aws sqs set-queue-attributes --queue-url "$QUEUE_URL" --attributes file://attributes.json
$ aws s3api put-bucket-notification-configuration --bucket uploads-bucket --notification-configuration file://notification.json
$ aws s3api get-bucket-notification-configuration --bucket uploads-bucket
{
    "QueueConfigurations": [
        {
            "Id": "uploads-to-sqs",
            "QueueArn": "arn:aws:sqs:us-east-1:<12桁の0>:uploads-queue",
            "Events": [
                "s3:ObjectCreated:*"
            ]
        }
    ]
}

この時点で、キューには s3:TestEvent というメッセージが1つ届いていました。オブジェクトをまだ置いていなくても届きます。

text
$ aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 3 > test-event.json; jq -r ".Messages[0].Body | fromjson" test-event.json
{
  "Service": "Amazon S3",
  "Event": "s3:TestEvent",
  "Time": "2026-11-15T02:27:34.090325Z",
  "Bucket": "uploads-bucket",
  "RequestId": "41821C507A61C1F9",
  "HostId": "41821c507a61c1f926c26f5bc0f03822874ceeb69135706afeef1d9eb68d2a1e"
}

イベントのメッセージの構造の説明にも、通知を設定すると S3 がこの形のテストのメッセージを送ると書かれています。このメッセージには Records がありません。同じ説明には、受け取る側のコードがテストのメッセージとイベントのメッセージの両方を見分けて扱えるようにしておくよう書かれています。確かめたあとは delete-message で消しました。

注意

AWS Emulator の公式ドキュメントでは、IAM のポリシーとリソースベースのポリシーを AWS と同じようには評価しないとして、セキュリティのテストに使わないよう書かれています。この検証ではキューのポリシーの有無で結果が変わりましたが、本物の AWS でポリシーが正しいかは、エミュレーターの結果だけでは確かめられません。

オブジェクトを置くと、Records を持つ JSON が届く

images/photo.jpg を置いてから受け取ると、本文は Records という配列を持つ JSON でした。

text
$ aws s3api put-object --bucket uploads-bucket --key images/photo.jpg --body photo.jpg --query ETag --output text
"b1946ac92492d2347c6235b4d2611184"
$ aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 5 > created.json; jq -r ".Messages[0].Body | fromjson" created.json
{
  "Records": [
    {
      "eventVersion": "2.1",
      "eventSource": "aws:s3",
      "awsRegion": "us-east-1",
      "eventTime": "2026-11-15T02:27:37.054893Z",
      "eventName": "ObjectCreated:Put",
      "userIdentity": {
        "principalId": "f7b11509f4d675c3c44f0dd37ca830bb02e8cfa58f04c46283c4bfcbdce1ff45"
      },
      "requestParameters": {
        "sourceIPAddress": "127.0.0.1"
      },
      "responseElements": {
        "x-amz-request-id": "40E382E358151959",
        "x-amz-id-2": "40e382e358151959ef38b1d2d20929042c0b47ec0dbb7f6fce1191df2147b4af"
      },
      "s3": {
        "s3SchemaVersion": "1.0",
        "configurationId": "uploads-to-sqs",
        "bucket": {
          "name": "uploads-bucket",
          "ownerIdentity": {
            "principalId": "f7b11509f4d675c3c44f0dd37ca830bb02e8cfa58f04c46283c4bfcbdce1ff45"
          },
          "arn": "arn:aws:s3:::uploads-bucket"
        },
        "object": {
          "key": "images/photo.jpg",
          "sequencer": "18E816EC9FB85530",
          "size": 6,
          "eTag": "b1946ac92492d2347c6235b4d2611184"
        }
      }
    }
  ]
}

eventName には、設定の s3: を除いた ObjectCreated:Put が入っています。configurationId は、通知の設定に付けた Id です。項目の名前と入れ子の形は、公式ドキュメントのメッセージの構造の説明にある例と同じでした(eventVersion は、公式の例が 2.6、エミュレーターは 2.1)。ここでは jq で、イベントの種類、バケットの名前、キー、サイズを取り出します。

text
$ jq -r ".Messages[0].Body | fromjson | .Records[] | [.eventName, .s3.bucket.name, .s3.object.key, .s3.object.size] | @tsv" created.json
ObjectCreated:Put	uploads-bucket	images/photo.jpg	6

続けて aws s3 rm でこのオブジェクトを消しても、キューには何も届きませんでした。設定したのが s3:ObjectCreated:* だけで、削除のイベントは入っていないためです。

キーは URL エンコードされて届く

キーに空白や日本語を含む images/my photo 猫.jpg を置くと、届いたキーは + と % を使った形になっていました。

text
$ aws s3api put-object --bucket uploads-bucket --key "images/my photo 猫.jpg" --body photo.jpg --query ETag --output text
"b1946ac92492d2347c6235b4d2611184"
$ aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 5 > space.json; jq -r ".Messages[0].Body | fromjson | .Records[0].s3.object.key" space.json
images/my+photo+%E7%8C%AB.jpg

メッセージの構造の説明にも、キーの値は URL エンコードされていて、red flower.jpg は red+flower.jpg になると書かれています。受け取ったキーは、置いたときのキーと同じ文字列ではありません。空白を + に変える形式なので、Python なら urllib.parse.unquote_plus で元に戻せました。

text
$ python3 -c "import json,sys,urllib.parse; b=json.load(open(\"space.json\"))[\"Messages\"][0][\"Body\"]; print(urllib.parse.unquote_plus(json.loads(b)[\"Records\"][0][\"s3\"][\"object\"][\"key\"]))"
images/my photo 猫.jpg

接頭辞と接尾辞で絞り、削除のイベントも受け取る

images/ の下の .jpg だけを、作られたときと消されたときの両方で受け取るように、設定を書き換えます。キーの絞り込みは Filter の FilterRules に、prefix と suffix で書きます。書き方はキーの名前で絞り込む説明にある例と同じです。

json
{
  "QueueConfigurations": [
    {
      "Id": "jpg-under-images",
      "QueueArn": "arn:aws:sqs:us-east-1:<12桁の0>:uploads-queue",
      "Events": ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"],
      "Filter": {
        "Key": {
          "FilterRules": [
            { "Name": "prefix", "Value": "images/" },
            { "Name": "suffix", "Value": ".jpg" }
          ]
        }
      }
    }
  ]
}

これを notification-filter.json に保存して入れると、キューにはまた s3:TestEvent が届きました。設定を入れ直すたびにテストのメッセージが届きます。

text
$ aws s3api put-bucket-notification-configuration --bucket uploads-bucket --notification-configuration file://notification-filter.json
$ aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 3 > test-event2.json; jq -c ".Messages[0].Body | fromjson | {Event, Bucket}" test-event2.json
{"Event":"s3:TestEvent","Bucket":"uploads-bucket"}

テストのメッセージを消してから、3つのキーでオブジェクトを置き、そのうち2つを消しました。

text
$ for k in docs/readme.txt images/icon.png images/cat.jpg; do aws s3api put-object --bucket uploads-bucket --key "$k" --body photo.jpg --query ETag --output text; done
"b1946ac92492d2347c6235b4d2611184"
"b1946ac92492d2347c6235b4d2611184"
"b1946ac92492d2347c6235b4d2611184"
$ aws s3 rm s3://uploads-bucket/images/cat.jpg
delete: s3://uploads-bucket/images/cat.jpg
$ aws s3 rm s3://uploads-bucket/images/icon.png
delete: s3://uploads-bucket/images/icon.png
$ aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 3 --max-number-of-messages 10 > filtered.json; jq -r ".Messages[].Body | fromjson | .Records[] | [.eventName, .s3.object.key] | @tsv" filtered.json
ObjectCreated:Put	images/cat.jpg
ObjectRemoved:Delete	images/cat.jpg

5回の操作のうち、届いたのは images/cat.jpg を置いたときと消したときの2つだけです。接頭辞が違う docs/readme.txt は置いても届かず、接尾辞が違う images/icon.png は置いても消しても届きませんでした。続けてもう一度受け取っても、ほかのメッセージは出てきませんでした。

API リファレンスによると、put-bucket-notification-configuration はそれまでの設定を丸ごと置き換えます。複数の送り先や絞り込みを使うときは、毎回すべてを1つの JSON に書きます。キーの名前で絞り込む説明によると、接頭辞どうし、接尾辞どうし、または接頭辞と接尾辞が重なる絞り込みを、同じイベントの種類で複数書くことはできません。

空の設定を入れると、通知が止まる

API リファレンスには、空の設定を入れると通知を止められると書かれています。{} を入れると、get-bucket-notification-configuration は何も出力しなくなり、そのあと images/after.jpg を置いてもキューには何も届きませんでした。

text
$ aws s3api put-bucket-notification-configuration --bucket uploads-bucket --notification-configuration "{}"
$ aws s3api get-bucket-notification-configuration --bucket uploads-bucket
$ aws s3api put-object --bucket uploads-bucket --key images/after.jpg --body photo.jpg --query ETag --output text
"b1946ac92492d2347c6235b4d2611184"
$ aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 3 --max-number-of-messages 10 --query "Messages[].Body"
null

本物の AWS で違ってくるところ

この検証では、どの通知も1回ずつ届きました。S3 のイベント通知の概要によると、本物の AWS では通知は「少なくとも1回」届くように作られていて、ふだんは数秒で届くものの、1分以上かかることもあります。イベントの種類と送り先の説明には、まれに同じイベントが重複して届くことや、届く順番が起きた順と同じとは限らないことも書かれています。同じ説明によると、SQS の FIFO キューは送り先にできず、FIFO キューに送りたいときは EventBridge を使います。エミュレーターで通ったテストでも、受け取る側の処理は、重複と順番の入れ替わりがあっても困らないように作っておく必要があります。

​Posted by 86