1 | # Amazon Simple Notification Service Construct Library
|
2 |
|
3 |
|
4 | ---
|
5 |
|
6 | ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
|
7 |
|
8 | ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
|
9 |
|
10 | ---
|
11 |
|
12 |
|
13 |
|
14 | Add an SNS Topic to your stack:
|
15 |
|
16 | ```ts
|
17 | const topic = new sns.Topic(this, 'Topic', {
|
18 | displayName: 'Customer subscription topic',
|
19 | });
|
20 | ```
|
21 |
|
22 | Add a FIFO SNS topic with content-based de-duplication to your stack:
|
23 |
|
24 | ```ts
|
25 | const topic = new sns.Topic(this, 'Topic', {
|
26 | contentBasedDeduplication: true,
|
27 | displayName: 'Customer subscription topic',
|
28 | fifo: true,
|
29 | topicName: 'customerTopic',
|
30 | });
|
31 | ```
|
32 |
|
33 | Note that FIFO topics require a topic name to be provided. The required `.fifo` suffix will be automatically added to the topic name if it is not explicitly provided.
|
34 |
|
35 | ## Subscriptions
|
36 |
|
37 | Various subscriptions can be added to the topic by calling the
|
38 | `.addSubscription(...)` method on the topic. It accepts a *subscription* object,
|
39 | default implementations of which can be found in the
|
40 | `@aws-cdk/aws-sns-subscriptions` package:
|
41 |
|
42 | Add an HTTPS Subscription to your topic:
|
43 |
|
44 | ```ts
|
45 | const myTopic = new sns.Topic(this, 'MyTopic');
|
46 |
|
47 | myTopic.addSubscription(new subscriptions.UrlSubscription('https://foobar.com/'));
|
48 | ```
|
49 |
|
50 | Subscribe a queue to the topic:
|
51 |
|
52 | ```ts
|
53 | declare const queue: sqs.Queue;
|
54 | const myTopic = new sns.Topic(this, 'MyTopic');
|
55 |
|
56 | myTopic.addSubscription(new subscriptions.SqsSubscription(queue));
|
57 | ```
|
58 |
|
59 | Note that subscriptions of queues in different accounts need to be manually confirmed by
|
60 | reading the initial message from the queue and visiting the link found in it.
|
61 |
|
62 | ### Filter policy
|
63 |
|
64 | A filter policy can be specified when subscribing an endpoint to a topic.
|
65 |
|
66 | Example with a Lambda subscription:
|
67 |
|
68 | ```ts
|
69 | import * as lambda from '@aws-cdk/aws-lambda';
|
70 |
|
71 | const myTopic = new sns.Topic(this, 'MyTopic');
|
72 | declare const fn: lambda.Function;
|
73 |
|
74 | // Lambda should receive only message matching the following conditions on attributes:
|
75 | // color: 'red' or 'orange' or begins with 'bl'
|
76 | // size: anything but 'small' or 'medium'
|
77 | // price: between 100 and 200 or greater than 300
|
78 | // store: attribute must be present
|
79 | myTopic.addSubscription(new subscriptions.LambdaSubscription(fn, {
|
80 | filterPolicy: {
|
81 | color: sns.SubscriptionFilter.stringFilter({
|
82 | allowlist: ['red', 'orange'],
|
83 | matchPrefixes: ['bl'],
|
84 | }),
|
85 | size: sns.SubscriptionFilter.stringFilter({
|
86 | denylist: ['small', 'medium'],
|
87 | }),
|
88 | price: sns.SubscriptionFilter.numericFilter({
|
89 | between: { start: 100, stop: 200 },
|
90 | greaterThan: 300,
|
91 | }),
|
92 | store: sns.SubscriptionFilter.existsFilter(),
|
93 | },
|
94 | }));
|
95 | ```
|
96 |
|
97 | ### Example of Firehose Subscription
|
98 |
|
99 | ```ts
|
100 | import { DeliveryStream } from '@aws-cdk/aws-kinesisfirehose';
|
101 |
|
102 | const topic = new sns.Topic(this, 'Topic');
|
103 | declare const stream: DeliveryStream;
|
104 |
|
105 | new sns.Subscription(this, 'Subscription', {
|
106 | topic,
|
107 | endpoint: stream.deliveryStreamArn,
|
108 | protocol: sns.SubscriptionProtocol.FIREHOSE,
|
109 | subscriptionRoleArn: "SAMPLE_ARN", //role with permissions to send messages to a firehose delivery stream
|
110 | });
|
111 | ```
|
112 |
|
113 | ## DLQ setup for SNS Subscription
|
114 |
|
115 | CDK can attach provided Queue as DLQ for your SNS subscription.
|
116 | See the [SNS DLQ configuration docs](https://docs.aws.amazon.com/sns/latest/dg/sns-configure-dead-letter-queue.html) for more information about this feature.
|
117 |
|
118 | Example of usage with user provided DLQ.
|
119 |
|
120 | ```ts
|
121 | const topic = new sns.Topic(this, 'Topic');
|
122 | const dlQueue = new sqs.Queue(this, 'DeadLetterQueue', {
|
123 | queueName: 'MySubscription_DLQ',
|
124 | retentionPeriod: Duration.days(14),
|
125 | });
|
126 |
|
127 | new sns.Subscription(this, 'Subscription', {
|
128 | endpoint: 'endpoint',
|
129 | protocol: sns.SubscriptionProtocol.LAMBDA,
|
130 | topic,
|
131 | deadLetterQueue: dlQueue,
|
132 | });
|
133 | ```
|
134 |
|
135 | ## CloudWatch Event Rule Target
|
136 |
|
137 | SNS topics can be used as targets for CloudWatch event rules.
|
138 |
|
139 | Use the `@aws-cdk/aws-events-targets.SnsTopic`:
|
140 |
|
141 | ```ts
|
142 | import * as codecommit from '@aws-cdk/aws-codecommit';
|
143 | import * as targets from '@aws-cdk/aws-events-targets';
|
144 |
|
145 | declare const repo: codecommit.Repository;
|
146 | const myTopic = new sns.Topic(this, 'Topic');
|
147 |
|
148 | repo.onCommit('OnCommit', {
|
149 | target: new targets.SnsTopic(myTopic),
|
150 | });
|
151 | ```
|
152 |
|
153 | This will result in adding a target to the event rule and will also modify the
|
154 | topic resource policy to allow CloudWatch events to publish to the topic.
|
155 |
|
156 | ## Topic Policy
|
157 |
|
158 | A topic policy is automatically created when `addToResourcePolicy` is called, if
|
159 | one doesn't already exist. Using `addToResourcePolicy` is the simplest way to
|
160 | add policies, but a `TopicPolicy` can also be created manually.
|
161 |
|
162 | ```ts
|
163 | const topic = new sns.Topic(this, 'Topic');
|
164 | const topicPolicy = new sns.TopicPolicy(this, 'TopicPolicy', {
|
165 | topics: [topic],
|
166 | });
|
167 |
|
168 | topicPolicy.document.addStatements(new iam.PolicyStatement({
|
169 | actions: ["sns:Subscribe"],
|
170 | principals: [new iam.AnyPrincipal()],
|
171 | resources: [topic.topicArn],
|
172 | }));
|
173 | ```
|
174 |
|
175 | A policy document can also be passed on `TopicPolicy` construction
|
176 |
|
177 | ```ts
|
178 | const topic = new sns.Topic(this, 'Topic');
|
179 | const policyDocument = new iam.PolicyDocument({
|
180 | assignSids: true,
|
181 | statements: [
|
182 | new iam.PolicyStatement({
|
183 | actions: ["sns:Subscribe"],
|
184 | principals: [new iam.AnyPrincipal()],
|
185 | resources: [topic.topicArn],
|
186 | }),
|
187 | ],
|
188 | });
|
189 |
|
190 | const topicPolicy = new sns.TopicPolicy(this, 'Policy', {
|
191 | topics: [topic],
|
192 | policyDocument,
|
193 | });
|
194 | ```
|