Amazon Simple Notification Service Developer Guide API Version 2010-03-31 Amazon Simple Notification Service Developer Guide Amazon Simple Notification Service: Developer Guide Copyright © 2015 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront, AWS CloudTrail, AWS CodeDeploy, Amazon Cognito, Amazon DevPay, DynamoDB, ElastiCache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Amazon Kinesis, Kindle, Kindle Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC, and Amazon WorkDocs. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. 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. AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region. 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 Common Scenarios ............................................................................................................... 3 Fanout......................................................................................................................... 3 Application and System Alerts......................................................................................... 3 Push Email and Text Messaging....................................................................................... 3 Mobile Push Notifications................................................................................................ 3 Getting Started ............................................................................................................................. 4 Before You Begin................................................................................................................... 4 Create a Topic ...................................................................................................................... 4 Subscribe to a Topic............................................................................................................... 6 Publish to a Topic .................................................................................................................. 6 Create Different Messages for Each Protocol..................................................................... 7 Clean Up ............................................................................................................................. 9 Using the SDK for Java......................................................................................................... 10 Managing Access ........................................................................................................................ 13 Overview............................................................................................................................ 13 When to Use Access Control......................................................................................... 14 Key Concepts ............................................................................................................. 14 Architectural Overview.................................................................................................. 16 Using the Access Policy Language................................................................................. 18 Evaluation Logic .......................................................................................................... 19 Example Cases for Amazon SNS Access Control.............................................................. 22 Special Information for Amazon SNS Policies........................................................................... 27 Amazon SNS Policy Limits ............................................................................................ 27 Valid Amazon SNS Policy Actions................................................................................... 27 Amazon SNS Keys....................................................................................................... 28 Controlling User Access to Your AWS Account.......................................................................... 29 IAM and Amazon SNS Policies Together.......................................................................... 29 Amazon SNS ARNs ..................................................................................................... 32 Amazon SNS Actions ................................................................................................... 33 Amazon SNS Keys....................................................................................................... 33 Example Policies for Amazon SNS.................................................................................. 34 Using Temporary Security Credentials............................................................................. 36 Amazon SNS Mobile Push ............................................................................................................ 38 Overview............................................................................................................................ 38 Prerequisites ...................................................................................................................... 39 Mobile Push High Level Steps................................................................................................ 40 Step 1: Request Credentials from Mobile Platforms............................................................ 40 Step 2: Request Token from Mobile Platforms................................................................... 40 Step 3: Request Platform Application Object..................................................................... 40 Step 4: Request Platform Endpoint Object........................................................................ 41 Step 5: Publish Message to Mobile Endpoint.................................................................... 41 Getting Started with ADM...................................................................................................... 41 ADM Prerequisites....................................................................................................... 41 Step 1: Create a Kindle Fire App with the ADM Service Enabled.......................................... 42 Step 2: Obtain a Client ID and Client Secret..................................................................... 42 Step 3: Obtain an API Key............................................................................................. 43 Step 4: Obtain a Registration ID..................................................................................... 43 Step 5: Sending a Message to a Kindle Fire app using Amazon SNS and ADM...................... 44 Getting Started with APNS.................................................................................................... 46 APNS Prerequisites ..................................................................................................... 46 Step 1: Create an iOS App............................................................................................ 46 API Version 2010-03-31 iii Amazon Simple Notification Service Developer Guide Step 2: Obtain an APNS SSL Certificate.......................................................................... 47 Step 3: Obtain the App Private Key................................................................................. 47 Step 4:Verify the Certificate and App Private Key.............................................................. 48 Step 5: Obtain a Device Token....................................................................................... 48 Step 6: Send a Message to an iOS app using Amazon SNS and APNS................................. 49 Getting Started with Baidu..................................................................................................... 51 Baidu Prerequisites...................................................................................................... 51 Step 1: Create a Baidu Account...................................................................................... 51 Step 2: Register as a Baidu Developer............................................................................. 53 Step 3: Create a Baidu Cloud Push Project...................................................................... 56 Step 4: Download and Install the Android Demo App.......................................................... 59 Step 5: Obtain a user Id and channel Id........................................................................... 63 Step 6: Send a Push Notification Message to a Mobile Endpoint using Amazon SNS and Baidu......................................................................................................................... 63 Getting Started with GCM ..................................................................................................... 67 GCM Prerequisites ...................................................................................................... 68 Step 1: Create a Google API Project and Enable the GCM Service....................................... 68 Step 2: Obtain the Server API Key.................................................................................. 68 Step 3: Obtain a Registration ID from GCM...................................................................... 69 Step 4: Send a Message to a Mobile Endpoint using GCM.................................................. 70 Getting Started with MPNS.................................................................................................... 72 MPNS Prerequisites..................................................................................................... 72 Step 1: Set Up Your Windows Phone App to Receive Push Notifications Messages................. 73 Step 2: Get a Push Notification URI from MPNS................................................................ 73 Step 3: Create a Windows Developer Account.................................................................. 73 Step 4: Upload TLS Certificate....................................................................................... 73 Step 5: Send a Push Notification Message to a Windows Phone app using Amazon SNS and MPNS........................................................................................................................ 73 Getting Started with WNS ..................................................................................................... 75 WNS Prerequisites ...................................................................................................... 76 Step 1: Set Up Your App to Receive Push Notifications Messages........................................ 76 Step 2: Get a Push Notification URI from WNS.................................................................. 76 Step 3: Get a Package Security Identifier from WNS.......................................................... 76 Step 4: Get a Secret Key from WNS................................................................................ 76 Step 5: Send a Push Notification Message to an App using Amazon SNS and WNS................ 77 Using Amazon SNS Mobile Push............................................................................................ 78 Register Your Mobile App with AWS................................................................................ 78 Add Device Tokens or Registration IDs............................................................................ 80 Send a Direct Message to a Mobile Device....................................................................... 83 Send Messages to Mobile Devices Subscribed to a Topic................................................... 83 Send Custom Platform-Specific Payloads to Mobile Devices................................................ 84 Application Attributes for Message Delivery Status.................................................................... 86 Configuring Message Delivery Status Attributes with the AWS Management Console.............. 86 Amazon SNS Message Delivery Status CloudWatch Log Examples...................................... 87 Configuring Message Delivery Status Attributes with the AWS SDKs.................................... 88 Platform Response Codes............................................................................................. 88 Amazon SNS TTL................................................................................................................ 89 TTL Message Attributes for Push Notification Services....................................................... 89 Precedence Order for Determining TTL........................................................................... 90 Specifying TTL with the AWS Management Console.......................................................... 90 Specifying TTL with the AWS SDKs................................................................................ 90 Amazon SNS Mobile Push APIs............................................................................................. 91 API Errors .......................................................................................................................... 92 Sending Messages to Amazon SQS Queues.................................................................................... 99 Step 1. Get the ARN of the queue and the topic....................................................................... 100 Step 2. Give permission to the Amazon SNS topic to send messages to the Amazon SQS queue.... 101 Step 3. Subscribe the queue to the Amazon SNS topic............................................................. 102 Step 4. Give users permissions to the appropriate topic and queue actions.................................. 102 API Version 2010-03-31 iv Amazon Simple Notification Service Developer Guide Adding a policy to an IAM user or group......................................................................... 103 Adding a policy to a topic or queue................................................................................ 103 Step 5.Test it .................................................................................................................... 104 Sending Messages to a Queue in a Different Account.............................................................. 105 Queue Owner Creates Subscription.............................................................................. 105 User Who Does Not Own the Queue Creates Subscription................................................ 107 Using an AWS CloudFormation Template to Create a Topic that Sends Messages to Amazon SQS Queues ............................................................................................................................ 108 Using an AWS CloudFormation Template to Set Up Topics and Queues Within an AWS Account.................................................................................................................... 109 Sending and Receiving SMS Notifications...................................................................................... 114 Task 1: Assign a Topic Display Name..................................................................................... 115 Task 2: Subscribe to a Topic Using the SMS Protocol............................................................... 117 Task 3: Publish a Message .................................................................................................. 119 Task 4: Cancel SMS Subscriptions........................................................................................ 121 Sending Messages to HTTP/HTTPS Endpoints............................................................................... 123 Step 1: Make sure your endpoint is ready to process Amazon SNS messages.............................. 124 Step 2: Subscribe the HTTP/HTTPS endpoint to the Amazon SNS topic...................................... 127 Step 3: Confirm the subscription........................................................................................... 128 Step 4: Set the delivery retry policy for the subscription (optional)............................................... 128 Step 5: Give users permissions to publish to the topic (optional)................................................. 128 Step 6: Send messages to the HTTP/HTTPS endpoint............................................................. 130 Setting Amazon SNS Delivery Retry Policies for HTTP/HTTPS Endpoints.................................... 130 Applying Delivery Policies to Topics and Subscriptions...................................................... 132 Setting the Maximum Receive Rate............................................................................... 133 Immediate Retry Phase............................................................................................... 136 Pre-Backoff Phase ..................................................................................................... 137 Backoff Phase ........................................................................................................... 138 Post-Backoff Phase .................................................................................................... 140 Certificate Authorities for HTTPS Endpoints............................................................................ 141 Verifying Message Signatures .............................................................................................. 154 Example Code for an Endpoint Java Servlet........................................................................... 157 Message Attributes .................................................................................................................... 161 Message Attribute Items and Validation.................................................................................. 161 Data Types........................................................................................................................ 162 Reserved Message Attributes .............................................................................................. 162 Using Message Attributes with the AWS SDKs........................................................................ 163 Monitoring Amazon SNS with CloudWatch..................................................................................... 164 Access CloudWatch Metrics for Amazon SNS......................................................................... 164 Set CloudWatch Alarms for Amazon SNS Metrics.................................................................... 165 Amazon SNS Metrics.......................................................................................................... 166 Dimensions for Amazon Simple Notification Service Metrics...................................................... 166 Logging Amazon SNS API Calls By Using CloudTrail........................................................................ 168 Amazon SNS Information in CloudTrail .................................................................................. 168 Understanding Amazon SNS Log File Entries......................................................................... 169 Appendix: Message and JSON Formats......................................................................................... 172 HTTP/HTTPS Headers ....................................................................................................... 172 HTTP/HTTPS Subscription Confirmation JSON Format............................................................ 173 HTTP/HTTPS Notification JSON Format................................................................................ 175 HTTP/HTTPS Unsubscribe Confirmation JSON Format............................................................ 176 SetSubscriptionAttributes Delivery Policy JSON Format............................................................ 178 SetTopicAttributes Delivery Policy JSON Format...................................................................... 178 Appendix: Large Payload and Raw Message Delivery....................................................................... 180 Enabling Raw Message Delivery with the AWS Management Console......................................... 180 Document History ...................................................................................................................... 182 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) consume or receive the message or notification over one of the supported protocols (i.e., Amazon SQS, HTTP/S, email, SMS) 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. 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 following sections: • What is Amazon SNS – The rest of this section includes a video that introduces Amazon SNS and walks you through the example presented in Getting Started with Amazon Simple Notification Service (p.4), and presents common use-case scenarios. • Getting Started – The Getting Started with Amazon Simple Notification Service (p.4) 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: • Managing Access to Your Amazon SNS Topics (p.13) 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 with CloudWatch (p.164) Amazon SNS and CloudWatch are integrated so you can collect, view, and analyze metrics for every active Amazon SNS topic. • Sending Amazon SNS Messages to Amazon SQS Queues (p.99) You can use Amazon SNS to send messages to one or more Amazon SQS queues. • Sending and Receiving SMS Notifications Using Amazon SNS (p.114) You can use Amazon Simple Notification Service (Amazon SNS) to send SMS notifications to SMS-enabled mobile phones and smart phones. • Sending Amazon SNS Messages to HTTP/HTTPS Endpoints (p.123) You can use Amazon SNS to send notification messages to one or more HTTP or HTTPS endpoints. Accessing Amazon SNS You can access Amazon SNS using the AWS Management Console, the command line interface (CLI)—http://www.amazonaws.cn/developertools/3688), and by writing code directly to the Amazon SNS Query API—, see Amazon Simple Notification Service API Reference. We also provide SDKs that enable you to access Amazon SNS from your preferred programming language. The SDKs contain functionality that automatically takes care of tasks such as: • Cryptographically signing your service requests • Retrying requests • Handling error responses API Version 2010-03-31 2 Amazon Simple Notification Service Developer Guide Common Scenarios For a list of available SDKs, go to Tools for Amazon Web Services Common Amazon SNS Scenarios Fanout The "fanout" scenario is when an Amazon SNS message is sent to a topic and then replicated and pushed to multiple Amazon SQS queues, HTTP endpoints, or email addresses.This allows for parallel asynchronous processing. For example, you could develop an application that sends an Amazon SNS message to a topic whenever an order is placed for a product.Then, the Amazon SQS queues that are subscribed to that topic would receive identical notifications for the new order.The Amazon EC2 server instance attached to one of the queues could handle the processing or fulfillment of the order while the other server instance could be attached to a data warehouse for analysis of all orders received. Another way to use "fanout" is to replicate data sent to your production environment with your development environment. Expanding upon the previous example, you could subscribe yet another queue to the same topic for new incoming orders.Then, by attaching this new queue to your development environment, you could continue to improve and test your application using data received from your production environment. For more information about sending Amazon SNS messages to Amazon SQS queues, see Sending Amazon SNS Messages to Amazon SQS Queues (p.99). For more information about sending Amazon SNS messages to HTTP/S endpoints, see Sending Amazon SNS Messages to HTTP/HTTPS Endpoints (p.123). Application and System Alerts Application and system alerts are notifications, triggered by predefined thresholds, sent to specified users by SMS and/or email. For example, since many AWS services use Amazon SNS, you can receive immediate notification when an event occurs, such as a specific change to your AWS Auto Scaling group. Push Email and Text Messaging Push email and text messaging are two ways to transmit messages to individuals or groups via email and/or SMS. For example, you could use Amazon SNS to push targeted news headlines to subscribers by email or SMS. Upon receiving the email or SMS text, interested readers could then choose to learn more by visiting a website or launching an application. For more information about using Amazon SNS to send SMS notifications, see Sending and Receiving SMS Notifications Using Amazon SNS (p.114). Mobile Push Notifications Mobile push notifications enable you to send messages directly to mobile apps. For example, you could use Amazon SNS for sending notifications to an app, indicating that an update is available.The notification message can include a link to download and install the update. For more information about using Amazon SNS to send direct notification messages to mobile endpoints, see Amazon SNS Mobile Push Notifications (p.38) 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 Amazon SNS Mobile Push Notifications (p.38). Topics • Before You Begin (p.4) • Create a Topic (p.4) • Subscribe to a Topic (p.6) • Publish to a Topic (p.6) • Clean Up (p.9) • Using the AWS SDK for Java with Amazon SNS (p.10) Before You Begin To use Amazon SNS, you need an AWS account. If you don't already have one, you'll be prompted to create one when you sign up for Amazon SNS. To sign up for Amazon SNS 1. Go to http://www.amazonaws.cn/sns/ and click Sign Up for Amazon SNS. 2. Follow the on-screen instructions. AWS will notify you by email when your account is active and available for you to use. 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. API Version 2010-03-31 4 Amazon Simple Notification Service Developer Guide Create a Topic To create a topic 1. Sign in to the AWS Management Console and open the Amazon SNS console at https:// console.amazonaws.cn/sns/. 2. Click Create New Topic. The Create New Topic dialog box appears. 3. Enter a topic name in the Topic Name field. The examples that follow use the topic name MyTopic. 4. Click Create Topic. The new topic appears in the Topic Details page. 5. Copy the Topic ARN for the next task. API Version 2010-03-31 5