# Amazon Simple Notification Service Construct Library
<!--BEGIN STABILITY BANNER-->---
> AWS CDK v1 has reached End-of-Support on 2023-06-01.
> This package is no longer being updated, and users should migrate to AWS CDK v2.
>
> For more information on how to migrate, see the [*Migrating to AWS CDK v2* guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).
---
<!--END STABILITY BANNER-->
Add an SNS Topic to your stack:
```python
topic = sns.Topic(self, "Topic",
display_name="Customer subscription topic"
)
```
Add a FIFO SNS topic with content-based de-duplication to your stack:
```python
topic = sns.Topic(self, "Topic",
content_based_deduplication=True,
display_name="Customer subscription topic",
fifo=True,
topic_name="customerTopic"
)
```
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.
## Subscriptions
Various subscriptions can be added to the topic by calling the
`.addSubscription(...)` method on the topic. It accepts a *subscription* object,
default implementations of which can be found in the
`@aws-cdk/aws-sns-subscriptions` package:
Add an HTTPS Subscription to your topic:
```python
my_topic = sns.Topic(self, "MyTopic")
my_topic.add_subscription(subscriptions.UrlSubscription("https://foobar.com/"))
```
Subscribe a queue to the topic:
```python
# queue: sqs.Queue
my_topic = sns.Topic(self, "MyTopic")
my_topic.add_subscription(subscriptions.SqsSubscription(queue))
```
Note that subscriptions of queues in different accounts need to be manually confirmed by
reading the initial message from the queue and visiting the link found in it.
### Filter policy
A filter policy can be specified when subscribing an endpoint to a topic.
Example with a Lambda subscription:
```python
import aws_cdk.aws_lambda as lambda_
# fn: lambda.Function
my_topic = sns.Topic(self, "MyTopic")
# Lambda should receive only message matching the following conditions on attributes:
# color: 'red' or 'orange' or begins with 'bl'
# size: anything but 'small' or 'medium'
# price: between 100 and 200 or greater than 300
# store: attribute must be present
my_topic.add_subscription(subscriptions.LambdaSubscription(fn,
filter_policy={
"color": sns.SubscriptionFilter.string_filter(
allowlist=["red", "orange"],
match_prefixes=["bl"]
),
"size": sns.SubscriptionFilter.string_filter(
denylist=["small", "medium"]
),
"price": sns.SubscriptionFilter.numeric_filter(
between=sns.BetweenCondition(start=100, stop=200),
greater_than=300
),
"store": sns.SubscriptionFilter.exists_filter()
}
))
```
### Example of Firehose Subscription
```python
from aws_cdk.aws_kinesisfirehose import DeliveryStream
# stream: DeliveryStream
topic = sns.Topic(self, "Topic")
sns.Subscription(self, "Subscription",
topic=topic,
endpoint=stream.delivery_stream_arn,
protocol=sns.SubscriptionProtocol.FIREHOSE,
subscription_role_arn="SAMPLE_ARN"
)
```
## DLQ setup for SNS Subscription
CDK can attach provided Queue as DLQ for your SNS subscription.
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.
Example of usage with user provided DLQ.
```python
topic = sns.Topic(self, "Topic")
dl_queue = sqs.Queue(self, "DeadLetterQueue",
queue_name="MySubscription_DLQ",
retention_period=Duration.days(14)
)
sns.Subscription(self, "Subscription",
endpoint="endpoint",
protocol=sns.SubscriptionProtocol.LAMBDA,
topic=topic,
dead_letter_queue=dl_queue
)
```
## CloudWatch Event Rule Target
SNS topics can be used as targets for CloudWatch event rules.
Use the `@aws-cdk/aws-events-targets.SnsTopic`:
```python
import aws_cdk.aws_codecommit as codecommit
import aws_cdk.aws_events_targets as targets
# repo: codecommit.Repository
my_topic = sns.Topic(self, "Topic")
repo.on_commit("OnCommit",
target=targets.SnsTopic(my_topic)
)
```
This will result in adding a target to the event rule and will also modify the
topic resource policy to allow CloudWatch events to publish to the topic.
## Topic Policy
A topic policy is automatically created when `addToResourcePolicy` is called, if
one doesn't already exist. Using `addToResourcePolicy` is the simplest way to
add policies, but a `TopicPolicy` can also be created manually.
```python
topic = sns.Topic(self, "Topic")
topic_policy = sns.TopicPolicy(self, "TopicPolicy",
topics=[topic]
)
topic_policy.document.add_statements(iam.PolicyStatement(
actions=["sns:Subscribe"],
principals=[iam.AnyPrincipal()],
resources=[topic.topic_arn]
))
```
A policy document can also be passed on `TopicPolicy` construction
```python
topic = sns.Topic(self, "Topic")
policy_document = iam.PolicyDocument(
assign_sids=True,
statements=[
iam.PolicyStatement(
actions=["sns:Subscribe"],
principals=[iam.AnyPrincipal()],
resources=[topic.topic_arn]
)
]
)
topic_policy = sns.TopicPolicy(self, "Policy",
topics=[topic],
policy_document=policy_document
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-sns",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/f9/fb/480459a7564efe385824fd1f7fe169fe5fdd7b991c6a62c6b34d4dd775f0/aws-cdk.aws-sns-1.204.0.tar.gz",
"platform": null,
"description": "# Amazon Simple Notification Service Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> AWS CDK v1 has reached End-of-Support on 2023-06-01.\n> This package is no longer being updated, and users should migrate to AWS CDK v2.\n>\n> For more information on how to migrate, see the [*Migrating to AWS CDK v2* guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).\n\n---\n<!--END STABILITY BANNER-->\n\nAdd an SNS Topic to your stack:\n\n```python\ntopic = sns.Topic(self, \"Topic\",\n display_name=\"Customer subscription topic\"\n)\n```\n\nAdd a FIFO SNS topic with content-based de-duplication to your stack:\n\n```python\ntopic = sns.Topic(self, \"Topic\",\n content_based_deduplication=True,\n display_name=\"Customer subscription topic\",\n fifo=True,\n topic_name=\"customerTopic\"\n)\n```\n\nNote 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.\n\n## Subscriptions\n\nVarious subscriptions can be added to the topic by calling the\n`.addSubscription(...)` method on the topic. It accepts a *subscription* object,\ndefault implementations of which can be found in the\n`@aws-cdk/aws-sns-subscriptions` package:\n\nAdd an HTTPS Subscription to your topic:\n\n```python\nmy_topic = sns.Topic(self, \"MyTopic\")\n\nmy_topic.add_subscription(subscriptions.UrlSubscription(\"https://foobar.com/\"))\n```\n\nSubscribe a queue to the topic:\n\n```python\n# queue: sqs.Queue\n\nmy_topic = sns.Topic(self, \"MyTopic\")\n\nmy_topic.add_subscription(subscriptions.SqsSubscription(queue))\n```\n\nNote that subscriptions of queues in different accounts need to be manually confirmed by\nreading the initial message from the queue and visiting the link found in it.\n\n### Filter policy\n\nA filter policy can be specified when subscribing an endpoint to a topic.\n\nExample with a Lambda subscription:\n\n```python\nimport aws_cdk.aws_lambda as lambda_\n# fn: lambda.Function\n\n\nmy_topic = sns.Topic(self, \"MyTopic\")\n\n# Lambda should receive only message matching the following conditions on attributes:\n# color: 'red' or 'orange' or begins with 'bl'\n# size: anything but 'small' or 'medium'\n# price: between 100 and 200 or greater than 300\n# store: attribute must be present\nmy_topic.add_subscription(subscriptions.LambdaSubscription(fn,\n filter_policy={\n \"color\": sns.SubscriptionFilter.string_filter(\n allowlist=[\"red\", \"orange\"],\n match_prefixes=[\"bl\"]\n ),\n \"size\": sns.SubscriptionFilter.string_filter(\n denylist=[\"small\", \"medium\"]\n ),\n \"price\": sns.SubscriptionFilter.numeric_filter(\n between=sns.BetweenCondition(start=100, stop=200),\n greater_than=300\n ),\n \"store\": sns.SubscriptionFilter.exists_filter()\n }\n))\n```\n\n### Example of Firehose Subscription\n\n```python\nfrom aws_cdk.aws_kinesisfirehose import DeliveryStream\n# stream: DeliveryStream\n\n\ntopic = sns.Topic(self, \"Topic\")\n\nsns.Subscription(self, \"Subscription\",\n topic=topic,\n endpoint=stream.delivery_stream_arn,\n protocol=sns.SubscriptionProtocol.FIREHOSE,\n subscription_role_arn=\"SAMPLE_ARN\"\n)\n```\n\n## DLQ setup for SNS Subscription\n\nCDK can attach provided Queue as DLQ for your SNS subscription.\nSee 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.\n\nExample of usage with user provided DLQ.\n\n```python\ntopic = sns.Topic(self, \"Topic\")\ndl_queue = sqs.Queue(self, \"DeadLetterQueue\",\n queue_name=\"MySubscription_DLQ\",\n retention_period=Duration.days(14)\n)\n\nsns.Subscription(self, \"Subscription\",\n endpoint=\"endpoint\",\n protocol=sns.SubscriptionProtocol.LAMBDA,\n topic=topic,\n dead_letter_queue=dl_queue\n)\n```\n\n## CloudWatch Event Rule Target\n\nSNS topics can be used as targets for CloudWatch event rules.\n\nUse the `@aws-cdk/aws-events-targets.SnsTopic`:\n\n```python\nimport aws_cdk.aws_codecommit as codecommit\nimport aws_cdk.aws_events_targets as targets\n\n# repo: codecommit.Repository\n\nmy_topic = sns.Topic(self, \"Topic\")\n\nrepo.on_commit(\"OnCommit\",\n target=targets.SnsTopic(my_topic)\n)\n```\n\nThis will result in adding a target to the event rule and will also modify the\ntopic resource policy to allow CloudWatch events to publish to the topic.\n\n## Topic Policy\n\nA topic policy is automatically created when `addToResourcePolicy` is called, if\none doesn't already exist. Using `addToResourcePolicy` is the simplest way to\nadd policies, but a `TopicPolicy` can also be created manually.\n\n```python\ntopic = sns.Topic(self, \"Topic\")\ntopic_policy = sns.TopicPolicy(self, \"TopicPolicy\",\n topics=[topic]\n)\n\ntopic_policy.document.add_statements(iam.PolicyStatement(\n actions=[\"sns:Subscribe\"],\n principals=[iam.AnyPrincipal()],\n resources=[topic.topic_arn]\n))\n```\n\nA policy document can also be passed on `TopicPolicy` construction\n\n```python\ntopic = sns.Topic(self, \"Topic\")\npolicy_document = iam.PolicyDocument(\n assign_sids=True,\n statements=[\n iam.PolicyStatement(\n actions=[\"sns:Subscribe\"],\n principals=[iam.AnyPrincipal()],\n resources=[topic.topic_arn]\n )\n ]\n)\n\ntopic_policy = sns.TopicPolicy(self, \"Policy\",\n topics=[topic],\n policy_document=policy_document\n)\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::SNS",
"version": "1.204.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "059736b109d75f6215fcf1c3f11ed009ec0112c2cb69b4637287412c7c4339df",
"md5": "1c1a2828df35bc9d7db5fa5e28af6aba",
"sha256": "29e78a2494b6142fe818bea1c84a26ec0ba015dd5aba4a3c575dce9b497e5c63"
},
"downloads": -1,
"filename": "aws_cdk.aws_sns-1.204.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1c1a2828df35bc9d7db5fa5e28af6aba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 136439,
"upload_time": "2023-06-19T21:01:29",
"upload_time_iso_8601": "2023-06-19T21:01:29.861627Z",
"url": "https://files.pythonhosted.org/packages/05/97/36b109d75f6215fcf1c3f11ed009ec0112c2cb69b4637287412c7c4339df/aws_cdk.aws_sns-1.204.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f9fb480459a7564efe385824fd1f7fe169fe5fdd7b991c6a62c6b34d4dd775f0",
"md5": "3436a8ed3bb12d198601d57bcc481fe7",
"sha256": "5b70bea4eea0233658ee31c1fa9acb1177c8d7cc957e077d2f9a03d5d2ad1739"
},
"downloads": -1,
"filename": "aws-cdk.aws-sns-1.204.0.tar.gz",
"has_sig": false,
"md5_digest": "3436a8ed3bb12d198601d57bcc481fe7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 137733,
"upload_time": "2023-06-19T21:07:40",
"upload_time_iso_8601": "2023-06-19T21:07:40.287385Z",
"url": "https://files.pythonhosted.org/packages/f9/fb/480459a7564efe385824fd1f7fe169fe5fdd7b991c6a62c6b34d4dd775f0/aws-cdk.aws-sns-1.204.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 21:07:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-sns"
}
JSON
