Rule

class aws_cdk.aws_events.Rule(scope, id, *, enabled=None, event_bus=None, schedule=None, targets=None, cross_stack_scope=None, description=None, event_pattern=None, rule_name=None)

Bases: Resource

Defines an EventBridge Rule in this stack.

Resource:: AWS::Events::Rule
ExampleMetadata:: infused

Example:

import aws_cdk.aws_lambda as lambda_


fn = lambda_.Function(self, "MyFunc",
    runtime=lambda_.Runtime.NODEJS_LATEST,
    handler="index.handler",
    code=lambda_.Code.from_inline("exports.handler = handler.toString()")
)

rule = events.Rule(self, "rule",
    event_pattern=events.EventPattern(
        source=["aws.ec2"]
    )
)

queue = sqs.Queue(self, "Queue")

rule.add_target(targets.LambdaFunction(fn,
    dead_letter_queue=queue,  # Optional: add a dead letter queue
    max_event_age=Duration.hours(2),  # Optional: set the maxEventAge retry policy
    retry_attempts=2
))

Parameters:

scope (Construct) –
id (str) –
enabled (Optional[bool]) – Indicates whether the rule is enabled. Default: true
event_bus (Optional[IEventBus]) – The event bus to associate with this rule. Default: - The default event bus.
schedule (Optional[Schedule]) – The schedule or rate (frequency) that determines when EventBridge runs the rule. You must specify this property, the eventPattern property, or both. For more information, see Schedule Expression Syntax for Rules in the Amazon EventBridge User Guide. Default: - None.
targets (Optional[Sequence[IRuleTarget]]) – 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]). Default: - No targets.
cross_stack_scope (Optional[Construct]) – The scope to use if the source of the rule and its target are in different Stacks (but in the same account & region). This helps dealing with cycles that often arise in these situations. Default: - none (the main scope will be used, even for cross-stack Events)
description (Optional[str]) – A description of the rule’s purpose. Default: - No description
event_pattern (Union[EventPattern, Dict[str, Any], None]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.
rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

Methods

add_event_pattern(*, account=None, detail=None, detail_type=None, id=None, region=None, resources=None, source=None, time=None, version=None)

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:

account (Optional[Sequence[str]]) – The 12-digit number identifying an AWS account. Default: - No filtering on account
detail (Optional[Mapping[str, Any]]) – A JSON object, whose content is at the discretion of the service originating the event. Default: - No filtering on detail
detail_type (Optional[Sequence[str]]) – Identifies, in combination with the source field, the fields and values that appear in the detail field. Represents the “detail-type” event field. Default: - No filtering on detail type
id (Optional[Sequence[str]]) – 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. Default: - No filtering on id
region (Optional[Sequence[str]]) – Identifies the AWS region where the event originated. Default: - No filtering on region
resources (Optional[Sequence[str]]) – 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. Default: - No filtering on resource
source (Optional[Sequence[str]]) – 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. Default: - No filtering on source
time (Optional[Sequence[str]]) – 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. Default: - No filtering on time
version (Optional[Sequence[str]]) – By default, this is set to 0 (zero) in all events. Default: - No filtering on version

Return type:

None

add_target(target=None)

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 (Optional[IRuleTarget]) –

Return type:

None

apply_removal_policy(policy)

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

Parameters:

policy (RemovalPolicy) –

Return type:

None

to_string()

Returns a string representation of this construct.

Return type:: str

Attributes

env

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: The tree node.

rule_arn

events:us-east-2:123456789012:rule/example.

Type:: The value of the event rule Amazon Resource Name (ARN), such as arn
Type:: aws

rule_name: The name event rule.

stack: The stack in which this resource is defined.

Static Methods

classmethod from_event_rule_arn(scope, id, event_rule_arn)

Import an existing EventBridge Rule provided an ARN.

Parameters:

scope (Construct) – The parent creating construct (usually this).
id (str) – The construct’s name.
event_rule_arn (str) – Event Rule ARN (i.e. arn:aws:events:::rule/MyScheduledRule).

Return type:

IRule

classmethod is_construct(x)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters:: x (Any) – Any object.
Return type:: bool
Returns:: true if x is an object created from a class which extends Construct.

classmethod is_owned_resource(construct)

Returns true if the construct was created by CDK, and false otherwise.

Parameters:

construct (IConstruct) –

Return type:

bool

classmethod is_resource(construct)

Check whether the given construct is a Resource.

Parameters:

construct (IConstruct) –

Return type:

bool