@aws-cdk/sns

AWS SNS Construct Library

Add an SNS Topic to your stack:

import { Topic } from '@aws-cdk/sns';

const topic = new Topic(stack, 'Topic', {
    displayName: 'Customer subscription topic'
});

Subscriptions

Various subscriptions can be added to the topic by calling the .subscribeXxx() methods on the topic.

Add an HTTPS Subscription to your topic:

const myTopic = new Topic(stack, 'MyTopic');

myTopic.subscribeUrl('MyHttpsSubscription', 'https://foobar.com/');

Subscribe a queue to the topic:

const topic = new Topic(this, 'MyTopic');
const queue = new Queue(this, 'MyQueue');

topic.subscribeQueue(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.

CloudWatch Event Rule Target

SNS topics can be used as targets for CloudWatch event rules:

const myTopic = new Topic(this, 'MyTopic');

// Use an EventRule and add the topic as a target
const rule = new EventRule(this, 'Rule', {
    scheduleExpression: 'rate(1 minute)'
});
rule.addTarget(myTopic);

// Or use one of the onXxx methods on event sources
codeCommitRepo.onCommit('OnCommit', myTopic);

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.

Reference

EmailSubscriptionOptions (interface)

class _aws-cdk_sns.EmailSubscriptionOptions

Options for email subscriptions.

json

Indicates if the full notification JSON should be sent to the email address or just the message text.

Type:boolean or None

Subscription

class _aws-cdk_sns.Subscription(parent, name, props)

A new subscription. Prefer to use the TopicRef.subscribeXxx() methods to creating instances of this class.

Extends:

Construct

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (SubscriptionProps) –

SubscriptionProps (interface)

class _aws-cdk_sns.SubscriptionProps

Properties for creating a new subscription

protocol

What type of subscription to add.

Type:SubscriptionProtocol
endpoint

The subscription endpoint. The meaning of this value depends on the value for ‘protocol’.

Type:any
topic

The topic to subscribe to.

Type:TopicRef

SubscriptionProtocol (enum)

class _aws-cdk_sns.SubscriptionProtocol
Http
Https
Email
EmailJson
Sms
Sqs
Application
Lambda

Topic

class _aws-cdk_sns.Topic(parent, name[, props])

A new SNS topic

Extends:

TopicRef

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (TopicProps or None) –
topicArn
Type:TopicArn (readonly)
topicName
Type:TopicName (readonly)
autoCreatePolicy

Controls automatic creation of policy objects. Set by subclasses.

Type:boolean

TopicArn

class _aws-cdk_sns.TopicArn([valueOrFunction])

ARN of a Topic

Extends:Arn
Parameters:valueOrFunction (any or None) –

TopicName

class _aws-cdk_sns.TopicName([valueOrFunction])

Name of a Topic

Extends:Token
Parameters:valueOrFunction (any or None) –

TopicPolicy

class _aws-cdk_sns.TopicPolicy(parent, name, props)

Applies a policy to SNS topics.

Extends:

Construct

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (TopicPolicyProps) –
document

The IAM policy document for this policy.

Type:PolicyDocument (readonly)

TopicPolicyProps (interface)

class _aws-cdk_sns.TopicPolicyProps
topics

The set of topics this policy applies to.

Type:TopicRef

TopicProps (interface)

class _aws-cdk_sns.TopicProps

Properties for a new SNS topic

displayName

A developer-defined string that can be used to identify this SNS topic.

Type:string or None
topicName

A name for the topic. If you don’t specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the topic name. For more information, see Name Type.

Type:string or None

TopicRef

class _aws-cdk_sns.TopicRef(parent, name)

Either a new or imported Topic

Extends:

Construct

Implements:

IEventRuleTarget

Implements:

IAlarmAction

Abstract:

Yes

Parameters:
  • parent (Construct) – The parent construct
  • name (string) –
static import(parent, name, props) → @aws-cdk/sns.TopicRef

Import a Topic defined elsewhere

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (TopicRefProps) –
Return type:

TopicRef

export() → @aws-cdk/sns.TopicRefProps

Export this Topic

Return type:TopicRefProps
subscribe(name, endpoint, protocol)

Subscribe some endpoint to this topic

Parameters:
  • name (string) –
  • endpoint (string) –
  • protocol (SubscriptionProtocol) –
subscribeQueue(queue) → @aws-cdk/sns.Subscription

Defines a subscription from this SNS topic to an SQS queue. The queue resource policy will be updated to allow this SNS topic to send messages to the queue. TODO: change to QueueRef.

Parameters:queue (QueueRef) – The target queue
Return type:Subscription
subscribeLambda(lambdaFunction) → @aws-cdk/sns.Subscription

Defines a subscription from this SNS Topic to a Lambda function. The Lambda’s resource policy will be updated to allow this topic to invoke the function.

Parameters:lambdaFunction (LambdaRef) – The Lambda function to invoke
Return type:Subscription
subscribeEmail(name, emailAddress[, options]) → @aws-cdk/sns.Subscription

Defines a subscription from this SNS topic to an email address.

Parameters:
  • name (string) – A name for the subscription
  • emailAddress (string) – The email address to use.
  • options (EmailSubscriptionOptions or None) –
Return type:

Subscription

subscribeUrl(name, url) → @aws-cdk/sns.Subscription

Defines a subscription from this SNS topic to an http:// or https:// URL.

Parameters:
  • name (string) – A name for the subscription
  • url (string) – The URL to invoke
Return type:

Subscription

addToResourcePolicy(statement)

Adds a statement to the IAM resource policy associated with this topic. If this topic was created in this stack (new Topic), a topic policy will be automatically created upon the first call to addToPolicy. If the topic is improted (Topic.import), then this is a no-op.

Parameters:statement (PolicyStatement) –
grantPublish([identity])

Grant topic publishing permissions to the given identity

Parameters:identity (IIdentityResource or None) –
metric(metricName[, props]) → @aws-cdk/cloudwatch.Metric

Construct a Metric object for the current topic for the given metric

Parameters:
  • metricName (string) –
  • props (MetricCustomization or None) –
Return type:

Metric

metricPublishSize([props]) → @aws-cdk/cloudwatch.Metric

Metric for the size of messages published through this topic

Parameters:props (MetricCustomization or None) –
Return type:Metric
metricNumberOfMessagesPublished([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of messages published through this topic

Parameters:props (MetricCustomization or None) –
Return type:Metric
metricNumberOfMessagesFailed([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of messages that failed to publish through this topic

Parameters:props (MetricCustomization or None) –
Return type:Metric
metricNumberOfMessagesDelivered([props]) → @aws-cdk/cloudwatch.Metric

Metric for the number of messages that were successfully delivered through this topic

Parameters:props (MetricCustomization or None) –
Return type:Metric
topicArn
Type:TopicArn (readonly) (abstract)
topicName
Type:TopicName (readonly) (abstract)
autoCreatePolicy

Controls automatic creation of policy objects. Set by subclasses.

Type:boolean (readonly) (abstract)
eventRuleTarget

Returns a RuleTarget that can be used to trigger this SNS topic as a result from a CloudWatch event.

Type:EventRuleTarget (readonly)
alarmActionArn

Return the ARN that should be used for a CloudWatch Alarm action

Type:Arn (readonly)

TopicRefProps (interface)

class _aws-cdk_sns.TopicRefProps

Reference to an external topic.

topicArn
Type:TopicArn
topicName
Type:TopicName