-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathREADME.Rmd
103 lines (68 loc) · 5.7 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
# AWS SNS Client Package
**aws.sns** is a simple client package for the Amazon Web Services (AWS) [Simple Notification Service (SNS)](https://aws.amazon.com/sns/) API, which can be used to trigger push messages to a variety of users, devices, and other endpoints. This might be useful for maintaining multi-platform mailing lists, or simply for creating a way to notify yourself when long-running code completes.
To use the package, you will need an AWS account and to enter your credentials into R. Your keypair can be generated on the [IAM Management Console](https://aws.amazon.com/) under the heading *Access Keys*. Note that you only have access to your secret key once. After it is generated, you need to save it in a secure location. New keypairs can be generated at any time if yours has been lost, stolen, or forgotten. The [**aws.iam** package](https://github.com/cloudyr/aws.iam) profiles tools for working with IAM, including creating roles, users, groups, and credentials programmatically; it is not needed to *use* IAM credentials.
A detailed description of how credentials can be specified is provided at: https://github.com/cloudyr/aws.signature/. The easiest way is to simply set environment variables on the command line prior to starting R or via an `Renviron.site` or `.Renviron` file, which are used to set environment variables in R during startup (see `? Startup`). They can be also set within R:
```R
Sys.setenv("AWS_ACCESS_KEY_ID" = "mykey",
"AWS_SECRET_ACCESS_KEY" = "mysecretkey",
"AWS_DEFAULT_REGION" = "us-east-1",
"AWS_SESSION_TOKEN" = "mytoken")
```
## Code Examples
The main purpose of Amazon SNS is to be able to push messages to different endpoints (e.g., Email, SMS, a Simple Queue Service queue, etc.). To do this, you have to create a *topic*, *subscribe* different endpoints (e.g., user email addresses) to that topic, and then *publish* to the topic. You can subscribe different types of endpoints to the same topic and, similarly, publish different messages to each type of endpoint simultaneously.
To create a topic, use `create_topic` and configure it using `set_topic_attrs`. The `name` argument in `create_topic` is a private label for you to keep track of topics. To use a topic, you need to use `set_topic_attrs` to configure a public display name that will be visible to subscribers:
```{r}
library("aws.sns")
topic <- create_topic(name = "TestTopic")
set_topic_attrs(topic, attribute = c(DisplayName = "Publicly visible topic name"))
```
To add a subscription to a topic:
```{r}
subscribe(topic, "[email protected]", "email")
#subscribe(topic, "1-111-555-1234", "sms") # SMS example
```
You can confirm the status of subscriptions using `list_subscriptions`:
```{r}
list_subscriptions(topic)
```
Subscriptions need to be confirmed by the endpoint. For example, an SMS endpoint will require an SMS response to an subscription invitation message. Subscriptions can be removed using `unsubscribe` (or whatever method is described in the invitation message); thus subscriptions can be handled by both users and administrator (you).
The endpoint will then receive a confirmation message, like the following, to confirm the subscription:
If they accept the invitation, the user will receive a confirmation of their subscription:
To publish a message, use `publish`:
```{r}
publish(topic = topic, message = "This is a test message!", subject = "Hello!")
```
By default, the message is sent to all platforms:
This may not be ideal if multiple dissimilar endpoints are subscribed to the same topic (e.g., SMS and email). This can be resolved by maintaining separate Topics or, more easily, by sending different messages to each type of endpoint:
```{r}
msgs <- list()
msgs$default = "This is the default message." # required
msgs$email = "This is a test email that will be sent to email addresses only."
msgs$sms = "This is a test SMS that will be sent to phone numbers only."
msgs$http = "This is a test message that will be sent to http URLs only."
publish(topic = topic, message = msgs, subject = "Hello!")
```
In addition to the standard endpoints ("http", "https", "email", "email-json", "sms", "sqs", "application"), it is possible to create endpoints for mobile platform applications. [See the SNS Developer Guide for further details](http://docs.aws.amazon.com/sns/latest/dg/SNSMobilePush.html).
It is also possible to give other AWS accounts permission to view or publish to a topic using `add_permission`. For example, you may want to have multiple administrators who share responsibility for publishing messages to the topic. Permissions can be revoked using `remove_permission`.
## Installation
[](https://cran.r-project.org/package=aws.sns)
[](https://travis-ci.org/cloudyr/aws.sns)
[](https://codecov.io/github/cloudyr/aws.sns?branch=master)
This package is not yet on CRAN. To install the latest development version you can install from the cloudyr drat repository:
```R
# latest stable version
install.packages("aws.sns", repos = c(cloudyr = "http://cloudyr.github.io/drat", getOption("repos")))
```
Or, to pull a potentially unstable version directly from GitHub:
```R
if(!require("remotes")){
install.packages("remotes")
}
remotes::install_github("cloudyr/aws.sns")
```
---
[](https://github.com/cloudyr)