CloudWatch Events のイベントパターン
イベントを管理するには、Amazon EventBridge が好ましい方法です。CloudWatch Events と EventBridge は同じ基盤となるサービスと API ですが、EventBridge はより多くの機能を提供します。CloudWatch または EventBridge のいずれかで行った変更は、各コンソールに表示されます。詳細については、Amazon EventBridge を参照してください。 |
Amazon CloudWatch Events のイベントは JSON オブジェクトとして表されます。JSON オブジェクトの詳細については、「RFC 7159
{ "version": "0", "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", "detail-type": "EC2 Instance State-change Notification", "source": "aws.ec2", "account": "111122223333", "time": "2017-12-22T18:43:48Z", "region": "us-west-1", "resources": [ "arn:aws:ec2:us-west-1:123456789012:instance/ i-1234567890abcdef0" ], "detail": { "instance-id": " i-1234567890abcdef0", "state": "terminated" } }
イベントについて以下の詳細を覚えておくことが重要です。
-
上記の例に示しているように、同じ最上位のフィールドがあり、それらは必須です。
-
[detail] の最上位のフィールドの内容は、どのサービスがイベントを生成したか、そのイベントが何であるかによって異なります。[source] フィールドと [detail-type] フィールドの組み合わせは、[detail] フィールドで見つかるフィールドと値を識別するために役立ちます。AWS のサービスによって生成されるイベントの例については、「CloudWatch Events のイベントタイプ」を参照してください。
以下に説明しているのは、各イベントフィールドです。
- バージョン
-
デフォルトでは、これはすべてのイベントで 0(ゼロ)に設定されます。
- id
-
一意の値はすべてのイベントに対して生成されます。これは、イベントがルールからターゲットに移動して処理されるとき、それらのイベントを追跡するために役立ちます。
- detail-type
-
[source] フィールドと組み合わせて、[detail] フィールドに表示されるフィールドと値を識別します。
CloudTrail 経由で送信されたイベントはすべて、
AWS API Call via CloudTrail
の値がdetail-type
になっています。詳細については、「CloudTrail 経由で配信されるイベント」を参照してください。 - source
-
イベントを発生したサービスを識別します。AWS 内から発生するすべてのイベントは「AWS」で始まります。お客様によって生成されたイベントは、「AWS」で始まる場合を除き、任意の値に設定することができます。Java パッケージ名のスタイルには、逆ドメイン名の文字列を使用することをお勧めします。
AWS サービスの
source
の正しい値を見つけるには、「AWS サービスの名前空間」を参照してください。例えば、Amazon CloudFront のsource
値はaws.cloudfront
です。 - account
-
AWS アカウントを識別する 12 桁の数字。
- time
-
イベントを発生したサービスによって指定できるイベントのタイムスタンプ。イベントが時間間隔にまたがる場合、サービスは開始時間をレポートするように選択可能であるため、この値は、イベントが実際に受け取られるより大幅に前の時間になることがあります。
- リージョン
-
イベントが発生した AWS リージョンを識別します。
- リソース
-
この JSON 配列には、イベントにかかわるリソースを識別する ARN が格納されます。これらの ARN を格納するかどうかは、サービスによって異なります。例えば、Amazon EC2 インスタンスの状態変更では、Amazon EC2 インスタンス ARN が格納され、Auto Scaling イベントでは、インスタンスと Auto Scaling グループの両方の ARN が格納されますが、AWS CloudTrail での API コールでは、リソース ARN は格納されません。
- detail
-
JSON オブジェクトであり、その内容はイベントを発生したサービスによって異なります。上記の例の detail の内容は、非常にシンプルな 2 つのフィールドのみです。AWSAPI コールイベントには、約 50 個のフィールドがいく層もの入れ子になった detail オブジェクトあります。
イベントパターン
ルールでは、イベントパターンを使用してイベントを選択し、ターゲットに振り分けます。パターンは、イベントに一致するか、一致しないかのいずれかになります。イベントパターンは、イベントと同様の構造になった JSON オブジェクトとして表されます。たとえば、以下のようになります。
{ "source": [ "aws.ec2" ], "detail-type": [ "EC2 Instance State-change Notification" ], "detail": { "state": [ "running" ] } }
イベントパターンマッチングについて以下を覚えておくことが重要です。
-
パターンがイベントに一致するには、イベントには、パターンに指定されているすべてのフィールド名が含まれている必要があります。フィールド名は、同じ入れ子構造になったイベントに表示されます。
-
パターンに登録されていないイベントの他のフィールドは無視されます。実際には、登録されていないフィールドには "*": "*" ワイルドカードがあります。
-
マッチングは厳密(文字単位)であり、大文字の小文字化など文字列の正規化は行われません。
-
値、つまり、引用符で囲まれた文字列、数字、引用符で囲まれていないキーワード(
true
、false
、null
)は JSON 形式のルールに従ってマッチングが調べられます。 -
数字のマッチングは文字列表現レベルで調べられます。たとえば、300、300.0、3.0e2 は等しいとはみなされません。
イベントと一致するパターンを記述するときは、TestEventPattern
API または test-event-pattern
CLI コマンドを使用して、パターンが目的のイベントと一致することを確認します。詳細については、TestEventPattern または test-event-pattern を参照してください。
以下のイベントパターンは、このページ上部のイベントと一致します。1 つめのパターンは、パターンで指定されているインスタンス値のいずれかがイベントと一致していることから、一致します (イベントに含まれていないその他のフィールドをパターンで指定することはできません)。2 つめのパターンは、「終了」状態がイベントに含まれていることから、一致します。
{ "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-12345678", "arn:aws:ec2:us-east-1:123456789012:instance/i-abcdefgh" ] }
{ "detail": { "state": [ "terminated" ] } }
以下のイベントパターンは、このページの上部のイベントと一致しません。1 つめのパターンは、パターンで「保留」状態を表す値が指定されており、イベントにこの値が表示されていないことから、一致しません。2 つめのパターンは、パターンで指定されているリソース値がイベントに表示されていないことから、一致しません。
{ "source": [ "aws.ec2" ], "detail-type": [ "EC2 Instance State-change Notification" ], "detail": { "state": [ "pending" ] } }
{ "source": [ "aws.ec2" ], "detail-type": [ "EC2 Instance State-change Notification" ], "resources": [ "arn:aws:ec2:us-east-1::image/ami-12345678" ] }
イベントパターンでの Null 値や空の文字列との一致
Null 値や空の文字列を持つイベントフィールドと一致するパターンを作成できます。この仕組みを確認するには、次のイベント例を検討してください。
{ "version": "0", "id": "3e3c153a-8339-4e30-8c35-687ebef853fe", "detail-type": "EC2 Instance Launch Successful", "source": "aws.autoscaling", "account": "123456789012", "time": "2015-11-11T21:31:47Z", "region": "us-east-1", "resources": [ ], "detail": { "eventVersion": "", "responseElements": null } }
eventVersion
の値が空の文字列であるイベントと一致させるには、イベント例と一致する次のパターンを使用します。
{ "detail": { "eventVersion": [""] } }
responseElements
の値が Null であるイベントと一致させるには、イベント例と一致する次のパターンを使用します。
{ "detail": { "responseElements": [null] } }
Null 値および空の文字列は、パターンマッチングで交換可能ではありません。空の文字列を検出するために記述されたパターンは、null
の値をキャッチしません。
CloudWatch Events パターンの配列
パターン内の各フィールドの値は 1 つ以上の値を格納する配列であり、配列の値のいずれかがイベントの値と一致すれば、パターンが一致したとみなされます。イベントの値が配列の場合、パターン配列とイベント配列の交差部分が空でないなら、パターンが一致したとみなされます。
たとえば、イベントパターンの例には次のテキストが含まれています。
"resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-b188560f", "arn:aws:ec2:us-east-1:111122223333:instance/i-b188560f", "arn:aws:ec2:us-east-1:444455556666:instance/i-b188560f", ]
パターンの例は、次のテキストが含まれているイベントに一致します。パターン配列の最初の項目が、イベント配列の 2 番目の項目と一致するためです。
"resources": [ "arn:aws:autoscaling:us-east-1:123456789012:autoScalingGroup:eb56d16b-bbf0-401d-b893-d5978ed4a025:autoScalingGroupName/ASGTerminate", "arn:aws:ec2:us-east-1:123456789012:instance/i-b188560f" ]