Amazon Simple Notification Service

211 Pages·2017·3.68 MB·French

by  Amazon Web Services

Amazon Simple
Notification Service
Developer Guide
API Version 2010-03-31
Amazon Simple Notification Service Developer Guide
Amazon Simple Notification Service: Developer Guide
Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
Amazon Simple Notification Service Developer Guide
Table of Contents
What is Amazon SNS? ........................................................................................................................ 1
Are You a First-Time Amazon Simple Notification Service User? ........................................................ 2
Beyond the Getting Started Section ............................................................................................. 2
Accessing Amazon SNS ............................................................................................................... 2
Getting Started .................................................................................................................................. 4
Before You Begin....................................................................................................................... 4
Create a Topic ........................................................................................................................... 5
Subscribe to a Topic ................................................................................................................... 5
Publish to a Topic...................................................................................................................... 6
Create Different Messages for Each Protocol .......................................................................... 7
Clean Up................................................................................................................................... 8
Using the AWS SDK for Java ....................................................................................................... 9
Using the AWS SDK for .NET ...................................................................................................... 10
How Amazon SNS Works................................................................................................................... 13
Common Scenarios................................................................................................................... 13
Fanout............................................................................................................................ 13
Application and System Alerts ........................................................................................... 13
Push Email and Text Messaging ......................................................................................... 14
Mobile Push Notifications.................................................................................................. 14
Message Durability........................................................................................................... 14
Message Delivery Status............................................................................................................ 14
Configuring Message Delivery Status Attributes with the AWS Management Console ................. 15
Configuring Message Delivery Status Attributes for Topics Subscribed to Amazon SNS
Endpoints with the AWS SDKs ........................................................................................... 15
Message Attributes................................................................................................................... 17
Message Attribute Items and Validation .............................................................................. 17
Data Types...................................................................................................................... 18
Reserved Message Attributes for Mobile Push Notifications .................................................... 18
Applying Message Attributes ............................................................................................. 19
Message Filtering..................................................................................................................... 24
Subscription Filter Policies ................................................................................................. 24
Applying.......................................................................................................................... 28
Removing........................................................................................................................ 31
Example: Filter Policy as a Java Collection ........................................................................... 33
Message and JSON Formats ....................................................................................................... 35
HTTP/HTTPS Headers....................................................................................................... 36
HTTP/HTTPS Subscription Confirmation JSON Format .......................................................... 36
HTTP/HTTPS Notification JSON Format .............................................................................. 38
HTTP/HTTPS Unsubscribe Confirmation JSON Format ........................................................... 39
SetSubscriptionAttributes Delivery Policy JSON Format ......................................................... 40
SetTopicAttributes Delivery Policy JSON Format ................................................................... 41
Large Payload and Raw Message Delivery .................................................................................... 42
Enabling Raw Message Delivery with the AWS Management Console ....................................... 42
System-to-System Messaging ............................................................................................................. 43
With AWS Lambda Function as Subscriber................................................................................... 43
Prerequisites.................................................................................................................... 43
Configuring Amazon SNS with Lambda Endpoints with the AWS Management Console .............. 43
With Amazon SQS Queue as Subscriber ...................................................................................... 44
Step 1: Get the ARN of the Queue and Topic ....................................................................... 45
Step 2: Give Permission to the Amazon SNS Topic to Send Messages to the Amazon SQS Queue .. 46
Step 3: Subscribe the Queue to the Amazon SNS Topic ......................................................... 46
Step 4: Give Users Permissions to the Appropriate Topic and Queue Actions ............................. 47
Step 5: Test the Topic's Queue Subscriptions ....................................................................... 49
Sending Messages to a Queue in a Different Account ............................................................ 50
API Version 2010-03-31
iii
Amazon Simple Notification Service Developer Guide
Using an AWS CloudFormation Template to Create a Topic that Sends Messages to Amazon
SQS Queues.................................................................................................................... 53
With HTTP/S Endpoint as Subscriber .......................................................................................... 57
Step 1: Make Sure Your Endpoint is Ready to Process Amazon SNS Messages ............................ 58
Step 2: Subscribe the HTTP/HTTPS endpoint to the Amazon SNS topic ................................... 61
Step 3: Confirm the subscription........................................................................................ 61
Step 4: Set the delivery retry policy for the subscription (optional) ......................................... 62
Step 5: Give users permissions to publish to the topic (optional) ............................................. 62
Step 6: Send messages to the HTTP/HTTPS endpoint ........................................................... 63
Setting Amazon SNS Delivery Retry Policies for HTTP/HTTPS Endpoints .................................. 63
Certificate Authorities for HTTPS Endpoints ......................................................................... 69
Verifying Message Signatures ............................................................................................. 81
Example Code for an Endpoint Java Servlet ......................................................................... 83
User Notifications............................................................................................................................. 87
With Mobile Application as Subscriber (Mobile Push).................................................................... 87
Overview......................................................................................................................... 87
Prerequisites.................................................................................................................... 88
Mobile Push High‐Level Steps ............................................................................................ 89
Getting Started with ADM ................................................................................................. 90
Getting Started with APNS ................................................................................................ 94
Getting Started with Baidu .............................................................................................. 100
Getting Started with GCM ............................................................................................... 116
Getting Started with MPNS ............................................................................................. 120
Getting Started with WNS ............................................................................................... 123
Using Amazon SNS Mobile Push ....................................................................................... 126
Application Attributes for Message Delivery Status ............................................................. 139
Application Event Notifications ......................................................................................... 142
Amazon SNS TTL ............................................................................................................ 144
Amazon SNS Mobile Push APIs ......................................................................................... 146
API Errors...................................................................................................................... 147
With Mobile Phone Number as Subscriber (Send SMS)................................................................. 153
Setting Preferences......................................................................................................... 154
Sending a Message......................................................................................................... 157
Sending a Message to Multiple Phone Numbers................................................................. 161
Monitoring SMS Activity .................................................................................................. 167
Managing Subscriptions................................................................................................... 172
Reserving a Short Code ................................................................................................... 177
Supported Regions and Countries ..................................................................................... 178
Monitoring and Logging.................................................................................................................. 186
Monitoring Topics Using CloudWatch ........................................................................................ 186
Access CloudWatch Metrics for Amazon SNS ...................................................................... 186
Set CloudWatch Alarms for Amazon SNS Metrics ................................................................ 187
Amazon SNS Metrics ....................................................................................................... 188
Dimensions for Amazon Simple Notification Service Metrics ................................................. 190
Logging API Calls Using CloudTrail ........................................................................................... 191
Amazon SNS Information in CloudTrail .............................................................................. 191
Example: Amazon SNS Log File Entries .............................................................................. 192
Security......................................................................................................................................... 195
Authentication and Access Control ............................................................................................ 195
Overview of Managing Access .......................................................................................... 195
Special Information for Amazon SNS Policies ..................................................................... 209
Controlling User Access to Your AWS Account .................................................................... 210
Server-Side Encryption............................................................................................................ 216
Encryption Scope............................................................................................................ 217
Key Terms...................................................................................................................... 217
Estimating AWS KMS Costs .............................................................................................. 218
Configuring AWS KMS Permissions ................................................................................... 219
API Version 2010-03-31
iv
Amazon Simple Notification Service Developer Guide
Errors............................................................................................................................ 221
Tutorial: Enabling SSE for a Topic ..................................................................................... 222
Tutorial: Enabling SSE for a Topic with an Encrypted Queue Subscribed ................................. 224
VPC Endpoints....................................................................................................................... 226
Tutorial: Publishing Messages Privately from a VPC ............................................................. 226
Tutorial: Creating a VPC Endpoint ..................................................................................... 236
Document History.......................................................................................................................... 238
AWS Glossary................................................................................................................................. 247
API Version 2010-03-31
v
Amazon Simple Notification Service Developer Guide
What is Amazon Simple Notification
Service?
Amazon Simple Notification Service (Amazon SNS) is a web service that coordinates and manages the
delivery or sending of messages to subscribing endpoints or clients. In Amazon SNS, there are two
types of clients—publishers and subscribers—also referred to as producers and consumers. Publishers
communicate asynchronously with subscribers by producing and sending a message to a topic, which is a
logical access point and communication channel. Subscribers (i.e., web servers, email addresses, Amazon
SQS queues, AWS Lambda functions) consume or receive the message or notification over one of the
supported protocols (i.e., Amazon SQS, HTTP/S, email, SMS, Lambda) when they are subscribed to the
topic.
When using Amazon SNS, you (as the owner) create a topic and control access to it by defining policies
that determine which publishers and subscribers can communicate with the topic. A publisher sends
messages to topics that they have created or to topics they have permission to publish to. Instead of
including a specific destination address in each message, a publisher sends a message to the topic.
Amazon SNS matches the topic to a list of subscribers who have subscribed to that topic, and delivers
the message to each of those subscribers. Each topic has a unique name that identifies the Amazon SNS
endpoint for publishers to post messages and subscribers to register for notifications. Subscribers receive
all messages published to the topics to which they subscribe, and all subscribers to a topic receive the
same messages.
Topics
• Are You a First-Time Amazon Simple Notification Service User? (p. 2)
• Beyond the Getting Started Section (p. 2)
• Accessing Amazon SNS (p. 2)
API Version 2010-03-31
1
Amazon Simple Notification Service Developer Guide
Are You a First-Time Amazon
Simple Notification Service User?
Are You a First-Time Amazon Simple Notification
Service User?
If you are a first-time user of Amazon SNS, we recommend that you begin by reading the Getting Started
with Amazon Simple Notification Service (p. 4) section. This section walks you through creating a
topic, subscribing to it, publishing a message to it, unsubscribing from it, and finally, deleting the topic.
Beyond the Getting Started Section
Beyond the getting started section, you'll probably want to learn more about Amazon SNS operations.
The following sections provide detailed information about working with Amazon SNS:
• Authentication and Access Control for Amazon SNS (p. 195)
You have detailed control over which endpoints a topic allows, who is able to publish to a topic, and
under what conditions. This section shows you how to control access through the use of access control
policies.
• Monitoring Amazon SNS Topics Using CloudWatch (p. 186)
Amazon SNS and CloudWatch are integrated so you can collect, view, and analyze metrics for every
active Amazon SNS topic.
• With an Amazon SQS Queue as a Subscriber (p. 44)
You can use Amazon SNS to send messages to one or more Amazon SQS queues.
• Using Amazon SNS for User Notifications with a Mobile Phone Number as a Subscriber (Send
SMS) (p. 153)
You can use Amazon Simple Notification Service (Amazon SNS) to send SMS notifications to SMS-
enabled mobile phones and smart phones.
• With an HTTP/S Endpoint as a Subscriber (p. 57)
You can use Amazon SNS to send notification messages to one or more HTTP or HTTPS endpoints.
Accessing Amazon SNS
If you have an AWS account, you can access Amazon SNS in any of the following ways.
AWS Management Console
The AWS Management Console provides a web interface where you can manage your compute,
storage, and other cloud resources. Within the AWS Management Console, individual services have
their own console. To open the Amazon SNS console, log in to https://console.aws.amazon.com/
and choose SNS from the console home page, or use the SNS console direct URL: https://
console.aws.amazon.com/sns/. For a tutorial that helps you complete common SNS tasks in the
console, see Getting Started with Amazon Simple Notification Service (p. 4).
AWS Command Line Interface (CLI)
Provides commands for a broad set of AWS products, and is supported on Windows, Mac, and Linux.
To get started, see AWS Command Line Interface User Guide. For more information about the
commands for Amazon SNS, see sns in the AWS CLI Command Reference.
API Version 2010-03-31
2
Amazon Simple Notification Service Developer Guide
Accessing Amazon SNS
AWS Tools for Windows PowerShell
Provides commands for a broad set of AWS products for those who script in the PowerShell
environment. To get started, see the AWS Tools for Windows PowerShell User Guide. For more
information about the cmdlets for Amazon SNS, see Amazon Simple Notification Service in the AWS
Tools for PowerShell Cmdlet Reference.
AWS SDKs
AWS provides SDKs (software development kits) that consist of libraries and sample code for various
programming languages and platforms (Java, Python, Ruby, .NET, iOS, Android, etc.). The SDKs
provide a convenient way to create programmatic access to Amazon SNS and AWS. For example, the
SDKs take care of tasks such as cryptographically signing requests, managing errors, and retrying
requests automatically. For information about the AWS SDKs, including how to download and install
them, see the Tools for Amazon Web Services page.
Amazon SNS Query API
You can access Amazon SNS and AWS programmatically by using the Amazon SNS Query API,
which lets you issue requests directly to the service. For more information, see the Amazon Simple
Notification Service API Reference.
API Version 2010-03-31
3
Amazon Simple Notification Service Developer Guide
Before You Begin
Getting Started with Amazon Simple
Notification Service
This section contains information for you to understand Amazon SNS concepts and quickly set up
and use available tools and interfaces for creating and publishing to topics. To get started with push
notification messages, see Using Amazon SNS for User Notifications with a Mobile Application as a
Subscriber (Mobile Push) (p. 87).
Topics
• Before You Begin (p. 4)
• Create a Topic (p. 5)
• Subscribe to a Topic (p. 5)
• Publish to a Topic (p. 6)
• Clean Up (p. 8)
• Using the AWS SDK for Java with Amazon SNS (p. 9)
• Using the AWS SDK for .NET with Amazon SNS (p. 10)
Before You Begin
To use Amazon SNS, you need an AWS account. If you don't already have one, use the following
procedure.
To sign up for AWS account
1. Open https://aws.amazon.com/, and then choose Create an AWS Account.
Note
If you previously signed in to the AWS Management Console using AWS account root user
credentials, choose Sign in to a different account. If you previously signed in to the console
using IAM credentials, choose Sign-in using root account credentials. Then choose Create
a new AWS account.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code using
the phone keypad.
To get started with Amazon SNS
1. Sign in to the AWS Management Console and open the Amazon SNS console at https://
console.aws.amazon.com/sns/v2/home.
2. Choose the Get Started button.
You should now be on the SNS Home page.
API Version 2010-03-31
4
Amazon Simple Notification Service Developer Guide
Create a Topic
Create a Topic
Now that you're signed up for Amazon SNS, you're ready to create a topic. A topic is a communication
channel to send messages and subscribe to notifications. It provides an access point for publishers and
subscribers to communicate with each other. In this section you create a topic named MyTopic.
To create a topic
1. In the Amazon SNS console, choose Create topic.
The Create topic dialog box appears.
2. In the Topic name box, type a topic name.
3. Choose Create topic.
4. On the Topic Details page, select the new topic and then choose the topic ARN.
5. Copy the topic ARN.
arn:aws:sns:us-west-2:111122223333:MyTopic

Subscribe to a Topic
To receive messages published to a topic, you have to subscribe an endpoint to that topic. An endpoint is
a mobile app, web server, email address, or an Amazon SQS queue that can receive notification messages
from Amazon SNS. Once you subscribe an endpoint to a topic and the subscription is confirmed, the
endpoint will receive all messages published to that topic.
In this section you subscribe an endpoint to the topic you just created in the previous section. You
configure the subscription to send the topic messages to your email account.
To subscribe to a topic
1. Open the Amazon SNS console at https://console.aws.amazon.com/sns/v2/home.
2. Choose Create subscription.
API Version 2010-03-31
5