Menu
Amazon CloudWatch Events
API Reference (API Version 2015-10-07)

PutRule

Creates or updates the specified rule. Rules are enabled by default, or based on value of the state. You can disable a rule using DisableRule.

When you create or update a rule, incoming events might not immediately start matching to new or updated rules. Please allow a short period of time for changes to take effect.

A rule must contain at least an EventPattern or ScheduleExpression. Rules with EventPatterns are triggered when a matching event is observed. Rules with ScheduleExpressions self-trigger based on the given schedule. A rule can have both an EventPattern and a ScheduleExpression, in which case the rule will trigger on matching events as well as on a schedule.

Most services in AWS treat : or / as the same character in Amazon Resource Names (ARNs). However, CloudWatch Events uses an exact match in event patterns and rules. Be sure to use the correct ARN characters when creating event patterns so that they match the ARN syntax in the event you want to match.

Request Syntax

{
   "Description": "string",
   "EventPattern": "string",
   "Name": "string",
   "RoleArn": "string",
   "ScheduleExpression": "string",
   "State": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Description

A description of the rule.

Type: String

Length Constraints: Maximum length of 512.

Required: No

EventPattern

The event pattern.

Type: String

Length Constraints: Maximum length of 2048.

Required: No

Name

The name of the rule that you are creating or updating.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [\.\-_A-Za-z0-9]+

Required: Yes

RoleArn

The Amazon Resource Name (ARN) of the IAM role associated with the rule.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

Required: No

ScheduleExpression

The scheduling expression. For example, "cron(0 20 * * ? *)", "rate(5 minutes)".

Type: String

Length Constraints: Maximum length of 256.

Required: No

State

Indicates whether the rule is enabled or disabled.

Type: String

Valid Values: ENABLED | DISABLED

Required: No

Response Syntax

{
   "RuleArn": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

RuleArn

The Amazon Resource Name (ARN) of the rule.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

Errors

For information about the errors that are common to all actions, see Common Errors.

ConcurrentModificationException

There is concurrent modification on a rule or target.

HTTP Status Code: 400

InternalException

This exception occurs due to unexpected causes.

HTTP Status Code: 500

InvalidEventPatternException

The event pattern is not valid.

HTTP Status Code: 400

LimitExceededException

You tried to create more rules or add more targets to a rule than is allowed.

HTTP Status Code: 400

Example

Creates a rule named "test" that matches events from Amazon EC2

The following is an example of a PutRule request and response.

Sample Request

POST / HTTP/1.1
Host: events.<region>.<domain>
x-amz-Date: <Date>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive 
X-Amz-Target: AWSEvents.PutRule

{
    "Name": "test", 
    "EventPattern": "{ \"source\": [\"aws.ec2\"] }" 
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>

{
    "RuleArn": "arn:aws:events:us-east-1:123456789012:rule/test"
}