class Rule (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.Events.Rule`
Java	`software.amazon.awscdk.services.events.Rule`
Python	`aws_cdk.aws_events.Rule`
TypeScript (source)	`@aws-cdk/aws-events` » `Rule`

Implements IConstruct, IConstruct, IDependable, IResource, IRule

Defines an EventBridge Rule in this stack.

Example

import * as lambda from '@aws-cdk/aws-lambda';

const fn = new lambda.Function(this, 'MyFunc', {
  runtime: lambda.Runtime.NODEJS_14_X,
  handler: 'index.handler',
  code: lambda.Code.fromInline(`exports.handler = handler.toString()`),
});

const rule = new events.Rule(this, 'rule', {
  eventPattern: {
    source: ["aws.ec2"],
  },
});

const queue = new sqs.Queue(this, 'Queue');

rule.addTarget(new targets.LambdaFunction(fn, {
  deadLetterQueue: queue, // Optional: add a dead letter queue
  maxEventAge: cdk.Duration.hours(2), // Optional: set the maxEventAge retry policy
  retryAttempts: 2, // Optional: set the max number of retry attempts
}));

Initializer

new Rule(scope: Construct, id: string, props?: RuleProps)

Parameters

scope Construct
id string
props RuleProps

Construct Props

Name	Type	Description
description?	`string`	A description of the rule's purpose.
enabled?	`boolean`	Indicates whether the rule is enabled.
eventBus?	`IEventBus`	The event bus to associate with this rule.
eventPattern?	`EventPattern`	Describes which events EventBridge routes to the specified target.
ruleName?	`string`	A name for the rule.
schedule?	`Schedule`	The schedule or rate (frequency) that determines when EventBridge runs the rule.
targets?	`IRuleTarget[]`	Targets to invoke when this rule matches an event.

description?

Type: string (optional, default: No description.)

A description of the rule's purpose.

enabled?

Type: boolean (optional, default: true)

Indicates whether the rule is enabled.

eventBus?

Type: IEventBus (optional, default: The default event bus.)

The event bus to associate with this rule.

eventPattern?

Type: EventPattern (optional, default: None.)

Describes which events EventBridge routes to the specified target.

These routed events are matched events. For more information, see Events and Event Patterns in the Amazon EventBridge User Guide.

You must specify this property (either via props or via addEventPattern), the scheduleExpression property, or both. The method addEventPattern can be used to add filter values to the event pattern.](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html

ruleName?

Type: string (optional, default: AWS CloudFormation generates a unique physical ID and uses that ID for the rule name. For more information, see Name Type.)

A name for the rule.

schedule?

Type: Schedule (optional, default: None.)

The schedule or rate (frequency) that determines when EventBridge runs the rule.

For more information, see Schedule Expression Syntax for Rules in the Amazon EventBridge User Guide.

You must specify this property, the eventPattern property, or both.](https://docs.aws.amazon.com/eventbridge/latest/userguide/scheduled-events.html

You must specify this property, the eventPattern property, or both.)

targets?

Type: IRuleTarget[] (optional, default: No 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]).

Properties

Name	Type	Description
env	`ResourceEnvironment`	The environment this resource belongs to.
node	`ConstructNode`	The construct tree node associated with this construct.
ruleArn	`string`	The value of the event rule Amazon Resource Name (ARN), such as arn:aws:events:us-east-2:123456789012:rule/example.
ruleName	`string`	The name event rule.
stack	`Stack`	The stack in which this resource is defined.

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

node

Type: ConstructNode

The construct tree node associated with this construct.

ruleArn

Type: string

The value of the event rule Amazon Resource Name (ARN), such as arn:aws:events:us-east-2:123456789012:rule/example.

ruleName

Type: string

The name event rule.

stack

Type: Stack

The stack in which this resource is defined.

Methods

Name	Description
addEventPattern(eventPattern?)	Adds an event pattern filter to this rule.
addTarget(target?)	Adds a target to the rule. The abstract class RuleTarget can be extended to define new targets.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
toString()	Returns a string representation of this construct.
protected validate()	Validate the current construct.
static fromEventRuleArn(scope, id, eventRuleArn)	Import an existing EventBridge Rule provided an ARN.

addEventPattern(eventPattern?)

public addEventPattern(eventPattern?: EventPattern): void

Parameters

eventPattern 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" ]
  }
}

addTarget(target?)

public addTarget(target?: IRuleTarget): void

Parameters

target IRuleTarget

Adds a target to the rule. The abstract class RuleTarget can be extended to define new targets.

No-op if target is undefined.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

toString()

public toString(): string

Returns

string

Returns a string representation of this construct.

protected validate()

protected validate(): string[]

Returns

string[]

Validate the current construct.

This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.

static fromEventRuleArn(scope, id, eventRuleArn)

public static fromEventRuleArn(scope: Construct, id: string, eventRuleArn: string): IRule

Parameters

scope Construct — The parent creating construct (usually this).
id string — The construct's name.
eventRuleArn string — Event Rule ARN (i.e. arn:aws:events::<account-id>:rule/MyScheduledRule).

Returns

IRule

Import an existing EventBridge Rule provided an ARN.