-
Interface Summary Interface Description CfnEventBusPolicy.ConditionProperty CfnEventBusPolicyProps Properties for defining a `AWS::Events::EventBusPolicy`.CfnEventBusProps Properties for defining a `AWS::Events::EventBus`.CfnRule.AwsVpcConfigurationProperty CfnRule.BatchArrayPropertiesProperty CfnRule.BatchParametersProperty CfnRule.BatchRetryStrategyProperty CfnRule.EcsParametersProperty CfnRule.InputTransformerProperty CfnRule.KinesisParametersProperty CfnRule.NetworkConfigurationProperty CfnRule.RunCommandParametersProperty CfnRule.RunCommandTargetProperty CfnRule.SqsParametersProperty CfnRule.TargetProperty CfnRuleProps Properties for defining a `AWS::Events::Rule`.CronOptions Options to configure a cron expression.EventBusAttributes Interface with properties necessary to import a reusable EventBus.EventBusProps Properties to define an event bus.EventPattern Events in Amazon CloudWatch Events are represented as JSON objects.IEventBus Interface which all EventBus based classes MUST implement.IRule IRuleTarget An abstract target for EventRules.OnEventOptions Standard set of options for `onXxx` event handlers on construct.RuleProps RuleTargetConfig Properties for an event rule target.RuleTargetInputProperties The input properties for an event target.
Package software.amazon.awscdk.services.events Description
Amazon 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.
- EventBuses: An event bus can receive events from your own custom applications or it can receive events from applications and services created by AWS SaaS partners. See Creating an Event Bus.
Rule
The Rule 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 IRuleTarget interface.
Normally, you will use one of the source.onXxx(name[, target[, options]]) -> Rule 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:
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var onCommitRule = repo.onCommit("OnCommit", Map.of(
"target", new CodeBuildProject(project),
"branches", asList("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:
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
onCommitRule.addTarget(SnsTopic.Builder.create(topic)
.message(events.RuleTargetInput.fromText("A commit was pushed to the repository " + codecommit.ReferenceEvent.repositoryName + " on branch " + codecommit.ReferenceEvent.referenceName))
.build());
Scheduling
You can configure a Rule to run on a schedule (cron or rate).
The following example runs a task every day at 4am:
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import software.amazon.awscdk.services.events.Rule;
import software.amazon.awscdk.services.events.Schedule;
import software.amazon.awscdk.services.events.targets.EcsTask;
EcsTask ecsTaskTarget = new EcsTask(new EcsTaskProps().cluster(cluster).taskDefinition(taskDefinition));
new Rule(this, "ScheduleRule", new RuleProps()
.schedule(Schedule.cron(new CronOptions().minute("0").hour("4")))
.targets(asList(ecsTaskTarget)));
More details in ScheduledEvents documentation page.
Event Targets
The @aws-cdk/aws-events-targets module includes classes that implement the IRuleTarget
interface for various AWS services.
The following targets are supported:
targets.CodeBuildProject: Start an AWS CodeBuild buildtargets.CodePipeline: Start an AWS CodePipeline pipeline executiontargets.EcsTask: Start a task on an Amazon ECS clustertargets.LambdaFunction: Invoke an AWS Lambda functiontargets.SnsTopic: Publish into an SNS topictargets.SqsQueue: Send a message to an Amazon SQS Queuetargets.SfnStateMachine: Trigger an AWS Step Functions state machinetargets.BatchJob: Queue an AWS Batch Jobtargets.AwsApi: Make an AWS API call
Cross-account targets
It's possible to have the source of the event and a target in separate AWS accounts:
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import software.amazon.awscdk.core.App;
import software.amazon.awscdk.core.Stack;
import software.amazon.awscdk.services.codebuild.*;
import software.amazon.awscdk.services.codecommit.*;
import software.amazon.awscdk.services.events.targets.*;
App app = new App();
Stack stack1 = new Stack(app, "Stack1", new StackProps().env(new Environment().account(account1).region("us-east-1")));
Repository repo = new Repository(stack1, "Repository", new RepositoryProps());
Stack stack2 = new Stack(app, "Stack2", new StackProps().env(new Environment().account(account2).region("us-east-1")));
Project project = new Project(stack2, "Project", new ProjectProps());
repo.onCommit("OnCommit", new OnCommitOptions()
.target(new CodeBuildProject(project)));
In this situation, the CDK will wire the 2 accounts together:
- It will generate a rule in the source stack with the event bus of the target account as the target
- It will generate a rule in the target stack, with the provided target
- It will generate a separate stack that gives the source account permissions to publish events to the event bus of the target account in the given region, and make sure its deployed before the source stack
Note: while events can span multiple accounts, they cannot span different regions (that is a CloudWatch, not CDK, limitation).
For more information, see the AWS documentation on cross-account events.