Menu
 

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.

If you are updating an existing rule, the rule is completely replaced with what you specify in this PutRule command. If you omit arguments in PutRule, the old values for those arguments are not kept. Instead, they are replaced with null values.

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 triggers 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. For more information, see Events and Event Patterns in the Amazon CloudWatch Events User Guide.

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 * * ? *)" or "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"
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: