Skip to main content

topics

Creates, updates, deletes, gets or lists a topics resource.

Overview​

Nametopics
TypeResource
Idaws.sns.topics

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
topic_arnstringThe topic's ARN.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
list_topicsselectregionNextTokenReturns a list of the requester's topics. Each call returns a limited list of topics, up to 100. If there are more topics, a NextToken is also returned. Use the NextToken parameter in a new ListTopics call to get further results. This action is throttled at 30 transactions per second (TPS).
create_topicinsertName, regionAttributes, Tags, DataProtectionPolicyCreates a topic to which notifications can be published. Users can create at most 100,000 standard topics (at most 1,000 FIFO topics). For more information, see Creating an Amazon SNS topic in the Amazon SNS Developer Guide. This action is idempotent, so if the requester already owns a topic with the specified name, that topic's ARN is returned without creating a new topic.
add_permissionupdateTopicArn, Label, AWSAccountId, ActionName, regionAdds a statement to a topic's access control policy, granting access for the specified Amazon Web Services accounts to the specified actions. To remove the ability to change topic permissions, you must deny permissions to the AddPermission, RemovePermission, and SetTopicAttributes actions in your IAM policy.
remove_permissionupdateTopicArn, Label, regionRemoves a statement from a topic's access control policy. To remove the ability to change topic permissions, you must deny permissions to the AddPermission, RemovePermission, and SetTopicAttributes actions in your IAM policy.
delete_topicdeleteTopicArn, regionDeletes a topic and all its subscriptions. Deleting a topic might prevent some messages previously sent to the topic from being delivered to subscribers. This action is idempotent, so deleting a topic that does not exist does not result in an error.
confirm_subscriptionexecTopicArn, Token, regionAuthenticateOnUnsubscribeVerifies an endpoint owner's intent to receive messages by validating the token sent to the endpoint by an earlier Subscribe action. If the token is valid, the action creates a new subscription and returns its Amazon Resource Name (ARN). This call requires an AWS signature only when the AuthenticateOnUnsubscribe flag is set to "true".
publish_batchexecTopicArn, PublishBatchRequestEntries, regionPublishes up to 10 messages to the specified topic in a single batch. This is a batch version of the Publish API. If you try to send more than 10 messages in a single batch request, you will receive a TooManyEntriesInBatchRequest exception. For FIFO topics, multiple messages within a single batch are published in the order they are sent, and messages are deduplicated within the batch and across batches for five minutes. The result of publishing each message is reported individually in the response. Because the batch request can result in a combination of successful and unsuccessful actions, you should check for batch errors even when the call returns an HTTP status code of 200. The maximum allowed individual message size and the maximum total payload size (the sum of the individual lengths of all of the batched messages) are both 256 KB (262,144 bytes). The PublishBatch API can send up to 10 messages at a time. If you attempt to send more than 10 messages in one request, you will encounter a TooManyEntriesInBatchRequest exception. In such cases, split your messages into multiple requests, each containing no more than 10 messages. Some actions take lists of parameters. These lists are specified using the param.n notation. Values of n are integers starting from 1. For example, a parameter list with two elements looks like this: &AttributeName.1=first &AttributeName.2=second If you send a batch message to a topic, Amazon SNS publishes the batch message to each endpoint that is subscribed to the topic. The format of the batch message depends on the notification protocol for each subscribed endpoint. When a messageId is returned, the batch message is saved, and Amazon SNS immediately delivers the message to subscribers.
subscribeexecTopicArn, regionProtocol, Endpoint, Attributes, ReturnSubscriptionArnSubscribes an endpoint to an Amazon SNS topic. If the endpoint type is HTTP/S or email, or if the endpoint and the topic are not in the same Amazon Web Services account, the endpoint owner must run the ConfirmSubscription action to confirm the subscription. You call the ConfirmSubscription action with the token from the subscription response. Confirmation tokens are valid for two days. This action is throttled at 100 transactions per second (TPS).

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
AWSAccountIdarrayThe Amazon Web Services account IDs of the users (principals) who will be given access to the specified actions. The users must have Amazon Web Services account, but do not need to be signed up for this service.
ActionNamearrayThe action you want to allow for the specified principal(s). Valid values: Any Amazon SNS action name, for example Publish.
LabelstringThe unique label of the statement you want to remove.
NamestringThe name of the topic you want to create. Constraints: Topic names must be made up of only uppercase and lowercase ASCII letters, numbers, underscores, and hyphens, and must be between 1 and 256 characters long. For a FIFO (first-in-first-out) topic, the name must end with the .fifo suffix.
PublishBatchRequestEntriesarrayA list of PublishBatch request entries to be sent to the SNS topic.
TokenstringShort-lived token sent to an endpoint during the Subscribe action.
TopicArnstringThe ARN of the topic you want to subscribe to.
regionstringAWS region (default: us-east-1)
AttributesobjectA map of attributes with their corresponding values. The following lists the names, descriptions, and values of the special request parameters that the Subscribe action uses: DeliveryPolicy – The policy that defines how Amazon SNS retries failed deliveries to HTTP/S endpoints. FilterPolicy – The simple JSON object that lets your subscriber receive only a subset of messages, rather than receiving every message published to the topic. FilterPolicyScope – This attribute lets you choose the filtering scope by using one of the following string value types: MessageAttributes (default) – The filter is applied on the message attributes. MessageBody – The filter is applied on the message body. RawMessageDelivery – When set to true, enables raw message delivery to Amazon SQS or HTTP/S endpoints. This eliminates the need for the endpoints to process JSON formatting, which is otherwise created for Amazon SNS metadata. RedrivePolicy – When specified, sends undeliverable messages to the specified Amazon SQS dead-letter queue. Messages that can't be delivered due to client errors (for example, when the subscribed endpoint is unreachable) or server errors (for example, when the service that powers the subscribed endpoint becomes unavailable) are held in the dead-letter queue for further analysis or reprocessing. The following attribute applies only to Amazon Data Firehose delivery stream subscriptions: SubscriptionRoleArn – The ARN of the IAM role that has the following: Permission to write to the Firehose delivery stream Amazon SNS listed as a trusted entity Specifying a valid ARN for this attribute is required for Firehose delivery stream subscriptions. For more information, see Fanout to Firehose delivery streams in the Amazon SNS Developer Guide. The following attributes apply only to FIFO topics: ReplayPolicy – Adds or updates an inline policy document for a subscription to replay messages stored in the specified Amazon SNS topic. ReplayStatus – Retrieves the status of the subscription message replay, which can be one of the following: Completed – The replay has successfully redelivered all messages, and is now delivering newly published messages. If an ending point was specified in the ReplayPolicy then the subscription will no longer receive newly published messages. In progress – The replay is currently replaying the selected messages. Failed – The replay was unable to complete. Pending – The default state while the replay initiates.
AuthenticateOnUnsubscribestringDisallows unauthenticated unsubscribes of the subscription. If the value of this parameter is true and the request has an Amazon Web Services signature, then only the topic owner and the subscription owner can unsubscribe the endpoint. The unsubscribe action requires Amazon Web Services authentication.
DataProtectionPolicystringThe body of the policy document you want to use for this topic. You can only add one policy per topic. The policy must be in JSON string format. Length Constraints: Maximum length of 30,720.
EndpointstringThe endpoint that you want to receive notifications. Endpoints vary by protocol: For the http protocol, the (public) endpoint is a URL beginning with http:​//. For the https protocol, the (public) endpoint is a URL beginning with https:​//. For the email protocol, the endpoint is an email address. For the email-json protocol, the endpoint is an email address. For the sms protocol, the endpoint is a phone number of an SMS-enabled device. For the sqs protocol, the endpoint is the ARN of an Amazon SQS queue. For the application protocol, the endpoint is the EndpointArn of a mobile app and device. For the lambda protocol, the endpoint is the ARN of an Lambda function. For the firehose protocol, the endpoint is the ARN of an Amazon Data Firehose delivery stream.
NextTokenstringToken returned by the previous ListTopics request.
ProtocolstringThe protocol that you want to use. Supported protocols include: http – delivery of JSON-encoded message via HTTP POST https – delivery of JSON-encoded message via HTTPS POST email – delivery of message via SMTP email-json – delivery of JSON-encoded message via SMTP sms – delivery of message via SMS sqs – delivery of JSON-encoded message to an Amazon SQS queue application – delivery of JSON-encoded message to an EndpointArn for a mobile app and device lambda – delivery of JSON-encoded message to an Lambda function firehose – delivery of JSON-encoded message to an Amazon Data Firehose delivery stream.
ReturnSubscriptionArnbooleanSets whether the response from the Subscribe request includes the subscription ARN, even if the subscription is not yet confirmed. If you set this parameter to true, the response includes the ARN in all cases, even if the subscription is not yet confirmed. In addition to the ARN for confirmed subscriptions, the response also includes the pending subscription ARN value for subscriptions that aren't yet confirmed. A subscription becomes confirmed when the subscriber calls the ConfirmSubscription action with a confirmation token. The default value is false.
TagsarrayThe list of tags to add to a new topic. To be able to tag a topic on creation, you must have the sns:CreateTopic and sns:TagResource permissions.

SELECT examples​

Returns a list of the requester's topics. Each call returns a limited list of topics, up to 100. If there are more topics, a NextToken is also returned. Use the NextToken parameter in a new ListTopics call to get further results. This action is throttled at 30 transactions per second (TPS).

SELECT
topic_arn
FROM aws.sns.topics
WHERE region = '{{ region }}' -- required
AND NextToken = '{{ NextToken }}'
;

INSERT examples​

Creates a topic to which notifications can be published. Users can create at most 100,000 standard topics (at most 1,000 FIFO topics). For more information, see Creating an Amazon SNS topic in the Amazon SNS Developer Guide. This action is idempotent, so if the requester already owns a topic with the specified name, that topic's ARN is returned without creating a new topic.

INSERT INTO aws.sns.topics (
Name,
region,
Attributes,
Tags,
DataProtectionPolicy
)
SELECT 
'{{ Name }}',
'{{ region }}',
'{{ Attributes }}',
'{{ Tags }}',
'{{ DataProtectionPolicy }}'
RETURNING
topic_arn
;

UPDATE examples​

Adds a statement to a topic's access control policy, granting access for the specified Amazon Web Services accounts to the specified actions. To remove the ability to change topic permissions, you must deny permissions to the AddPermission, RemovePermission, and SetTopicAttributes actions in your IAM policy.

UPDATE aws.sns.topics
SET 
-- No updatable properties
WHERE 
TopicArn = '{{ TopicArn }}' --required
AND Label = '{{ Label }}' --required
AND AWSAccountId = '{{ AWSAccountId }}' --required
AND ActionName = '{{ ActionName }}' --required
AND region = '{{ region }}' --required;

DELETE examples​

Deletes a topic and all its subscriptions. Deleting a topic might prevent some messages previously sent to the topic from being delivered to subscribers. This action is idempotent, so deleting a topic that does not exist does not result in an error.

DELETE FROM aws.sns.topics
WHERE TopicArn = '{{ TopicArn }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods​

Verifies an endpoint owner's intent to receive messages by validating the token sent to the endpoint by an earlier Subscribe action. If the token is valid, the action creates a new subscription and returns its Amazon Resource Name (ARN). This call requires an AWS signature only when the AuthenticateOnUnsubscribe flag is set to "true".

EXEC aws.sns.topics.confirm_subscription 
@TopicArn='{{ TopicArn }}' --required, 
@Token='{{ Token }}' --required, 
@region='{{ region }}' --required, 
@AuthenticateOnUnsubscribe='{{ AuthenticateOnUnsubscribe }}'
;
Last updated on