Skip navigation links

Package software.amazon.awscdk.services.events

Amazon EventBridge Construct Library

See: Description

Package software.amazon.awscdk.services.events Description

Amazon EventBridge Construct Library

---

cfn-resources: Stable

cdk-constructs: Stable

Amazon EventBridge 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 its state.

Rule

The Rule construct defines an EventBridge 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
 Object 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(String.format("A commit was pushed to the repository %s on branch %s", codecommit.ReferenceEvent.getRepositoryName(), codecommit.ReferenceEvent.getReferenceName())))
         .build());

Scheduling

You can configure a Rule to run on a schedule (cron or rate). Rate must be specified in minutes, hours or days.

The following example runs a task every day at 4am: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import aws.cdk.lib.aws.events.Rule;
 import aws.cdk.lib.aws.events.Schedule;
 import aws.cdk.lib.aws.events.targets.EcsTask;
 
 
 EcsTask ecsTaskTarget = new EcsTask(new EcsTaskProps().cluster(cluster).taskDefinition(taskDefinition).role(role));
 
 new Rule(this, "ScheduleRule", new RuleProps()
         .schedule(Schedule.cron(new CronOptions().minute("0").hour("4")))
         .targets(asList(ecsTaskTarget)));

If you want to specify Fargate platform version, set platformVersion in EcsTask's props like the following example: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object platformVersion = ecs.FargatePlatformVersion.getVERSION1_4();
 Object ecsTaskTarget = EcsTask.Builder.create().cluster(cluster).taskDefinition(taskDefinition).role(role).platformVersion(platformVersion).build();

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:

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.App;
 import software.amazon.awscdk.Stack;
 import software.amazon.awscdk.aws_codebuild;
 import software.amazon.awscdk.aws_codecommit;
 import software.amazon.awscdk.aws_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:

Note: while events can span multiple accounts, they cannot span different regions (that is an EventBridge, not CDK, limitation).

For more information, see the AWS documentation on cross-account events.

Archiving

It is possible to archive all or some events sent to an event bus. It is then possible to replay these events. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.*;
 
 
 Object stack = new stack();
 
 Object bus = EventBus.Builder.create(stack, "bus")
         .eventBusName("MyCustomEventBus")
         .build();
 
 bus.archive("MyArchive", Map.of(
         "archiveName", "MyCustomEventBusArchive",
         "description", "MyCustomerEventBus Archive",
         "eventPattern", Map.of(
                 "account", asList(stack.getAccount())),
         "retention", cdk.Duration.days(365)));

Granting PutEvents to an existing EventBus

To import an existing EventBus into your CDK application, use EventBus.fromEventBusArn or EventBus.fromEventBusAttributes factory method.

Then, you can use the grantPutEventsTo method to grant event:PutEvents to the eventBus. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object eventBus = EventBus.fromEventBusArn(this, "ImportedEventBus", "arn:aws:events:us-east-1:111111111:event-bus/my-event-bus");
 
 // now you can just call methods on the eventbus
 eventBus.grantPutEventsTo(lambdaFunction);
Skip navigation links

Copyright © 2021. All rights reserved.