EventBridgeのルールは、イベントのJSONとイベントパターンを照合し、一致したものだけをターゲットへ送ります。本記事では照合規則、prefix・anything-but・numeric・wildcard・$orなどの比較演算子、S3とCloudTrailの実例、test-event-patternとpytestによるテストを、AWS公式ドキュメントに沿って整理しました。全体像はAmazon EventBridgeとは？仕組み・料金とCLI・Pythonでの実装手順に譲り、ここではルールの条件を書く作業に絞ります。仕様と上限値は2026年10月時点の記載です。
まとめ：イベントパターンは照合規則を押さえて書き、テストで固定する
パターンで詰まる原因の多くは、演算子の知識不足ではなく照合規則の誤解にあります。フィールド同士はAND、1つのフィールドの配列の中はORです。同じフィールドにprefixとsuffixを並べると、どちらか一方で一致してしまう。文字列は大文字小文字を区別する厳密一致で、数値も文字列表現で比べるため300と300.0は別の値になります。
書き方の基本は、sourceとdetail-typeを必ず書き、detailの中を演算子で絞ることです。書いたら一致すべきイベントと弾くべきイベントの両方で確かめ、そのケースをpytestに入れてCIで回します。パターンが2,048字の上限に近づいたら、条件をターゲット側のコードへ移す判断をします。
イベントパターンの照合規則｜配列のOR・フィールドのANDと型の扱い
演算子を足す前に、パターンがどう評価されるかを押さえます。
フィールド間はAND・配列内はORになる照合の基本と書かない項目
公式のイベントパターン構文によると、パターンに書かなかったフィールドは無視されます。逆に、書いたフィールド名はすべてイベント側に同じネスト構造で存在しなければなりません。値は必ずJSON配列で書き、並べた値のいずれかに一致すればよい、という意味になります。
{
"source": ["aws.ec2"],
"detail-type": ["EC2 Instance State-change Notification"],
"detail": { "state": ["stopped", "terminated"] }
}この例は、3つのフィールドがすべて条件を満たし、stateがstoppedかterminatedのイベントに一致します。見落としやすいのは配列に演算子を2つ置いた場合です。"key": [{"prefix": "uploads"}, {"suffix": ".csv"}]は「uploadsで始まる、または.csvで終わる」になる。1つのフィールドに「AかつB」を課すなら、後述のwildcardで1つの式にまとめます。
文字単位の厳密一致と300≠300.0、キーのドット結合による想定外の一致
文字列は文字単位の厳密一致で、"Running"と"running"は別物です。数値も文字列表現で比べるため、公式は300と300.0と3.0e2を等しくないと明記しています。値として比べたいときはnumericで["=", 300]と書きます。
同じキーを2回書くと最後の1つだけが使われる点も要注意です。さらに、EventBridgeはドットを結合文字としてパターンをコンパイルするため、{"state": {"status": [...]}}と{"state.status": [...]}は同じ扱いになります。公式はどちらも「現在の動作の説明で、依存すべきではない」と注記しているので、重複キーやドット入りのキー名は使いません。
イベント側が配列のときは共通要素が1つあれば一致する判定とARNの注意
resourcesのように配列で届くフィールドについて、複数の値での一致の解説は、パターンとイベントの配列の共通部分が空でなければ一致すると定めています。順序は問いません。Auto ScalingのイベントにはグループとインスタンスのARNが並びますが、インスタンスのARNを1つ書けば届きます。
ARNの区切り文字には気をつけてください。AWS CLIのtest-event-patternリファレンスは、多くのサービスがARNの:と/を同一視する一方、EventBridgeのパターンは完全一致で比べると注意書きしています。実際のイベントからARNをコピーして書くのが安全です。
比較演算子の書き方｜prefix・numeric・$orなど主要な条件の指定方法
公式の比較演算子ページによると、$orとanything-butを除き、演算子は値を持つ末端のフィールド（リーフノード）でしか機能しません。
主要な演算子をイベントバスとPipesの対応可否で並べた早見表
同じ構文はEventBridge Pipesのフィルタでも使えますが、一部は対応していません。ルールのパターンをPipesへ移す予定があるなら、右列を先に確認します。
| 演算子 | 用途 | バス | Pipes |
|---|---|---|---|
| 完全一致 | 値の一致（配列はOR） | 可 | 可 |
| prefix ／ suffix | 前方一致・後方一致 | 可 | 可 |
| equals-ignore-case | 大文字小文字を無視 | 可 | 可 |
| anything-but | 指定値以外 | 可 | 可 |
| anything-butの拡張 | prefix等と組み合わせた除外 | 可 | 不可 |
| numeric | 数値の範囲 | 可 | 可 |
| exists | 項目の有無 | 可 | 可 |
| cidr | IPアドレス範囲 | 可 | 可 |
| wildcard | *を使う部分一致 | 可 | 不可 |
| $or | 複数フィールドのOR | 可 | 可 |
「anything-butの拡張」は、anything-butにequals-ignore-case・prefix・suffix・wildcardを組み合わせた形です。Pipes側でソースごとに起点のフィールドが変わる点はEventBridge Pipesの使い方：DynamoDB Streamsのフィルタとエンリッチ実装で扱っています。
prefix・suffixと大文字小文字を無視する指定で文字列の一部を照合
前方一致は{"prefix": "2017-10-02"}、後方一致は{"suffix": ".png"}と書きます。拡張子が.PNGで届くかもしれないファイル名のように、大文字小文字を区別したくない場合は値の位置にequals-ignore-caseを入れ子にします。
{
"detail": {
"FileName": [{ "suffix": { "equals-ignore-case": ".png" } }]
}
}AWSサービスのsourceやdetail-typeは表記が決まっているので、ここを緩める理由はありません。緩めるのは利用者の入力やファイル名など、表記が揺れるデータに限ります。
anything-butは単一値・リスト・prefixとの組み合わせで除外を書く
anything-butは指定した値以外に一致し、{"anything-but": ["stopped", "overloaded"]}のようにリストも渡せます。イベントバスでは{"anything-but": {"prefix": "init"}}のように前方一致・後方一致・wildcardとも組み合わせ可能です。
受け取りたい値が確定しているなら、完全一致のリストのほうが安全です。ソース側に新しい値が増えると、anything-butはそれを黙って通してしまう。公式のベストプラクティスも、後から追加されるイベントによる予期しない一致を避けるよう勧めています。
numericは±2の53乗までの倍精度で比較する範囲指定の書き方
numericは比較演算子と値を交互に並べ、{"numeric": [">", 0, "<=", 5]}なら0より大きく5以下です。値は64ビット倍精度浮動小数点数（IEEE 754 binary64）として比べられ、正確に判定できる整数は-2の53乗から+2の53乗まで。範囲外の値をルールに書くと作成時に拒否され、範囲外のイベント値は数値比較に一致しません。
19桁の注文IDのような値は、数値ではなく文字列の完全一致かprefixで扱います。2022年の機能追加を伝えた解説には範囲を「-5.0e9〜+5.0e9」とするものがあり、現行の記載とは異なる内容です。またAWSがOSSで公開している同じ構文の照合ライブラリEvent RulerのREADMEは、numericがJSONの数値にだけ働くと明記しています。"amount": "12800"のように文字列で送っているなら、送信側を直すのが先です。
exists・null・空文字列を区別し項目の有無で振り分ける条件
項目の有無は{"exists": true}と{"exists": false}で分けます。値がnullのイベントと項目そのものが無いイベントは別物で、前者は[null]、後者は[{"exists": false}]、空文字列は[""]で拾います。
「値なし」の表現が送信側で揺れると、ルールが発火しない原因になります。パターンで吸収するより、送信側のスキーマで1つに決めるほうが手間は減ります。
wildcardとcidr、30ルール上限と複雑さエラーの回避策
wildcardは{"wildcard": "dir/*.png"}のように書きます。*はいくつ置いてもよいものの、連続した**は使えません。パターンが複雑すぎるとInvalidEventPatternExceptionが返るため、公式はワイルドカードの数とその後ろに続く文字列を減らすよう挙げています。
EventBridgeのクォータでは、ワイルドカードを含むルールは1つのバスにつき30本までで、引き上げできません。cidrは{"cidr": "10.0.0.0/24"}の形でIPv4とIPv6に使え、CloudTrailイベントのsourceIPAddressで社外からのAPI呼び出しを拾う用途に向きます。
$orで複数フィールドのいずれかに一致させ組み合わせ1,000以内に収める
フィールドをまたぐORは$orで書きます。各要素にはnumericなど他の条件をそのまま入れられます。
{
"source": ["com.example.orders"],
"detail": {
"$or": [
{ "amount": [{ "numeric": [">=", 100000] }] },
{ "customerRank": ["platinum"] }
]
}
}公式は組み合わせ数を各$orの要素数の積と定義し、1,000を超えるとPutRuleやTestEventPatternが例外を返すとしています。3要素と2要素の$orを同居させれば6通りです。積で増えるので、$orを重ねる前にルールを分けることを考えます。
S3とCloudTrailのイベントを例にルールのパターンを組み立てる手順
リージョンは東京（ap-northeast-1）、アカウントIDは例として111122223333で進めます。
S3のObject Createdを接頭辞・拡張子・サイズで絞るパターン例
S3の公式手順では、バケットでEventBridge通知を有効にすると全イベントが送られ、反映に5分ほどかかります。このコマンドは通知設定全体を置き換えるため、既存の通知があるバケットでは現在の設定に足した形で渡してください。
aws s3api put-bucket-notification-configuration \
--bucket amzn-s3-demo-bucket1 \
--notification-configuration '{ "EventBridgeConfiguration": {} }'「uploadsに置かれた0バイトより大きいCSVで、コピーによる作成は除く」条件をpatterns/s3-csv-upload.jsonに保存します。フィールド名はS3のイベント構造のObject Createdの例に合わせました。
{
"source": ["aws.s3"],
"detail-type": ["Object Created"],
"detail": {
"bucket": { "name": ["amzn-s3-demo-bucket1"] },
"object": {
"key": [{ "wildcard": "uploads/*.csv" }],
"size": [{ "numeric": [">", 0] }]
},
"reason": [{ "anything-but": "CopyObject" }]
}
}キーをprefixとsuffixの2要素にせずwildcard1つにしたのは、2要素だとORになるためです。その代わり、このルールはワイルドカード30本の枠を1本使います。reasonにはPutObject・POST Object・CopyObject・CompleteMultipartUploadのいずれかが入るので、PutObjectだけを完全一致で指定するとマルチパートで届く大きなファイルを取りこぼします。
CloudTrailのAPIコールを$orで束ね読み取り系はルール状態で拾う
CloudTrail経由のイベントの解説によると、受け取るには証跡の有効化が必要で、イベントはデフォルトバスにだけ届きます。証跡の設計はCloudTrailとは？証跡設計と料金実額・Lake新規受付終了後の構成をCLIで解説にまとめました。
{
"detail-type": ["AWS API Call via CloudTrail"],
"$or": [
{ "source": ["aws.ec2"],
"detail": { "eventName": [{ "prefix": "AuthorizeSecurityGroup" }] } },
{ "source": ["aws.s3"],
"detail": { "eventName": ["PutBucketPolicy", "DeleteBucketPolicy"] } }
]
}sourceとeventNameの組を$orで束ねる形は、公式ベストプラクティスの例と同じです。ただし既定のENABLED状態のルールが拾うのは書き込み系の管理イベントで、読み取り専用の管理イベントはENABLED_WITH_ALL_CLOUDTRAIL_MANAGEMENT_EVENTSにしたルールでしか一致しません。読み取り系だけ拾えないときは、パターンではなくルールの状態を疑います。
put-ruleでルールを登録するときの上書き仕様と反映待ちの注意
S3とCloudTrailのイベントはデフォルトバスに届くので、--event-bus-nameは省略します。
aws events put-rule \
--name s3-csv-upload \
--event-pattern file://patterns/s3-csv-upload.json \
--state ENABLED \
--region ap-northeast-1
aws events put-targets \
--rule s3-csv-upload \
--targets '[{"Id":"csv-ingest","Arn":"arn:aws:sqs:ap-northeast-1:111122223333:csv-ingest"}]' \
--region ap-northeast-1put-ruleのリファレンスによると、put-ruleは既存ルールを置き換え、省略したオプションはnullになります。パターンだけ直すつもりで--stateや説明文を省くと、それらが消える仕様です。作成・更新の直後は新しいパターンがすぐ一致しない場合もあるため、届かなくても少し待って再送してから判断します。ルールで絞ったイベントをSNSメールやSlackの通知文に整える手順は、EventBridge 入力トランスフォーマーの使い方にまとめています。
イベントパターンのテスト｜サンドボックス・CLI・pytestで一致を確かめる
テストはルールを作る前と、パターンを変えるたびに行います。本番で「届かない」と気づいてからでは切り分けに時間を取られます。
コンソールのサンドボックスでサンプルイベントと照合する操作手順
形を掴む段階では、ルールを作らずに照合できるEventBridgeコンソールのサンドボックスが手軽です。
- 「デベロッパーリソース」から「サンドボックス」を開き、「イベントパターン」タブを選ぶ
- AWSのサンプルイベントを選ぶか、「自分のイベントを入力」に実際のJSONを貼る
- 「Custom pattern (JSON editor)」にパターンを貼り、「テストパターン」を押す
- 一致を確認できたら「パターンを持つルールを作成」で作成画面へ引き継ぐ
サンプルイベントは値が固定なので、コピーしてサイズを0にする、拡張子を.tsvにするなど書き換え、弾かれる側も確かめます。
test-event-patternで一致と不一致の両方のケースを確かめる手順
手元で繰り返すならCLIです。イベントにはid・account・source・time・region・resources・detail-typeの7項目が必須で、detailは条件に使う部分だけで足ります。
aws events test-event-pattern \
--event-pattern file://patterns/s3-csv-upload.json \
--event '{"id":"1","account":"111122223333","source":"aws.s3","time":"2026-10-17T00:00:00Z","region":"ap-northeast-1","resources":["arn:aws:s3:::amzn-s3-demo-bucket1"],"detail-type":"Object Created","detail":{"bucket":{"name":"amzn-s3-demo-bucket1"},"object":{"key":"uploads/2026/orders.csv","size":2048},"reason":"PutObject"}}' \
--region ap-northeast-1
# 一致すれば {"Result": true}、しなければ {"Result": false}キーをorders.CSVに変えると、wildcardは大文字小文字を区別するのでfalseです。なお--event-patternは4,096字まで受け付けますが、ルールに登録できるのはクォータの2,048字まで。テストが通るのにput-ruleで弾かれるなら字数を確認します。
boto3のtest_event_patternをpytestに組み込みCIで回帰を防ぐ
パターンをリポジトリで管理しているなら、一致・不一致のケースをテストに残すと、条件を足したときの壊れ方にすぐ気づけます。boto3のtest_event_patternは、パターンとイベントをJSON文字列で受け取り、Resultに真偽値を返します。
import json
import pathlib
import boto3
import pytest
client = boto3.client("events", region_name="ap-northeast-1")
PATTERN = pathlib.Path("patterns/s3-csv-upload.json").read_text()
BASE = {
"id": "1",
"account": "111122223333",
"source": "aws.s3",
"time": "2026-10-17T00:00:00Z",
"region": "ap-northeast-1",
"resources": ["arn:aws:s3:::amzn-s3-demo-bucket1"],
"detail-type": "Object Created",
}
def s3_event(key, size, reason="PutObject"):
return {
**BASE,
"detail": {
"bucket": {"name": "amzn-s3-demo-bucket1"},
"object": {"key": key, "size": size},
"reason": reason,
},
}
@pytest.mark.parametrize(
"event, expected",
[
(s3_event("uploads/2026/orders.csv", 2048), True),
(s3_event("uploads/2026/orders.csv", 2048, "CompleteMultipartUpload"), True),
(s3_event("uploads/2026/orders.tsv", 2048), False),
(s3_event("tmp/orders.csv", 2048), False),
(s3_event("uploads/2026/empty.csv", 0), False),
(s3_event("uploads/2026/orders.csv", 2048, "CopyObject"), False),
],
)
def test_s3_csv_upload_pattern(event, expected):
res = client.test_event_pattern(EventPattern=PATTERN, Event=json.dumps(event))
assert res["Result"] is expectedEventBridgeのAPIを呼ぶため、CIにはevents:TestEventPatternを許可したロールの認証情報が要ります。文法が壊れていればInvalidEventPatternExceptionで落ちるので、構文チェックも兼ねられます。
Event RulerでAWSに接続せずJava側で照合を再現する選択肢
CIからAWSへ接続したくない場合は、Apache License 2.0のJavaライブラリEvent Rulerが候補です。MachineにaddRuleでルールを登録し、rulesForJSONEventにイベントを渡すと一致したルール名が返ります。Maven Centralの最新は2026年10月時点で2.2系（2.2.0、2026年9月公開）です。
<dependency>
<groupId>software.amazon.event.ruler</groupId>
<artifactId>event-ruler</artifactId>
<version>2.2.0</version>
</dependency>READMEはEventBridgeとの挙動の同一性を保証していません。最終的な合否はTestEventPatternで判定し、Event Rulerは開発中の確認用にとどめます。
イベントパターンの設計判断｜ルールで絞る条件とターゲット側で捌く場面
パターンとコードの分担は、運用の手間と事故の起きやすさで決めます。
ルールのパターンで絞るべき条件はsourceとdetail-typeまで必ず書く
パターンで絞るのは、ターゲットを呼ぶこと自体が無駄になるイベントです。公式ベストプラクティスの例では、sourceだけを指定したパターンが後から追加された「Payment rejected」まで拾ってしまいます。detail-typeまで書けば、ソース側の追加に巻き込まれません。
無限ループの防止もパターン側の責任です。S3のACL変更を検知してACLを直すルールは、修正自体が再びルールを発火させます。公式は「変更があったら」ではなく「ACLが不良な状態のときだけ」一致させるよう勧めています。ターゲットが同じ種類のイベントを生む構成では、requesterなど自分の操作を見分ける条件を入れ、Amazon EventBridgeの料金で見積もった額を超えたら気づけるようAWS Budgetsのアラートも設定しておくと安心です。
パターンで頑張らない場面は2,048字に迫る条件とPipesへの移行予定
次の場面では、条件をパターンに詰め込まず、ターゲット側のコードで判定します。
- パターンが2,048字に近い、または
$orの組み合わせが数百に達する - 条件が業務ルールで頻繁に変わり、更新と反映待ちが負担になる
- ワイルドカードを含むルールが1つのバスで30本に近い
- Pipesへ移す予定があり、wildcardやanything-butの拡張に依存したくない
パターンは「明らかに不要なイベントを捨てる粗いふるい」、業務判断はLambdaなどのコードで単体テストする、という分担が扱いやすい形です。ルール1本のターゲットは5つまでで、引き上げはできません。イベント駆動の構成をAWS上でどう組むか、既存システムのどこから切り出すかを含めて検討したい場合は、インフラ構築（AWS・Google Cloud・Azure）でご相談を受け付けています。
よくある質問
EventBridgeのイベントパターンについて、よく聞かれる疑問を5つ取り上げます。
イベントパターンで大文字小文字を区別しない指定はできますか？
できます。値全体なら{"equals-ignore-case": "running"}、後方一致と組み合わせるならsuffixの値の中に入れ子で書く形。指定しなければ大文字小文字は区別されます。wildcardには大文字小文字を無視する指定が無いため、.CSVも受けたいならwildcardを2要素の配列にするか、アップロード時にキーを小文字へ揃える運用にしてください。
ルールがイベントに一致しないときは何を確認しますか？
実際に届いたイベントのJSONをtest-event-patternでパターンと照合します。falseなら、ネストの位置、大文字小文字、数値か文字列か、同じフィールドの条件がORになっていないかを見ます。trueなのに届かないなら、ルールの状態、ルールを置いたバス、更新直後の反映待ち、ターゲット側のアクセス許可が確認先です。実際のイベントの捕まえ方とメトリクスでの切り分けはEventBridge ログの調べ方：ルールが発火しない原因をメトリクス・バスログ・DLQで特定するにまとめました。
イベントパターンの文字数に上限はありますか？
あります。クォータの「Event pattern size」は2,048字で、引き上げを申請できる項目です。APIのパラメータは4,096字まで受け付けますが、ルールに登録できるのはクォータの範囲になります。上限に近づいたら、値の列挙をprefixやnumericの範囲に置き換えるか、ルールを分けて対応します。
Pipesのフィルタとイベントバスのルールで書き方は同じですか？
構文は共通ですが、wildcardとanything-butの拡張はPipesで使えません。またPipesのフィルタリングでは、SQSならbody、DynamoDB Streamsならdynamodbというようにソースごとに起点のフィールドが変わります。ルールのパターンを貼るだけでは動きません。
スケジュールで起動するルールとイベントパターンのルールは何が違いますか？
put-ruleの--event-patternはイベントの内容で、--schedule-expressionはrate(5 minutes)やcron式の時刻で発火します。定期実行を新しく組むなら、1回限りの実行などに対応したEventBridge Schedulerが向いています。実装はEventBridge SchedulerのAPI｜cron式・手動実行・上限と料金の実装ガイドで解説しました。
関連記事
- Amazon EventBridgeとは？仕組み・料金とCLI・Pythonでの実装手順、新Custom Event Busとの違いを解説【2026年版】：バス・ルール・ターゲットの全体像と最小構成。
- EventBridge Pipesの使い方：DynamoDB Streamsのフィルタとエンリッチ実装：同じ構文をPipesのフィルタで使う場合の違い。
- EventBridgeとSQS・Lambdaの非同期構成｜キューポリシー・部分バッチ応答・DLQの置き場所：パターンで絞ったイベントをSQSとLambdaで受ける設計。
- イベント駆動アーキテクチャとは？仕組み・実装パターンと採用判断を実装者目線で解説：ルールを含む構成全体の考え方。
- Amazon SQSとは？標準キューとFIFOの違い・可視性タイムアウトとDLQ設計を解説：ルールのターゲットに置くキューとDLQの設計。
