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.

See also: [https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html

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

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.)

---

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.

See also: [https://docs.aws.amazon.com/eventbridge/latest/userguide/scheduled-events.html

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.