@aws-cdk/events¶
AWS CloudWatch Events Construct Library¶
Amazon CloudWatch Events delivers a near real-time stream of system events that describe changes in AWS resources. For example, an AWS CodePipeline emits the State Change event when the pipeline changes it’s state.
- Events: An event indicates a change in your AWS environment. AWS resources can generate events when their state changes. For example, Amazon EC2 generates an event when the state of an EC2 instance changes from pending to running, and Amazon EC2 Auto Scaling generates events when it launches or terminates instances. AWS CloudTrail publishes events when you make API calls. You can generate custom application-level events and publish them to CloudWatch Events. You can also set up scheduled events that are generated on a periodic basis. For a list of services that generate events, and sample events from each service, see CloudWatch Events Event Examples From Each Supported Service.
- Targets: A target processes events. Targets can include Amazon EC2 instances, AWS Lambda functions, Kinesis streams, Amazon ECS tasks, Step Functions state machines, Amazon SNS topics, Amazon SQS queues, and built-in targets. A target receives events in JSON format.
- Rules: A rule matches incoming events and routes them to targets for processing. A single rule can route to multiple targets, all of which are processed in parallel. Rules are not processed in a particular order. This enables different parts of an organization to look for and process the events that are of interest to them. A rule can customize the JSON sent to the target, by passing only certain parts or by overwriting it with a constant.
The EventRule
construct defines a CloudWatch events rule which monitors an
event based on an event
pattern
and invoke event targets when the pattern is matched against a triggered
event. Event targets are objects that implement the IEventTarget
interface.
Normally, you will use one of the source.onXxx(name[, target[, options]]) ->
EventRule
methods on the event source to define an event rule associated with
the specific activity. You can targets either via props, or add targets using
rule.addTarget
.
For example, to define an rule that triggers a CodeBuild project build when a commit is pushed to the “master” branch of a CodeCommit repository:
const onCommitRule = repo.onCommit('OnCommitToMaster', buildProject, 'master');
You can add additional targets, with optional input
transformer
using eventRule.addTarget(target[, input])
. For example, we can add a SNS
topic target which formats a human-readable message for the commit.
For example, this adds an SNS topic as a target:
onCommitRule.addTarget(topic, {
template: 'A commit was pushed to the repository <repo> on branch <branch>',
pathsMap: {
branch: '$.detail.referenceName',
repo: '$.detail.repositoryName'
}
});
Reference¶
EventPattern (interface)¶
-
class
_aws-cdk_events.
EventPattern
¶ Events in Amazon CloudWatch Events are represented as JSON objects. For more information about JSON objects, see RFC 7159. Rules use event patterns to select events and route them to targets. A pattern either matches an event or it doesn’t. Event patterns are represented as JSON objects with a structure that is similar to that of events, for example: It is important to remember the following about event pattern matching: - For a pattern to match an event, the event must contain all the field names listed in the pattern. The field names must appear in the event with the same nesting structure. - Other fields of the event not mentioned in the pattern are ignored; effectively, there is a
"*": "*"
wildcard for fields not mentioned. - The matching is exact (character-by-character), without case-folding or any other string normalization. - The values being matched follow JSON rules: Strings enclosed in quotes, numbers, and the unquoted keywords true, false, and null. - Number matching is at the string representation level. For example, 300, 300.0, and 3.0e2 are not considered equal.-
version
¶ By default, this is set to 0 (zero) in all events.
Type: string or None
-
id
¶ A unique value is generated for every event. This can be helpful in tracing events as they move through rules to targets, and are processed.
Type: string or None
-
detailType
¶ Identifies, in combination with the source field, the fields and values that appear in the detail field. Represents the “detail-type” event field.
Type: string or None
-
source
¶ Identifies the service that sourced the event. All events sourced from within AWS begin with “aws.” Customer-generated events can have any value here, as long as it doesn’t begin with “aws.” We recommend the use of Java package-name style reverse domain-name strings. To find the correct value for source for an AWS service, see the table in AWS Service Namespaces. For example, the source value for Amazon CloudFront is aws.cloudfront.
Type: string or None
-
account
¶ The 12-digit number identifying an AWS account.
Type: string or None
-
time
¶ The event timestamp, which can be specified by the service originating the event. If the event spans a time interval, the service might choose to report the start time, so this value can be noticeably before the time the event is actually received.
Type: string or None
-
region
¶ Identifies the AWS region where the event originated.
Type: string or None
-
resources
¶ This JSON array contains ARNs that identify resources that are involved in the event. Inclusion of these ARNs is at the discretion of the service. For example, Amazon EC2 instance state-changes include Amazon EC2 instance ARNs, Auto Scaling events include ARNs for both instances and Auto Scaling groups, but API calls with AWS CloudTrail do not include resource ARNs.
Type: Arn
or None
-
detail
¶ A JSON object, whose content is at the discretion of the service originating the event.
Type: any or None
-
EventRule¶
-
class
_aws-cdk_events.
EventRule
(parent, name[, props])¶ Defines a CloudWatch Event Rule in this stack.
Extends: EventRuleRef
Parameters: - parent (
Construct
) – - name (string) –
- props (
EventRuleProps
or None) –
-
addTarget
([target[, inputOptions]])¶ Adds a target to the rule. The abstract class RuleTarget can be extended to define new targets. No-op if target is undefined.
Parameters: - target (
IEventRuleTarget
or None) – - inputOptions (
TargetInputTemplate
or None) –
- target (
-
addEventPattern
([eventPattern])¶ Adds an event pattern filter to this rule. If a pattern was already specified, these values are merged into the existing pattern. For example, if the rule already contains the pattern: { “resources”: [ “r1” ], “detail”: { “hello”: [ 1 ] } } And addEventPattern is called with the pattern: { “resources”: [ “r2” ], “detail”: { “foo”: [ “bar” ] } } The resulting event pattern will be: { “resources”: [ “r1”, “r2” ], “detail”: { “hello”: [ 1 ], “foo”: [ “bar” ] } }
Parameters: eventPattern ( EventPattern
or None) –
-
validate
() → string[]¶ This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.
Return type: string
-
ruleArn
¶ The value of the event rule Amazon Resource Name (ARN), such as arn:aws:events:us-east-2:123456789012:rule/example.
Type: RuleArn
- parent (
EventRuleProps (interface)¶
-
class
_aws-cdk_events.
EventRuleProps
¶ -
description
¶ A description of the rule’s purpose.
Type: string or None
-
ruleName
¶ A name for the rule. If you don’t specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the rule name. For more information, see Name Type.
Type: string or None
-
enabled
¶ Indicates whether the rule is enabled.
Type: boolean or None
-
scheduleExpression
¶ The schedule or rate (frequency) that determines when CloudWatch Events runs the rule. For more information, see Schedule Expression Syntax for Rules in the Amazon CloudWatch User Guide.
Type: string or None
-
eventPattern
¶ Describes which events CloudWatch Events routes to the specified target. These routed events are matched events. For more information, see Events and Event Patterns in the Amazon CloudWatch User Guide.
Type: EventPattern
or None
-
targets
¶ Targets to invoke when this rule matches an event. Input will be the full matched event. If you wish to specify custom target input, use addTarget(target[, inputOptions]).
Type: IEventRuleTarget
or None
-
EventRuleRef¶
-
class
_aws-cdk_events.
EventRuleRef
(parent, name)¶ Extends: Construct
Abstract: Yes
Parameters: - parent (
Construct
) – The parent construct - name (string) –
-
static
import
(parent, name, props) → @aws-cdk/events.EventRuleRef¶ Imports a rule by ARN into this stack.
Parameters: - parent (
Construct
) – - name (string) –
- props (
EventRuleRefProps
) –
Return type: EventRuleRef
- parent (
-
export
() → @aws-cdk/events.EventRuleRefProps¶ Exports this rule resource from this stack and returns an import token.
Return type: EventRuleRefProps
-
ruleArn
¶ The value of the event rule Amazon Resource Name (ARN), such as arn:aws:events:us-east-2:123456789012:rule/example.
Type: RuleArn
(readonly) (abstract)
- parent (
EventRuleRefProps (interface)¶
EventRuleTarget (interface)¶
-
class
_aws-cdk_events.
EventRuleTarget
¶ -
id
¶ A unique, user-defined identifier for the target. Acceptable values include alphanumeric characters, periods (.), hyphens (-), and underscores (_).
Type: string
-
arn
¶ The Amazon Resource Name (ARN) of the target.
Type: Arn
-
roleArn
¶ The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role to use for this target when the rule is triggered. If one rule triggers multiple targets, you can use a different IAM role for each target.
Type: RoleArn
or None
-
ecsParameters
¶ The Amazon ECS task definition and task count to use, if the event target is an Amazon ECS task.
Type: EcsParametersProperty
or None
-
kinesisParameters
¶ Settings that control shard assignment, when the target is a Kinesis stream. If you don’t include this parameter, eventId is used as the partition key.
Type: KinesisParametersProperty
or None
-
runCommandParameters
¶ Parameters used when the rule invokes Amazon EC2 Systems Manager Run Command.
Type: RunCommandParametersProperty
or None
-
IEventRuleTarget (interface)¶
TargetInputTemplate (interface)¶
-
class
_aws-cdk_events.
TargetInputTemplate
¶ Specifies settings that provide custom input to an Amazon CloudWatch Events rule target based on certain event data.
-
textTemplate
¶ Input template where you can use the values of the keys from inputPathsMap to customize the data sent to the target. Enclose each InputPathsMaps value in brackets: <value> The value passed here will be double-quoted to indicate it’s a string value. This option is mutually exclusive with jsonTemplate.
Type: any or None
-
jsonTemplate
¶ Input template where you can use the values of the keys from inputPathsMap to customize the data sent to the target. Enclose each InputPathsMaps value in brackets: <value> This option is mutually exclusive with textTemplate.
Type: any or None
-
pathsMap
¶ Map of JSON paths to be extracted from the event. These are key-value pairs, where each value is a JSON path. You must use JSON dot notation, not bracket notation.
Type: string or None
-