From 2a70f3aba74c07dd4147078163d34c6b5ebe50be Mon Sep 17 00:00:00 2001 From: "Thomas J. Leeper" Date: Thu, 8 Dec 2016 17:46:07 +0000 Subject: [PATCH] update documentation for CRAN release --- .Rbuildignore | 1 + DESCRIPTION | 11 ++-- NAMESPACE | 7 +- NEWS | 6 +- R/http.r | 50 +++++++-------- R/package.R | 5 +- R/publish.r | 33 ++++++---- R/subscriptions.r | 86 ++++++++++++------------- R/topic.r | 117 +++++++++++++--------------------- README.Rmd | 36 +++++++---- README.md | 64 ++++++++++++++----- man/add_permission.Rd | 14 ++-- man/aws.sns-package.Rd | 3 +- man/create_topic.Rd | 35 ---------- man/delete_topic.Rd | 35 ---------- man/get_subscription_attrs.Rd | 3 +- man/list_topics.Rd | 38 ----------- man/publish.Rd | 33 ++++++---- man/snsHTTP.Rd | 24 +++---- man/subscribe.Rd | 47 -------------- man/subscriptions.Rd | 57 +++++++++++++++++ man/topics.Rd | 56 ++++++++++++++++ man/unsubscribe.Rd | 35 ---------- 23 files changed, 372 insertions(+), 424 deletions(-) delete mode 100644 man/create_topic.Rd delete mode 100644 man/delete_topic.Rd delete mode 100644 man/list_topics.Rd delete mode 100644 man/subscribe.Rd create mode 100644 man/subscriptions.Rd create mode 100644 man/topics.Rd delete mode 100644 man/unsubscribe.Rd diff --git a/.Rbuildignore b/.Rbuildignore index 707ab0b..d279e5f 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -2,3 +2,4 @@ README.Rmd drat.sh knitreadme.sh +CONTRIBUTING.md diff --git a/DESCRIPTION b/DESCRIPTION index 40661e5..0408f09 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,18 +1,19 @@ Package: aws.sns Type: Package Title: AWS SNS Client Package -Version: 0.1.3 -Date: 2016-03-17 +Version: 0.1.5 +Date: 2016-12-08 Author: Thomas J. Leeper Maintainer: Thomas J. Leeper Description: A simple client package for the Amazon Web Services (AWS) Simple Notification Service (SNS) API. License: GPL (>= 2) Imports: + stats, httr, - XML, + xml2, jsonlite, - aws.signature + aws.signature (>= 0.2.6) URL: https://github.com/cloudyr/aws.sns BugReports: https://github.com/cloudyr/aws.sns/issues -RoxygenNote: 5.0.1.9000 +RoxygenNote: 5.0.1 diff --git a/NAMESPACE b/NAMESPACE index d294ba4..97392ff 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -5,6 +5,8 @@ export(create_topic) export(delete_topic) export(get_subscription_attrs) export(get_topic_attrs) +export(list_subscriptions) +export(list_topics) export(publish) export(remove_permission) export(set_subscription_attrs) @@ -13,8 +15,9 @@ export(snsHTTP) export(subscribe) export(unsubscribe) import(httr) -importFrom(XML,xmlParse) -importFrom(XML,xmlToList) importFrom(aws.signature,signature_v4_auth) importFrom(jsonlite,fromJSON) importFrom(jsonlite,toJSON) +importFrom(stats,setNames) +importFrom(xml2,as_list) +importFrom(xml2,read_xml) diff --git a/NEWS b/NEWS index 0a918ab..98ab07c 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,7 @@ -# CHANGES TO aws.sns 0.1 # +# CHANGES TO aws.sns 0.1.5 + +* Add examples and cleanup documentation. + +# CHANGES TO aws.sns 0.1.1 * Initial release. diff --git a/R/http.r b/R/http.r index 71c4947..cbf65af 100644 --- a/R/http.r +++ b/R/http.r @@ -1,31 +1,25 @@ #' @title Execute SNS API Request #' @description This is the workhorse function to execute calls to the SNS API. -#' @details -#' This function constructs and signs an SNS API request and returns the -#' results thereof, or relevant debugging information in the case of error. -#' -#' @param query An optional named list containing query string parameters and -#' their character values. -#' @param region A character string containing an AWS region. If missing, the -#' default \dQuote{us-east-1} is used. -#' @param key A character string containing an AWS Access Key ID. The default -#' is pulled from environment variable \dQuote{AWS_ACCESS_KEY_ID}. -#' @param secret A character string containing an AWS Secret Access Key. The -#' default is pulled from environment variable \dQuote{AWS_SECRET_ACCESS_KEY}. +#' @param query An optional named list containing query string parameters and their character values. +#' @param region A character string containing an AWS region. If missing, the default \dQuote{us-east-1} is used. +#' @param key A character string containing an AWS Access Key ID. The default is pulled from environment variable \dQuote{AWS_ACCESS_KEY_ID}. +#' @param secret A character string containing an AWS Secret Access Key. The default is pulled from environment variable \dQuote{AWS_SECRET_ACCESS_KEY}. +#' @param session_token Optionally, a character string containing an AWS temporary Session Token. If missing, defaults to value stored in environment variable \dQuote{AWS_SESSION_TOKEN}. #' @param ... Additional arguments passed to \code{\link[httr]{GET}}. -#' @return If successful, a named list. Otherwise, a data structure of class -#' \dQuote{aws-error} containing any error message(s) from AWS and information -#' about the request attempt. +#' @return If successful, a named list. Otherwise, a data structure of class \dQuote{aws-error} containing any error message(s) from AWS and information about the request attempt. +#' @details This function constructs and signs an SNS API request and returns the results thereof, or relevant debugging information in the case of error. #' @author Thomas J. Leeper #' @import httr #' @importFrom jsonlite fromJSON -#' @importFrom XML xmlParse xmlToList +#' @importFrom xml2 read_xml as_list #' @importFrom aws.signature signature_v4_auth #' @export snsHTTP <- function(query, region = Sys.getenv("AWS_DEFAULT_REGION","us-east-1"), key = Sys.getenv("AWS_ACCESS_KEY_ID"), - secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"), ...) { + secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"), + session_token = Sys.getenv("AWS_SESSION_TOKEN"), + ...) { d_timestamp <- format(Sys.time(), "%Y%m%dT%H%M%SZ", tz = "UTC") if (key == "") { H <- add_headers(`x-amz-date` = d_timestamp) @@ -40,16 +34,22 @@ snsHTTP <- function(query, canonical_headers = list(host = paste0("sns.",region,".amazonaws.com"), `x-amz-date` = d_timestamp), request_body = "", - key = key, secret = secret) - H <- add_headers(`x-amz-date` = d_timestamp, - `x-amz-content-sha256` = S$BodyHash, - Authorization = S$SignatureHeader) + key = key, + secret = secret, + session_token = session_token) + headers <- list(`x-amz-date` = d_timestamp, + `x-amz-content-sha256` = S$BodyHash, + Authorization = S$SignatureHeader) + if (!is.null(session_token) && session_token != "") { + headers[["x-amz-security-token"]] <- session_token + } + H <- do.call(add_headers, headers) } r <- GET(paste0("https://sns.",region,".amazonaws.com"), H, query = query, ...) if (http_status(r)$category == "client error") { - x <- try(xmlToList(xmlParse(content(r, "text"))), silent = TRUE) + x <- try(as_list(read_xml(content(r, "text", encoding = "UTF-8"))), silent = TRUE) if (inherits(x, "try-error")) { - x <- try(fromJSON(content(r, "text"))$Error, silent = TRUE) + x <- try(fromJSON(content(r, "text", encoding = "UTF-8"))$Error, silent = TRUE) } warn_for_status(r) h <- headers(r) @@ -58,9 +58,9 @@ snsHTTP <- function(query, attr(out, "request_string_to_sign") <- S$StringToSign attr(out, "request_signature") <- S$SignatureHeader } else { - out <- try(fromJSON(content(r, "text")), silent = TRUE) + out <- try(fromJSON(content(r, "text", encoding = "UTF-8")), silent = TRUE) if(inherits(out, "try-error")) - out <- structure(content(r, "text"), "unknown") + out <- structure(content(r, "text", encoding = "UTF-8"), "unknown") } return(out) } diff --git a/R/package.R b/R/package.R index 95686fc..cd303c6 100644 --- a/R/package.R +++ b/R/package.R @@ -1,11 +1,10 @@ #' @title aws.sqs #' @description AWS SNS Client Package -#' @details A simple client package for the Amazon Web Services (AWS) Simple -#' Notification Service (SNS) REST API. +#' @details A simple client package for the Amazon Web Services (AWS) Simple Notification Service (SNS) REST API. #' @name aws.sns-package #' @aliases aws.sns-package aws.sns #' @docType package -#' @author Thomas J. Leeper +#' @author Thomas J. Leeper #' @keywords package NULL diff --git a/R/publish.r b/R/publish.r index e3508e0..13e86dc 100644 --- a/R/publish.r +++ b/R/publish.r @@ -1,5 +1,11 @@ #' @title Publish to a topic or endpoint #' @description Publish a message to a specified topic or application endpoint. +#' @param topic Optionally, a character string containing an SNS Topic Amazon Resource Name (ARN). Must specify \code{topic} or \code{endpoint}. +#' @param endpoint Optionally, a character string containing an SNS Application Endpoint ARN. Must specify \code{topic} or \code{endpoint}. +#' @param message Either a single character string containing a message to be sent to all endpoints, or a named list of messages to be sent to specific endpoints (where the names of each element correspond to endpoints). +#' @param subject Optionally, a character string containing a subject line (e.g., to be used for an email endpoint). +#' @param ... Additional arguments passed to \code{\link{snsHTTP}}. +#' @return If successful, a character string containing a message ID. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. #' @details #' Publishes a message to a topic or an application endpoint. Messages can be #' the same for all endpoints or customized so that, for example, a short @@ -7,20 +13,21 @@ #' topic while longer messages are sent to email endpoints, etc. The allowed #' message types are: default, email, email-json, sqs, sms, http, https, and #' application. +#' @examples +#' \dontrun{ +#' top <- create_topic("new_topic") +#' +#' # simple notifications +#' publish(top, message = "This is a notification message", subject = "Notification!") +#' +#' # endpoint-specific notification +#' publish(top, message = list(sms = "This is an sms message", +#' email = "This is an email"), +#' subject = "Notification!") +#' +#' delete_topic(top) +#' } #' -#' @param topic Optionally, a character string containing an SNS Topic Amazon -#' Resource Name (ARN). Must specify \code{topic} or \code{endpoint}. -#' @param endpoint Optionally, a character string containing an SNS Application -#' Endpoint ARN. Must specify \code{topic} or \code{endpoint}. -#' @param message Either a single character string containing a message to be -#' sent to all endpoints, or a named list of messages to be sent to specific -#' endpoints (where the names of each element correspond to endpoints). -#' @param subject Optionally, a character string containing a subject line -#' (e.g., to be used for an email endpoint). -#' @param ... Additional arguments passed to \code{\link{snsHTTP}}. -#' @return If successful, a character string containing a message ID. -#' Otherwise, a data structure of class \dQuote{aws_error} containing any error -#' message(s) from AWS and information about the request attempt. #' @author Thomas J. Leeper #' @references #' \href{http://docs.aws.amazon.com/sns/latest/api/API_Publish.html}{Publish} diff --git a/R/subscriptions.r b/R/subscriptions.r index d1bbd1d..847a175 100644 --- a/R/subscriptions.r +++ b/R/subscriptions.r @@ -1,64 +1,60 @@ -#' @title Subscribe to a topic +#' @rdname subscriptions +#' @title Subscribe/Unsubscribe to a topic #' @description Subscribes an endpoint to the specified SNS topic. +#' @param topic A character string containing an SNS Topic Amazon Resource Name (ARN). +#' @param endpoint A character string containing the endpoint to be subscribed (e.g., an email address). +#' @param protocol The allowed protocol types are: default, email, email-json, sqs, sms, http, https, and application. +#' @param subscription A character string containing an SNS Subscription Amazon Resource Name (ARN). +#' @param ... Additional arguments passed to \code{\link{snsHTTP}}. +#' @return If successful, a character string containing a subscription ARN. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. #' @details -#' Initiates a subscription of an endpoint to an SNS topic. For example, this -#' is used to add an email address endpoint to a 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 \code{\link{unsubscribe}} (or whatever method is described in -#' the invitation message); thus subscriptions can be handled by both users and -#' administrator (you). +#' \code{subscribe} initiates a subscription of an endpoint to an SNS topic. For example, this is used to add an email address endpoint to a 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 \code{\link{unsubscribe}} (or whatever method is described in the invitation message); thus subscriptions can be handled by both users and administrator (you). #' -#' @param topic A character string containing an SNS Topic Amazon Resource Name -#' (ARN). -#' @param endpoint A character string containing the endpoint to be subscribed -#' (e.g., an email address). -#' @param protocol The allowed protocol types are: default, email, email-json, -#' sqs, sms, http, https, and application. -#' @param ... Additional arguments passed to \code{\link{snsHTTP}}. -#' @return If successful, a character string containing a subscription ARN. -#' Otherwise, a data structure of class \dQuote{aws_error} containing any error -#' message(s) from AWS and information about the request attempt. +#' \code{unsubscribe} unsubscribes an endpoint from an SNS topic. #' @author Thomas J. Leeper -#' @seealso \code{link{unsubscribe}} \code{\link{list_subscriptions}} +#' @examples +#' \dontrun{ +#' top <- create_topic("new_topic") +#' # email subscription +#' subscribe(top, "example@example.com", protocol = "email") +#' +#' # sms subscription +#' subscribe(top, "555-123-4567", protocol = "sms") +#' +#' delete_topic(top) +#' } +#' +#' @seealso \code{\link{list_subscriptions}} #' @references #' \href{http://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html}{Subscribe} +#' \href{http://docs.aws.amazon.com/sns/latest/api/API_Unsubscribe.html}{Unsubscribe} #' @export subscribe <- function(topic, endpoint, protocol, ...) { query_list <- list(TopicArn = topic, Action = "Subscribe") query_list$Endpoint <- endpoint protocol_list <- c("http","https","email","email-json","sms","sqs","application") - if(!protocol %in% protocol_list) + if (!protocol %in% protocol_list) { stop("'protocol' must be one of: ", paste0('"',protocol_list,'"', collapse = ", ")) - else + } else { query_list$Protocol <- protocol + } out <- snsHTTP(query = query_list, ...) - if(inherits(out, "aws_error")) + if (inherits(out, "aws_error")) { return(out) + } structure(out$SubscribeResponse$SubscribeResult$SubscriptionArn, RequestId = out$SubscribeResponse$ResponseMetadata$RequestId) } -#' @title Unsubscribe from a topic -#' @description Cancels an endpoint's subscription to a topic. -#' @details Unsubscribes an endpoint from an SNS topic. -#' @param subscription A character string containing an SNS Subscription Amazon -#' Resource Name (ARN). -#' @param ... Additional arguments passed to \code{\link{snsHTTP}}. -#' @return If successful, a logical \code{TRUE}. Otherwise, a data structure of -#' class \dQuote{aws_error} containing any error message(s) from AWS and -#' information about the request attempt. -#' @author Thomas J. Leeper -#' @seealso \code{link{unsubscribe}} \code{\link{list_subscriptions}} -#' @references -#' \href{http://docs.aws.amazon.com/sns/latest/api/API_Unsubscribe.html}{Unsubscribe} +#' @rdname subscriptions #' @export unsubscribe <- function(subscription, ...) { query_list <- list(SubscriptionArn = subscription, Action = "Unsubscribe") out <- snsHTTP(query = query_list, ...) - if(inherits(out, "aws_error")) + if (inherits(out, "aws_error")) { return(out) + } structure(TRUE, RequestId = out$UnsubscribeResponse$ResponseMetadata$RequestId) } @@ -82,8 +78,7 @@ unsubscribe <- function(subscription, ...) { #' \dQuote{aws_error} containing any error message(s) from AWS and information #' about the request attempt. #' @author Thomas J. Leeper -#' @seealso \code{link{subscribe}} \code{link{unsubscribe}} -#' \code{link{list_subscriptions}} +#' @seealso \code{link{subscribe}} \code{link{list_subscriptions}} #' @references #' \href{http://docs.aws.amazon.com/sns/latest/api/API_GetSubscriptionAttributes.html}{GetSubscriptionAttributes} #' \href{http://docs.aws.amazon.com/sns/latest/api/API_SetSubscriptionAttributes.html}{SetSubscriptionAttributes} @@ -91,8 +86,9 @@ unsubscribe <- function(subscription, ...) { get_subscription_attrs <- function(subscription, ...) { query_list <- list(SubscriptionArn = subscription, Action = "GetSubscriptionAttributes") out <- snsHTTP(query = query_list, ...) - if(inherits(out, "aws_error")) + if (inherits(out, "aws_error")) { return(out) + } structure(out$GetSubscriptionAttributesResponse$GetSubscriptionAttributesResult$Attributes, RequestId = out$GetSubscriptionAttributesResponse$ResponseMetadata$RequestId) } @@ -101,15 +97,16 @@ get_subscription_attrs <- function(subscription, ...) { #' @export set_subscription_attrs <- function(subscription, attribute, ...) { query_list <- list(SubscriptionArn = subscription, Action = "SetSubscriptionAttributes") - if(any(!names(attribute) %in% c("DeliveryPolicy","RawMessageDelivery"))) + if (any(!names(attribute) %in% c("DeliveryPolicy","RawMessageDelivery"))) { stop("Attribute name must be 'DeliveryPolicy' or 'RawMessageDelivery'") - else { + } else { query_list$AttributeName <- names(attribute) query_list$AttributeValue <- attribute[[1]] } out <- snsHTTP(query = query_list, ...) - if(inherits(out, "aws_error")) + if (inherits(out, "aws_error")) { return(out) + } structure(TRUE, RequestId = out$SetSubscriptionAttributesResponse$ResponseMetadata$RequestId) } @@ -135,8 +132,9 @@ set_subscription_attrs <- function(subscription, attribute, ...) { #' @author Thomas J. Leeper #' @seealso \code{link{subscribe}} \code{link{unsubscribe}} #' \code{link{get_subscription_attrs}} -#' @references -#' \href{http://docs.aws.amazon.com/sns/latest/api/API_ListSubscriptions.html}{ListSubscriptions} +#' @references \href{http://docs.aws.amazon.com/sns/latest/api/API_ListSubscriptions.html}{ListSubscriptions} +#' @importFrom stats setNames +#' @export list_subscriptions <- function(topic, token, ...) { if (missing(topic)) { query_list <- list(Action = "ListSubscriptions") diff --git a/R/topic.r b/R/topic.r index e40fea3..848c010 100644 --- a/R/topic.r +++ b/R/topic.r @@ -1,19 +1,29 @@ -#' @title Create a topic -#' @description Create an SNS topic -#' @details -#' Create a new topic. The \code{name} is a private name for the topic. Use -#' \code{\link{set_topic_attrs}} to set a publicly visible name for the topic. -#' -#' @aliases create_topic +#' @rdname topics +#' @title Manage topics +#' @description Create, delete, and list topics #' @param name A character string containing a (private) name for the topic. +#' @param topic A character string containing an SNS Topic Amazon Resource Name (ARN). +#' @param token A paging paramter used to return additional pages of results. This will be available in the \dQuote{NextToken} attribute of a previous call to \code{list_topics}. #' @param ... Additional arguments passed to \code{\link{snsHTTP}}. -#' @return If successful, a character string containing an SNS Topic ARN. -#' Otherwise, a data structure of class \dQuote{aws_error} containing any error -#' message(s) from AWS and information about the request attempt. +#' @return For \code{create_topic}: If successful, a character string containing an SNS Topic ARN. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +#' For \code{delete_topic}: If successful, a logical \code{TRUE}. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +#' For \code{list_topics}: If successful, a data frame. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +#' @details \code{create_topic} creates a new topic. The \code{name} is a private name for the topic. Use \code{\link{set_topic_attrs}} to set a publicly visible name for the topic. \code{delete_topic} deletes a named topic. \code{list_topics} lists all currently available topics. +#' +#' \code{list_topics} lists topics. Up to 100 subscriptions are returned by each request. The \code{token} argument can be used to return additional results. #' @author Thomas J. Leeper +#' @examples +#' \dontrun{ +#' top <- create_topic("new_topic") +#' get_topic_attrs(top) +#' list_topics() +#' delete_topic(top) +#' } #' @seealso \code{link{delete_topic}} #' @references -#' \href{http://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html}{CreateTopic} +#' \href{http://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html}{CreateTopic} +#' \href{http://docs.aws.amazon.com/sns/latest/api/API_DeleteTopic.html}{DeleteTopic} +#' \href{http://docs.aws.amazon.com/sns/latest/api/API_ListTopics.html}{ListTopics} #' @export create_topic <- function(name, ...) { query_list <- list(Action = "CreateTopic") @@ -32,20 +42,7 @@ create_topic <- function(name, ...) { RequestId = out$CreateTopicResponse$ResponseMetadata$RequestId) } -#' @title Delete a topic -#' @aliases delete_topic -#' @description Delete an SNS topic -#' @details Delete an existing topic. -#' @param topic A character string containing an SNS Topic Amazon Resource Name -#' (ARN). -#' @param ... Additional arguments passed to \code{\link{snsHTTP}}. -#' @return If successful, a logical \code{TRUE}. Otherwise, a data structure of -#' class \dQuote{aws_error} containing any error message(s) from AWS and -#' information about the request attempt. -#' @author Thomas J. Leeper -#' @seealso \code{link{create_topic}} -#' @references -#' \href{http://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html}{CreateTopic} +#' @rdname topics #' @export delete_topic <- function(topic, ...) { out <- snsHTTP(query = list(TopicArn = topic, Action = "DeleteTopic"), ...) @@ -56,16 +53,30 @@ delete_topic <- function(topic, ...) { RequestId = out$DeleteTopicResponse$ResponseMetadata$RequestId) } +#' @rdname topics +#' @export +list_topics <- function(token, ...) { + if (missing(token)) { + out <- snsHTTP(query = list(Action = "ListTopics"), ...) + } else { + out <- snsHTTP(query = list(Action = "ListTopics", NextToken = token), ...) + } + if (inherits(out, "aws_error")) { + return(out) + } + structure(out$ListTopicsResponse$ListTopicsResult$Topics, + NextToken = out$ListTopicsResponse$ListTopicsResult$NextToken, + RequestId = out$ListTopicsResponse$ResponseMetadata$RequestId) +} + #' @rdname get_topic_attrs #' @title Get/set topic attributes #' @description Get or set topic attributes -#' @details -#' \code{get_topic_attrs} retrieves topic attributes, while \code{set_topic_attrs} can be used to set those attributes. -#' #' @param topic A character string containing an SNS Topic Amazon Resource Name (ARN). #' @param attribute A named, single-element list containing a topic attribute. Name must be either \dQuote{Policy}, \dQuote{DeliveryPolicy}, or \dQuote{DisplayName}. #' @param ... Additional arguments passed to \code{\link{snsHTTP}}. #' @return If successful, for \code{get_topic_attrs}: a named list containing some details of the request, for \code{set_topic_attrs}: a logical \code{TRUE} value. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +#' @details \code{get_topic_attrs} retrieves topic attributes, while \code{set_topic_attrs} can be used to set those attributes. #' @author Thomas J. Leeper #' @references #' \href{http://docs.aws.amazon.com/sns/latest/api/API_GetTopicAttributes.html}{GetTopicAttributes} @@ -98,58 +109,16 @@ set_topic_attrs <- function(topic, attribute, ...) { RequestId = out$SetTopicAttributesResponse$ResponseMetadata$RequestId) } - - - -#' @title List subscriptions for a topic -#' @description Lists subscriptions for a specified topic -#' @details -#' Lists topics. Up to 100 subscriptions are returned by each request. The -#' \code{token} argument can be used to return additional results. -#' -#' @param token A paging paramter used to return additional pages of results. -#' This will be available in the \dQuote{NextToken} attribute of a previous -#' call to \code{list_topics}. -#' @param ... Additional arguments passed to \code{\link{snsHTTP}}. -#' @return If successful, a dataframe containing details of . Otherwise, a data -#' structure of class \dQuote{aws_error} containing any error message(s) from -#' AWS and information about the request attempt. -#' @author Thomas J. Leeper -#' @seealso \code{link{subscribe}} \code{link{unsubscribe}} -#' \code{link{get_subscription_attrs}} -#' @references -#' \href{http://docs.aws.amazon.com/sns/latest/api/API_ListTopics.html}{ListTopics} -list_topics <- function(token, ...) { - if (missing(token)) { - out <- snsHTTP(query = list(Action = "ListTopics"), ...) - } else { - out <- snsHTTP(query = list(Action = "ListTopics", NextToken = token), ...) - } - if (inherits(out, "aws_error")) { - return(out) - } - structure(out$ListTopicsResponse$ListTopicsResult$Topics, - NextToken = out$ListTopicsResponse$ListTopicsResult$NextToken, - RequestId = out$ListTopicsResponse$ResponseMetadata$RequestId) -} - #' @rdname add_permission #' @title Add/remove access permissions #' @aliases add_permission remove_permission #' @description Add/remove permissions to publish to topic -#' @details Add or remove a permission, which grants another AWS account permission to -#' use an SNS topic. -#' -#' @param topic A character string containing an SNS Topic Amazon Resource Name -#' (ARN). +#' @param topic A character string containing an SNS Topic Amazon Resource Name (ARN). #' @param label A character string containing a label for the permission. -#' @param permissions A named list of character strings, where the names of the -#' list are AWS Account ID numbers and the list elements are SNS API endpoints -#' (e.g. \dQuote{Publish}, \dQuote{Subscribe}, \dQuote{Unsubscribe}, etc.). +#' @param permissions A named list of character strings, where the names of the list are AWS Account ID numbers and the list elements are SNS API endpoints (e.g. \dQuote{Publish}, \dQuote{Subscribe}, \dQuote{Unsubscribe}, etc.). #' @param ... Additional arguments passed to \code{\link{snsHTTP}}. -#' @return If successful, a logical \code{TRUE}. Otherwise, a data structure of -#' class \dQuote{aws_error} containing any error message(s) from AWS and -#' information about the request attempt. +#' @return If successful, a logical \code{TRUE}. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +#' @details Add or remove a permission, which grants another AWS account permission to use an SNS topic. #' @author Thomas J. Leeper #' @references #' \href{http://docs.aws.amazon.com/sns/latest/api/API_AddPermission.html}{AddPermission} diff --git a/README.Rmd b/README.Rmd index 17e01b2..bdcb8ea 100644 --- a/README.Rmd +++ b/README.Rmd @@ -1,21 +1,34 @@ -# AWS SNS Client Package # +# AWS SNS Client Package -**aws.sns** is a simple client package for the Amazon Web Services (AWS) [Simple Notification Service (SNS)](http://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. +**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 enter your credentials into R. Your keypair can be generated on the [IAM Management Console](https://console.aws.amazon.com/iam/home?#security_credential) 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. +To use the package, you will need an AWS account and 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. -By default, all **cloudyr** packages look for the access key ID and secret access key in environment variables. You can also use this to specify a default region. For example: +By default, all **cloudyr** packages look for the access key ID and secret access key in environment variables. You can also use this to specify a default region or a temporary "session token". For example: ```R Sys.setenv("AWS_ACCESS_KEY_ID" = "mykey", "AWS_SECRET_ACCESS_KEY" = "mysecretkey", - "AWS_DEFAULT_REGION" = "us-east-1") + "AWS_DEFAULT_REGION" = "us-east-1", + "AWS_SESSION_TOKEN" = "mytoken") ``` -These can alternatively be set on the command line or via an `Renviron.site` or `.Renviron` file ([see here for instructions](http://cran.r-project.org/web/packages/httr/vignettes/api-packages.html)). +These can alternatively be set 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`). +If you work with multiple AWS accounts, another option that is consistent with other Amazon SDKs is to create [a centralized `~/.aws/credentials` file](https://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs), containing credentials for multiple accounts. You can then use credentials from this file on-the-fly by simply doing: -## Code Examples ## +```R +# use your 'default' account credentials +use_credentials() + +# use an alternative credentials profile +use_credentials(profile = "bob") +``` + +Temporary session tokens are stored in environment variable `AWS_SESSION_TOKEN` (and will be stored there by the `use_credentials()` function). The [aws.iam package](https://github.com/cloudyr/aws.iam/) provides an R interface to IAM roles and the generation of temporary session tokens via the security token service (STS). + + +## 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. @@ -77,17 +90,18 @@ In addition to the standard endpoints ("http", "https", "email", "email-json", " 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 ## +## Installation -[![CRAN](http://www.r-pkg.org/badges/version/aws.sns)](http://cran.r-project.org/package=aws.sns) +[![CRAN](https://www.r-pkg.org/badges/version/aws.sns)](https://cran.r-project.org/package=aws.sns) +![Downloads](https://cranlogs.r-pkg.org/badges/aws.polly) [![Travis Build Status](https://travis-ci.org/cloudyr/aws.sns.png?branch=master)](https://travis-ci.org/cloudyr/aws.sns) -[![codecov.io](http://codecov.io/github/cloudyr/aws.sns/coverage.svg?branch=master)](http://codecov.io/github/cloudyr/aws.sns?branch=master) +[![codecov.io](https://codecov.io/github/cloudyr/aws.sns/coverage.svg?branch=master)](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(getOption("repos"), "http://cloudyr.github.io/drat")) +install.packages("aws.sns", repos = c(cloudyr = "http://cloudyr.github.io/drat", getOption("repos"))) ``` Or, to pull a potentially unstable version directly from GitHub: diff --git a/README.md b/README.md index 3352822..f600774 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,34 @@ -# AWS SNS Client Package # +# AWS SNS Client Package -**aws.sns** is a simple client package for the Amazon Web Services (AWS) [Simple Notification Service (SNS)](http://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. +**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. -## Code Examples ## +To use the package, you will need an AWS account and 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. + +By default, all **cloudyr** packages look for the access key ID and secret access key in environment variables. You can also use this to specify a default region or a temporary "session token". For example: + +```R +Sys.setenv("AWS_ACCESS_KEY_ID" = "mykey", + "AWS_SECRET_ACCESS_KEY" = "mysecretkey", + "AWS_DEFAULT_REGION" = "us-east-1", + "AWS_SESSION_TOKEN" = "mytoken") +``` + +These can alternatively be set 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`). + +If you work with multiple AWS accounts, another option that is consistent with other Amazon SDKs is to create [a centralized `~/.aws/credentials` file](https://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs), containing credentials for multiple accounts. You can then use credentials from this file on-the-fly by simply doing: + +```R +# use your 'default' account credentials +use_credentials() + +# use an alternative credentials profile +use_credentials(profile = "bob") +``` + +Temporary session tokens are stored in environment variable `AWS_SESSION_TOKEN` (and will be stored there by the `use_credentials()` function). The [aws.iam package](https://github.com/cloudyr/aws.iam/) provides an R interface to IAM roles and the generation of temporary session tokens via the security token service (STS). + + +## 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. @@ -16,9 +42,9 @@ set_topic_attrs(topic, attribute = c(DisplayName = "Publicly visible topic name" ``` ``` -## list() +## [1] TRUE ## attr(,"RequestId") -## [1] "4e055b41-adb6-5859-b6d1-167545652e16" +## [1] "2d94baa0-931d-5352-a577-ea630d959d5d" ``` To add a subscription to a topic: @@ -31,7 +57,7 @@ subscribe(topic, "me@example.com", "email") ``` ## [1] "pending confirmation" ## attr(,"RequestId") -## [1] "83af083b-0bc0-5654-b443-450fe313e0b3" +## [1] "6e1d1b5a-8bc0-5266-8975-4b991548bc69" ``` ```r @@ -71,9 +97,9 @@ publish(topic = topic, message = "This is a test message!", subject = "Hello!") ``` ``` -## [1] "daec96f6-7e09-57bc-9533-dbc296ddc02c" +## [1] "ea59fd65-de84-5067-9f98-ada6400c8e68" ## attr(,"RequestId") -## [1] "9bcca33f-0a57-5b40-94d0-ee0be2830cd0" +## [1] "55b1f0ee-359d-5c99-a3ca-a02dab150296" ``` By default, the message is sent to all platforms: @@ -94,22 +120,30 @@ publish(topic = topic, message = msgs, subject = "Hello!") ``` ``` -## [1] "bc5f4554-b40d-585b-9a9f-08605cd92871" +## [1] "7614981f-1680-5d0c-9ddf-c8dc88090303" ## attr(,"RequestId") -## [1] "509bfe4e-68e5-5870-b930-b37a8031885a" +## [1] "86899f80-af5c-557f-ae30-cf4331d5ab70" ``` 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 ## +## Installation -[![CRAN](http://www.r-pkg.org/badges/version/aws.sns)](http://cran.r-project.org/package=aws.sns) +[![CRAN](https://www.r-pkg.org/badges/version/aws.sns)](https://cran.r-project.org/package=aws.sns) +![Downloads](https://cranlogs.r-pkg.org/badges/aws.polly) [![Travis Build Status](https://travis-ci.org/cloudyr/aws.sns.png?branch=master)](https://travis-ci.org/cloudyr/aws.sns) -[![codecov.io](http://codecov.io/github/cloudyr/aws.sns/coverage.svg?branch=master)](http://codecov.io/github/cloudyr/aws.sns?branch=master) +[![codecov.io](https://codecov.io/github/cloudyr/aws.sns/coverage.svg?branch=master)](https://codecov.io/github/cloudyr/aws.sns?branch=master) -To install the latest development version from GitHub, run the following: +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("ghit")){ @@ -118,7 +152,5 @@ if(!require("ghit")){ ghit::install_github("cloudyr/aws.sns") ``` -To install the latest version from CRAN, simply use `install.packages("aws.sns")`. - --- [![cloudyr project logo](http://i.imgur.com/JHS98Y7.png)](https://github.com/cloudyr) diff --git a/man/add_permission.Rd b/man/add_permission.Rd index 785bef6..c150976 100644 --- a/man/add_permission.Rd +++ b/man/add_permission.Rd @@ -10,28 +10,22 @@ add_permission(topic, label, permissions, ...) remove_permission(topic, label, ...) } \arguments{ -\item{topic}{A character string containing an SNS Topic Amazon Resource Name -(ARN).} +\item{topic}{A character string containing an SNS Topic Amazon Resource Name (ARN).} \item{label}{A character string containing a label for the permission.} -\item{permissions}{A named list of character strings, where the names of the -list are AWS Account ID numbers and the list elements are SNS API endpoints -(e.g. \dQuote{Publish}, \dQuote{Subscribe}, \dQuote{Unsubscribe}, etc.).} +\item{permissions}{A named list of character strings, where the names of the list are AWS Account ID numbers and the list elements are SNS API endpoints (e.g. \dQuote{Publish}, \dQuote{Subscribe}, \dQuote{Unsubscribe}, etc.).} \item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} } \value{ -If successful, a logical \code{TRUE}. Otherwise, a data structure of -class \dQuote{aws_error} containing any error message(s) from AWS and -information about the request attempt. +If successful, a logical \code{TRUE}. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. } \description{ Add/remove permissions to publish to topic } \details{ -Add or remove a permission, which grants another AWS account permission to -use an SNS topic. +Add or remove a permission, which grants another AWS account permission to use an SNS topic. } \author{ Thomas J. Leeper diff --git a/man/aws.sns-package.Rd b/man/aws.sns-package.Rd index 16d883d..cb9c21e 100644 --- a/man/aws.sns-package.Rd +++ b/man/aws.sns-package.Rd @@ -9,8 +9,7 @@ AWS SNS Client Package } \details{ -A simple client package for the Amazon Web Services (AWS) Simple -Notification Service (SNS) REST API. +A simple client package for the Amazon Web Services (AWS) Simple Notification Service (SNS) REST API. } \author{ Thomas J. Leeper diff --git a/man/create_topic.Rd b/man/create_topic.Rd deleted file mode 100644 index 3fa8653..0000000 --- a/man/create_topic.Rd +++ /dev/null @@ -1,35 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/topic.R -\name{create_topic} -\alias{create_topic} -\title{Create a topic} -\usage{ -create_topic(name, ...) -} -\arguments{ -\item{name}{A character string containing a (private) name for the topic.} - -\item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} -} -\value{ -If successful, a character string containing an SNS Topic ARN. -Otherwise, a data structure of class \dQuote{aws_error} containing any error -message(s) from AWS and information about the request attempt. -} -\description{ -Create an SNS topic -} -\details{ -Create a new topic. The \code{name} is a private name for the topic. Use -\code{\link{set_topic_attrs}} to set a publicly visible name for the topic. -} -\author{ -Thomas J. Leeper -} -\references{ -\href{http://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html}{CreateTopic} -} -\seealso{ -\code{link{delete_topic}} -} - diff --git a/man/delete_topic.Rd b/man/delete_topic.Rd deleted file mode 100644 index f876a2e..0000000 --- a/man/delete_topic.Rd +++ /dev/null @@ -1,35 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/topic.R -\name{delete_topic} -\alias{delete_topic} -\title{Delete a topic} -\usage{ -delete_topic(topic, ...) -} -\arguments{ -\item{topic}{A character string containing an SNS Topic Amazon Resource Name -(ARN).} - -\item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} -} -\value{ -If successful, a logical \code{TRUE}. Otherwise, a data structure of -class \dQuote{aws_error} containing any error message(s) from AWS and -information about the request attempt. -} -\description{ -Delete an SNS topic -} -\details{ -Delete an existing topic. -} -\author{ -Thomas J. Leeper -} -\references{ -\href{http://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html}{CreateTopic} -} -\seealso{ -\code{link{create_topic}} -} - diff --git a/man/get_subscription_attrs.Rd b/man/get_subscription_attrs.Rd index c3b4bd5..a268257 100644 --- a/man/get_subscription_attrs.Rd +++ b/man/get_subscription_attrs.Rd @@ -41,7 +41,6 @@ Thomas J. Leeper \href{http://docs.aws.amazon.com/sns/latest/api/API_SetSubscriptionAttributes.html}{SetSubscriptionAttributes} } \seealso{ -\code{link{subscribe}} \code{link{unsubscribe}} -\code{link{list_subscriptions}} +\code{link{subscribe}} \code{link{list_subscriptions}} } diff --git a/man/list_topics.Rd b/man/list_topics.Rd deleted file mode 100644 index a9192e6..0000000 --- a/man/list_topics.Rd +++ /dev/null @@ -1,38 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/topic.R -\name{list_topics} -\alias{list_topics} -\title{List subscriptions for a topic} -\usage{ -list_topics(token, ...) -} -\arguments{ -\item{token}{A paging paramter used to return additional pages of results. -This will be available in the \dQuote{NextToken} attribute of a previous -call to \code{list_topics}.} - -\item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} -} -\value{ -If successful, a dataframe containing details of . Otherwise, a data -structure of class \dQuote{aws_error} containing any error message(s) from -AWS and information about the request attempt. -} -\description{ -Lists subscriptions for a specified topic -} -\details{ -Lists topics. Up to 100 subscriptions are returned by each request. The -\code{token} argument can be used to return additional results. -} -\author{ -Thomas J. Leeper -} -\references{ -\href{http://docs.aws.amazon.com/sns/latest/api/API_ListTopics.html}{ListTopics} -} -\seealso{ -\code{link{subscribe}} \code{link{unsubscribe}} -\code{link{get_subscription_attrs}} -} - diff --git a/man/publish.Rd b/man/publish.Rd index 5198511..38a2d05 100644 --- a/man/publish.Rd +++ b/man/publish.Rd @@ -7,25 +7,18 @@ publish(topic, endpoint, message, subject, ...) } \arguments{ -\item{topic}{Optionally, a character string containing an SNS Topic Amazon -Resource Name (ARN). Must specify \code{topic} or \code{endpoint}.} +\item{topic}{Optionally, a character string containing an SNS Topic Amazon Resource Name (ARN). Must specify \code{topic} or \code{endpoint}.} -\item{endpoint}{Optionally, a character string containing an SNS Application -Endpoint ARN. Must specify \code{topic} or \code{endpoint}.} +\item{endpoint}{Optionally, a character string containing an SNS Application Endpoint ARN. Must specify \code{topic} or \code{endpoint}.} -\item{message}{Either a single character string containing a message to be -sent to all endpoints, or a named list of messages to be sent to specific -endpoints (where the names of each element correspond to endpoints).} +\item{message}{Either a single character string containing a message to be sent to all endpoints, or a named list of messages to be sent to specific endpoints (where the names of each element correspond to endpoints).} -\item{subject}{Optionally, a character string containing a subject line -(e.g., to be used for an email endpoint).} +\item{subject}{Optionally, a character string containing a subject line (e.g., to be used for an email endpoint).} \item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} } \value{ -If successful, a character string containing a message ID. -Otherwise, a data structure of class \dQuote{aws_error} containing any error -message(s) from AWS and information about the request attempt. +If successful, a character string containing a message ID. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. } \description{ Publish a message to a specified topic or application endpoint. @@ -37,6 +30,22 @@ the same for all endpoints or customized so that, for example, a short topic while longer messages are sent to email endpoints, etc. The allowed message types are: default, email, email-json, sqs, sms, http, https, and application. +} +\examples{ +\dontrun{ + top <- create_topic("new_topic") + + # simple notifications + publish(top, message = "This is a notification message", subject = "Notification!") + + # endpoint-specific notification + publish(top, message = list(sms = "This is an sms message", + email = "This is an email"), + subject = "Notification!") + + delete_topic(top) +} + } \author{ Thomas J. Leeper diff --git a/man/snsHTTP.Rd b/man/snsHTTP.Rd index 59d51b7..fb5b8fc 100644 --- a/man/snsHTTP.Rd +++ b/man/snsHTTP.Rd @@ -6,34 +6,30 @@ \usage{ snsHTTP(query, region = Sys.getenv("AWS_DEFAULT_REGION", "us-east-1"), key = Sys.getenv("AWS_ACCESS_KEY_ID"), - secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"), ...) + secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"), + session_token = Sys.getenv("AWS_SESSION_TOKEN"), ...) } \arguments{ -\item{query}{An optional named list containing query string parameters and -their character values.} +\item{query}{An optional named list containing query string parameters and their character values.} -\item{region}{A character string containing an AWS region. If missing, the -default \dQuote{us-east-1} is used.} +\item{region}{A character string containing an AWS region. If missing, the default \dQuote{us-east-1} is used.} -\item{key}{A character string containing an AWS Access Key ID. The default -is pulled from environment variable \dQuote{AWS_ACCESS_KEY_ID}.} +\item{key}{A character string containing an AWS Access Key ID. The default is pulled from environment variable \dQuote{AWS_ACCESS_KEY_ID}.} -\item{secret}{A character string containing an AWS Secret Access Key. The -default is pulled from environment variable \dQuote{AWS_SECRET_ACCESS_KEY}.} +\item{secret}{A character string containing an AWS Secret Access Key. The default is pulled from environment variable \dQuote{AWS_SECRET_ACCESS_KEY}.} + +\item{session_token}{Optionally, a character string containing an AWS temporary Session Token. If missing, defaults to value stored in environment variable \dQuote{AWS_SESSION_TOKEN}.} \item{...}{Additional arguments passed to \code{\link[httr]{GET}}.} } \value{ -If successful, a named list. Otherwise, a data structure of class -\dQuote{aws-error} containing any error message(s) from AWS and information -about the request attempt. +If successful, a named list. Otherwise, a data structure of class \dQuote{aws-error} containing any error message(s) from AWS and information about the request attempt. } \description{ This is the workhorse function to execute calls to the SNS API. } \details{ -This function constructs and signs an SNS API request and returns the -results thereof, or relevant debugging information in the case of error. +This function constructs and signs an SNS API request and returns the results thereof, or relevant debugging information in the case of error. } \author{ Thomas J. Leeper diff --git a/man/subscribe.Rd b/man/subscribe.Rd deleted file mode 100644 index d938c0e..0000000 --- a/man/subscribe.Rd +++ /dev/null @@ -1,47 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/subscriptions.R -\name{subscribe} -\alias{subscribe} -\title{Subscribe to a topic} -\usage{ -subscribe(topic, endpoint, protocol, ...) -} -\arguments{ -\item{topic}{A character string containing an SNS Topic Amazon Resource Name -(ARN).} - -\item{endpoint}{A character string containing the endpoint to be subscribed -(e.g., an email address).} - -\item{protocol}{The allowed protocol types are: default, email, email-json, -sqs, sms, http, https, and application.} - -\item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} -} -\value{ -If successful, a character string containing a subscription ARN. -Otherwise, a data structure of class \dQuote{aws_error} containing any error -message(s) from AWS and information about the request attempt. -} -\description{ -Subscribes an endpoint to the specified SNS topic. -} -\details{ -Initiates a subscription of an endpoint to an SNS topic. For example, this -is used to add an email address endpoint to a 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 \code{\link{unsubscribe}} (or whatever method is described in -the invitation message); thus subscriptions can be handled by both users and -administrator (you). -} -\author{ -Thomas J. Leeper -} -\references{ -\href{http://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html}{Subscribe} -} -\seealso{ -\code{link{unsubscribe}} \code{\link{list_subscriptions}} -} - diff --git a/man/subscriptions.Rd b/man/subscriptions.Rd new file mode 100644 index 0000000..707e302 --- /dev/null +++ b/man/subscriptions.Rd @@ -0,0 +1,57 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/subscriptions.R +\name{subscribe} +\alias{subscribe} +\alias{unsubscribe} +\title{Subscribe/Unsubscribe to a topic} +\usage{ +subscribe(topic, endpoint, protocol, ...) + +unsubscribe(subscription, ...) +} +\arguments{ +\item{topic}{A character string containing an SNS Topic Amazon Resource Name (ARN).} + +\item{endpoint}{A character string containing the endpoint to be subscribed (e.g., an email address).} + +\item{protocol}{The allowed protocol types are: default, email, email-json, sqs, sms, http, https, and application.} + +\item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} + +\item{subscription}{A character string containing an SNS Subscription Amazon Resource Name (ARN).} +} +\value{ +If successful, a character string containing a subscription ARN. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +} +\description{ +Subscribes an endpoint to the specified SNS topic. +} +\details{ +\code{subscribe} initiates a subscription of an endpoint to an SNS topic. For example, this is used to add an email address endpoint to a 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 \code{\link{unsubscribe}} (or whatever method is described in the invitation message); thus subscriptions can be handled by both users and administrator (you). + +\code{unsubscribe} unsubscribes an endpoint from an SNS topic. +} +\examples{ +\dontrun{ + top <- create_topic("new_topic") + # email subscription + subscribe(top, "example@example.com", protocol = "email") + + # sms subscription + subscribe(top, "555-123-4567", protocol = "sms") + + delete_topic(top) +} + +} +\author{ +Thomas J. Leeper +} +\references{ +\href{http://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html}{Subscribe} +\href{http://docs.aws.amazon.com/sns/latest/api/API_Unsubscribe.html}{Unsubscribe} +} +\seealso{ +\code{\link{list_subscriptions}} +} + diff --git a/man/topics.Rd b/man/topics.Rd new file mode 100644 index 0000000..8066470 --- /dev/null +++ b/man/topics.Rd @@ -0,0 +1,56 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/topic.R +\name{create_topic} +\alias{create_topic} +\alias{delete_topic} +\alias{list_topics} +\title{Manage topics} +\usage{ +create_topic(name, ...) + +delete_topic(topic, ...) + +list_topics(token, ...) +} +\arguments{ +\item{name}{A character string containing a (private) name for the topic.} + +\item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} + +\item{topic}{A character string containing an SNS Topic Amazon Resource Name (ARN).} + +\item{token}{A paging paramter used to return additional pages of results. This will be available in the \dQuote{NextToken} attribute of a previous call to \code{list_topics}.} +} +\value{ +For \code{create_topic}: If successful, a character string containing an SNS Topic ARN. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +For \code{delete_topic}: If successful, a logical \code{TRUE}. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +For \code{list_topics}: If successful, a data frame. Otherwise, a data structure of class \dQuote{aws_error} containing any error message(s) from AWS and information about the request attempt. +} +\description{ +Create, delete, and list topics +} +\details{ +\code{create_topic} creates a new topic. The \code{name} is a private name for the topic. Use \code{\link{set_topic_attrs}} to set a publicly visible name for the topic. \code{delete_topic} deletes a named topic. \code{list_topics} lists all currently available topics. + +\code{list_topics} lists topics. Up to 100 subscriptions are returned by each request. The \code{token} argument can be used to return additional results. +} +\examples{ +\dontrun{ + top <- create_topic("new_topic") + get_topic_attrs(top) + list_topics() + delete_topic(top) +} +} +\author{ +Thomas J. Leeper +} +\references{ +\href{http://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html}{CreateTopic} + \href{http://docs.aws.amazon.com/sns/latest/api/API_DeleteTopic.html}{DeleteTopic} + \href{http://docs.aws.amazon.com/sns/latest/api/API_ListTopics.html}{ListTopics} +} +\seealso{ +\code{link{delete_topic}} +} + diff --git a/man/unsubscribe.Rd b/man/unsubscribe.Rd deleted file mode 100644 index a29a03d..0000000 --- a/man/unsubscribe.Rd +++ /dev/null @@ -1,35 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/subscriptions.R -\name{unsubscribe} -\alias{unsubscribe} -\title{Unsubscribe from a topic} -\usage{ -unsubscribe(subscription, ...) -} -\arguments{ -\item{subscription}{A character string containing an SNS Subscription Amazon -Resource Name (ARN).} - -\item{...}{Additional arguments passed to \code{\link{snsHTTP}}.} -} -\value{ -If successful, a logical \code{TRUE}. Otherwise, a data structure of -class \dQuote{aws_error} containing any error message(s) from AWS and -information about the request attempt. -} -\description{ -Cancels an endpoint's subscription to a topic. -} -\details{ -Unsubscribes an endpoint from an SNS topic. -} -\author{ -Thomas J. Leeper -} -\references{ -\href{http://docs.aws.amazon.com/sns/latest/api/API_Unsubscribe.html}{Unsubscribe} -} -\seealso{ -\code{link{unsubscribe}} \code{\link{list_subscriptions}} -} -