Debian Codegraph @

docs/source/guide/cw-example-events.rst

raw
1 .. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2
3 This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4 International License (the "License"). You may not use this file except in compliance with the
5 License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6
7 This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8 either express or implied. See the License for the specific language governing permissions and
9 limitations under the License.
10
11 .. _aws-boto3-cw-events:
12
13 ##########################################
14 Sending events to Amazon CloudWatch Events
15 ##########################################
16
17 This Python example shows you how to:
18
19 * Create and update a rule used to trigger an event
20
21 * Define one or more targets to respond to an event
22
23 * Send events that are matched to targets for handling
24
25 The scenario
26 ============
27
28 CloudWatch Events delivers a near real-time stream of system events that describe changes in
29 Amazon Web Services (AWS) resources to any of various targets. Using simple rules, you can match
30 events and route them to one or more target functions or streams.
31
32 In this example, Python code is used to send events to CloudWatch Events. The code uses the
33 AWS SDK for Python to manage instances using these methods of the CloudWatchEvents client class:
34
35 * `put_rule <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/events.html#CloudWatchEvents.Client.put_rule>`_.
36
37 * `put_targets <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/events.html#CloudWatchEvents.Client.put_targets>`_.
38
39 * `put_events <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/events.html#CloudWatchEvents.Client.put_events>`_.
40
41 For more information about CloudWatch Events, see
42 `Adding Events with PutEvents <http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/AddEventsPutEvents.html>`_
43 in the *Amazon CloudWatch Events User Guide*.
44
45 All the example code for the Amazon Web Services (AWS) SDK for Python is available `here on GitHub <https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/python/example_code>`_.
46
47 Prerequisite tasks
48 =================
49
50 * Configure your AWS credentials, as described in :doc:`quickstart`.
51
52 * Create a Lambda function using the **hello-world** blueprint to serve as the target for events. To
53 learn how, see `Step 1: Create an AWS Lambda function <http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/LogEC2InstanceState.html>`_
54 in the *Amazon CloudWatch Events User Guide*.
55
56 * Create an IAM role whose policy grants permission to CloudWatch Events and that includes :code:`events.amazonaws.com`
57 as a trusted entity. For more information about creating an IAM role, see
58 `Creating a Role to Delegate Permissions to an AWS Service <http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html>`_
59 in the *IAM User Guide*.
60
61 Use the following role policy when creating the IAM role.
62
63 .. code-block:: python
64
65 {
66 "Version": "2012-10-17",
67 "Statement": [
68 {
69 "Sid": "CloudWatchEventsFullAccess",
70 "Effect": "Allow",
71 "Action": "events:*",
72 "Resource": "*"
73 },
74 {
75 "Sid": "IAMPassRoleForCloudWatchEvents",
76 "Effect": "Allow",
77 "Action": "iam:PassRole",
78 "Resource": "arn:aws:iam::*:role/AWS_Events_Invoke_Targets"
79 }
80 ]
81 }
82
83 Use the following trust relationship when creating the IAM role.
84
85 .. code-block:: python
86
87 {
88 "Version": "2012-10-17",
89 "Statement": [
90 {
91 "Effect": "Allow",
92 "Principal": {
93 "Service": "events.amazonaws.com"
94 },
95 "Action": "sts:AssumeRole"
96 }
97 ]
98 }
99
100
101 Create a scheduled rule
102 =======================
103
104 Create or update the specified rule. Rules are enabled by default, or based on value of the state.
105 You can disable a rule using `DisableRule <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/events.html#CloudWatchEvents.Client.disable_rule>`_.
106
107 The example below shows how to:
108
109 * Create a CloudWatch Events rule using
110 `put_rule <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/events.html#CloudWatchEvents.Client.put_rule>`_.
111
112
113 Example
114 -------
115
116 .. code-block:: python
117
118 import boto3
119
120
121 # Create CloudWatchEvents client
122 cloudwatch_events = boto3.client('events')
123
124 # Put an event rule
125 response = cloudwatch_events.put_rule(
126 Name='DEMO_EVENT',
127 RoleArn='IAM_ROLE_ARN',
128 ScheduleExpression='rate(5 minutes)',
129 State='ENABLED'
130 )
131 print(response['RuleArn'])
132
133
134 Add an AWS Lambda function target
135 =================================
136
137 Add the specified targets to the specified rule, or update the targets if they are already
138 associated with the rule.
139
140 The example below shows how to:
141
142 * Add a target to a rule using
143 `put_targets <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/events.html#CloudWatchEvents.Client.put_targets>`_.
144
145
146 Example
147 -------
148
149 .. code-block:: python
150
151 import boto3
152
153 # Create CloudWatchEvents client
154 cloudwatch_events = boto3.client('events')
155
156 # Put target for rule
157 response = cloudwatch_events.put_targets(
158 Rule='DEMO_EVENT',
159 Targets=[
160 {
161 'Arn': 'LAMBDA_FUNCTION_ARN',
162 'Id': 'myCloudWatchEventsTarget',
163 }
164 ]
165 )
166 print(response)
167
168
169 Send events
170 ===========
171
172 Send custom events to Amazon CloudWatch Events so that they can be matched to rules.
173
174 The example below shows how to:
175
176 * Send a custom event to CloudWatch Events using
177 `put_events <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/events.html#CloudWatchEvents.Client.put_events>`_.
178
179 Example
180 -------
181
182 .. code-block:: python
183
184 import json
185
186 import boto3
187
188
189 # Create CloudWatchEvents client
190 cloudwatch_events = boto3.client('events')
191
192 # Put an event
193 response = cloudwatch_events.put_events(
194 Entries=[
195 {
196 'Detail': json.dumps({'key1': 'value1', 'key2': 'value2'}),
197 'DetailType': 'appRequestSubmitted',
198 'Resources': [
199 'RESOURCE_ARN',
200 ],
201 'Source': 'com.company.myapp'
202 }
203 ]
204 )
205 print(response['Entries'])
206
207