Create a list from an struct object

Description

Create a list from an struct object

Usage

## S3 method for class 'struct'
as.list(x, ...)

Arguments

Generate a classed http error

Description

This function generates S3 error objects which are passed to stop() to generate classed errors. These can be used in conjunction with tryCatch() to respond differently to different types of failure.

Usage

aws_error(e, call = sys.call(-1), use_call = FALSE)

Arguments

Details

This expands on the condition messages generated by the httr package in httr::http_condition(). In addition to error classes like http_error, http_400, and http_404, this sets attributes on the error condition that contain the unmarshalled error response from AWS for the respective service.

Value

An S3 object that inherits from (e.g.) condition, error, http_error, http_400 and http_404.

See Also

http://adv-r.had.co.nz/Exceptions-Debugging.html#condition-handling for more details about R's condition handling model https://github.com/r-lib/httr/blob/master/R/response-status.r#L310 for the httr inspiration of this condition

Get the service configuration from the service object.

Description

Look up the service configuration from the service object, e.g. when calling svc$operation(), get_config() will look up svc, then get any configuration stored in it, as if the operation function were a method and the service object were a class instance.

Usage

get_config()

Details

get_config must be called directly by the operation function and assigned immediately, not provided as an argument to another function.

We look up the service object then fetch its data so we can both support documentation tooltips in RStudio and also have class-object-like behavior. Alternatives that do not support documentation tooltips in RStudio include reference classes (RC), R6 classes, and any modification of the functions at run-time, e.g. inserting the configuration into the function definition for each operation in a particular service object.

Set or add to handler lists

Description

Set or add to a list of request-handling functions. Request-handling functions must take a request and return a request.

Usage

handlers_set(...)

handlers_add_back(existing, ...)

handlers_add_front(existing, ...)

Arguments

Examples

## Not run: 
# Replace a handler list with a new handler list.
handlers$build <- handlers_set(restxml_build)

# Add a new handler onto the end of an existing handler list.
handlers$build <- handlers_add_back(handlers$build, restxml_build)

# Add a new handler at the beginning of an existing handler list.
handlers$build <- handlers_add_front(handlers$build, restxml_build)

## End(Not run)

Check whether an object is empty

Description

Check whether an object is empty, e.g. has no sub-elements, is NA, or is the empty string.

Usage

is_empty(x)

Arguments

Examples

is_empty(NA) # TRUE
is_empty("") # TRUE
is_empty(list()) # TRUE
is_empty(list(list())) # TRUE

is_empty(1) # FALSE
is_empty(list(1)) # FALSE
is_empty(list(list(1))) # FALSE

Check whether an object is empty for xml builds

Description

Check whether an object is empty, e.g. has no sub-elements, is NA

Usage

is_empty_xml(x)

Arguments

Examples

is_empty_xml(NA) # TRUE
is_empty_xml(list()) # TRUE
is_empty_xml(list(list())) # TRUE

is_empty_xml(1) # FALSE
is_empty_xml("") # FALSE
is_empty_xml(list(1)) # FALSE
is_empty_xml(list(list(1))) # FALSE

List methods that can be paginated from a paws client.

Description

List methods that can be paginated from a paws client.

Usage

list_paginators(svc)

Arguments

Value

character vector of functions that can be paginated.

Examples

## Not run: 
# Note: where svc is a paws client.
list_paginators(svc)

## End(Not run)

Locate AWS credentials

Description

Locate AWS credentials

Usage

locate_credentials(profile = "", anonymous = FALSE)

Arguments

Value

list containing AWS credentials

• access_key_id - (character) AWS access key ID

• secret_access_key - (character) AWS secret access key

• session_token - (character) AWS temporary session token

• access_token - (character) A token that gives a user permission to access certain resources

• expiration - (numeric) Indicates the Unix time when an access token will expire.

• region - (character) The AWS Region used in instantiating the client.

Merges config lists for paws services

Description

Allows config list to be flatten from shorthand.

Usage

merge_config(orig_cfg, param_cfg)

Arguments

Return request handlers for a service

Description

Return request handlers for a given protocol and request signer.

Usage

new_handlers(protocol, signer)

Arguments

See Also

Other API request functions: new_operation(), new_request(), new_service(), send_request()

Examples

# Get the handlers needed for an API using REST-JSON and AWS signature V4.
handlers <- new_handlers("restjson", "v4")

Return an API operation object

Description

Return an API operation object, with information on what to request for a given API operation. For example, the S3 service's "list buckets" operation is named ListBuckets, it requires a GET request, and so on.

Usage

new_operation(
  name,
  http_method,
  http_path,
  host_prefix,
  paginator,
  stream_api = FALSE,
  before_presign_fn = NULL
)

Arguments

See Also

Other API request functions: new_handlers(), new_request(), new_service(), send_request()

Examples

# Save info about the S3 ListBuckets API operation.
op <- new_operation(
  name = "ListBuckets",
  http_method = "GET",
  http_path = "/",
  paginator = list()
)

Return an API request object

Description

Return an API request object with everything needed to make a request.

Usage

new_request(client, operation, params, data, dest = NULL)

Arguments

See Also

Other API request functions: new_handlers(), new_operation(), new_service(), send_request()

Examples

## Not run: 
# Make a request object for the S3 ListBuckets operation.
metadata <- list(
  endpoints = list("*" = list(endpoint = "s3.{region}.amazonaws.com", global = FALSE)),
  service_name = "s3"
)
client <- new_service(metadata, new_handlers("restxml", "s3"))
op <- new_operation("ListBuckets", "GET", "/", list())
params <- list()
data <- tag_add(list(Buckets = list()), list(type = "structure"))
req <- new_request(client, op, params, data)

## End(Not run)

Return an AWS API service object

Description

Return an API service object with information and handlers needed to make API requests.

Usage

new_service(metadata, handlers, cfgs = NULL, operation = Operation())

Arguments

list(
  service_name = "string",
  endpoints = list("region" = list(endpoint = "endpoint", global = FALSE)),
  service_id = "string",
  api_version = "string",
  signing_name = "string"|NULL,
  json_version = "string",
  target_prefix = "string"
)

Region and credentials

new_service requires that you've set your AWS region in one of:

1. AWS_REGION R environment variable

2. AWS_REGION OS environment variable (Linux and macOS)

3. ⁠~/.aws/config⁠ AWS configuration file

new_service also requires that you've set your AWS credentials in one of:

1. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY R environment variables

2. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY OS environment variables (Linux and macOS)

3. ⁠~/.aws/credentials⁠ AWS credentials file

4. IAM role

See Also

new_operation()

Other API request functions: new_handlers(), new_operation(), new_request(), send_request()

Examples

## Not run: 
# Metadata for the S3 API.
metadata <- list(
  service_name = "s3",
  endpoints = list("us-east-1" = list(endpoint = "s3.amazonaws.com", global = FALSE)),
  service_id = "S3",
  api_version = "2006-03-01",
  signing_name = NULL,
  json_version = "",
  target_prefix = ""
)

# Handlers for S3.
handlers <- new_handlers("restxml", "v4")

# Build a service object for S3, containing the information necessary to
# build, send, and receive requests.
service <- new_service(metadata, handlers)

## End(Not run)

Paginate over an operation.

Description

Some AWS operations return results that are incomplete and require subsequent requests in order to attain the entire result set. The process of sending subsequent requests to continue where a previous request left off is called pagination. For example, the list_objects operation of Amazon S3 returns up to 1000 objects at a time, and you must send subsequent requests with the appropriate Marker in order to retrieve the next page of results.

Usage

paginate(
  Operation,
  PageSize = NULL,
  MaxItems = NULL,
  StartingToken = NULL,
  StopOnSameToken = FALSE
)

paginate_lapply(
  Operation,
  FUN,
  ...,
  PageSize = NULL,
  MaxItems = NULL,
  StartingToken = NULL,
  StopOnSameToken = FALSE
)

paginate_sapply(
  Operation,
  FUN,
  ...,
  simplify = TRUE,
  PageSize = NULL,
  MaxItems = NULL,
  StartingToken = NULL,
  StopOnSameToken = FALSE
)

Arguments

Value

list of responses from the operation.

Examples

## Not run: 
# The following example retrieves object list. The request specifies max
# keys to limit response to include only 2 object keys.
paginate(
  svc$list_objects_v2(
    Bucket = "DOC-EXAMPLE-BUCKET"
  ),
  MaxItems = 50
)

## End(Not run)

paws logging system

Description

Ability to configure paws logging system, through the use of paws helper function `paws_config_log` or R:base options function. Users are able to change logging levels without calling paws.common by the use of options e.g. options("paws.log_level" = 2L).

• paws.log_level (integer): The minimum log level that should be tracked

• paws.log_file (character): path for logs to populate, default output logs to console.

• paws.log_timestamp_fmt (character): see format.POSIXct()

Usage

paws_config_log(
  level = 2L,
  file = "",
  timestamp_fmt = "%Y-%m-%d %H:%M:%OS3"
)

Arguments

Examples

# log to a file
temp_file <- tempfile()
paws_config_log(file = temp_file)
unlink(temp_file)

# change log threshold to INFO
paws_config_log(level = 3L)

# reset to default config
paws_config_log()

Clear down paws cache environments

Description

Clears down the cache environments.

• ini_cache: an environment that stores the results from read_ini, mainly used for storing AWS config files.

• os_env_cache: an environment that stores environmental variables from Unix Operating Systems.

Usage

paws_reset_cache()

Iterate over AWS Event Stream connection

Description

Iterate over AWS Event Stream connection

Usage

paws_stream_handler(FUN, .connection = FALSE)

paws_stream_parser(con)

Arguments

Value

list of responses from the operation or a paws_connection object

Examples

## Not run: 
# Developed from:
# https://docs.aws.amazon.com/code-library/latest/ug/python_3_bedrock-runtime_code_examples.html
library(paws)

# Create a Bedrock Runtime client in the AWS Region you want to use.
client <- bedrockruntime(region = "us-east-1")

# Set the model ID, e.g., Titan Text Premier.
model_id <- "amazon.titan-text-premier-v1:0"

# Start a conversation with the user message.
user_message <- "Describe the purpose of a 'hello world' program in one line."
conversation <- list(
  list(
    role = "user",
    content = list(list(text = user_message))
  )
)

resp <- client$converse_stream(
  modelId = model_id,
  messages = conversation,
  inferenceConfig = list(maxTokens = 512, temperature = 0.5, topP = 0.9)
)
resp$stream(\(chunk) chunk$contentBlockDelta$delta$text)
# Note: stream will close connection after all chunks are read

# Get connection object
resp <- client$converse_stream(
  modelId = model_id,
  messages = conversation,
  inferenceConfig = list(maxTokens = 512, temperature = 0.5, topP = 0.9)
)
con <- resp$stream(.connection = T)

# Handle connection object using paws_stream_parser
while (!is.null(chunk <- paws_stream_parser(con))) {
  print(chunk$contentBlockDelta$delta$text)
}

# Note: paws_stream_parser will close connection after all chunks are read

resp <- client$converse_stream(
  modelId = model_id,
  messages = conversation,
  inferenceConfig = list(maxTokens = 512, temperature = 0.5, topP = 0.9)
)

# Or handle connection using httr2::resp_stream_aws
while (!is.null(chunk <- resp_stream_aws(con))) {
  str(chunk)
}
close(con)

# Note: connection needs to be closed manually after all chunks have been read.

## End(Not run)

Populate a list with data from another list

Description

populate copies data from a list (e.g. input by a user) to another list with a similar shape. The second list, called the interface, will generally also contain extra metadata for making API requests, such as names or types.

Usage

populate(input, interface)

Arguments

Examples

# Make an interface with metadata, e.g. type.
interface <- tag_add(list(foo = c(), bar = c()), list(type = "structure"))

# Combine data and the metadata from the interface.
populate(list(foo = 1, bar = 2), interface)

Send a request and handle the response

Description

Send a request and handle the response. Build the HTTP request, send it to AWS, interpret the response, and throw an error if the response is not ok.

Usage

send_request(request)

Arguments

See Also

Other API request functions: new_handlers(), new_operation(), new_request(), new_service()

Examples

## Not run: 
# Send a request and handle the response.
resp <- send_request(req)

## End(Not run)

Add configuration settings to a service object.

Description

set_config adds a given set of configuration settings in cfgs to a service object, i.e. the service object for S3. Configuration settings can include credentials, region, endpoint, etc. These configuration settings will be used whenever an operation is called from that service object.

Usage

set_config(svc, cfgs = list())

Arguments

Details

set_config explicitly makes the credentials property mutable, such that when the SDK retrieves credentials later on, it will save them in the service object. This means that credentials don't need to be fetched on each operation, only if and when the saved credentials expire.

The optional configuration settings can include the following:

list(
  credentials = list(
    creds = list(
      access_key_id = "string",
      secret_access_key = "string",
      session_token = "string"
    ),
    profile = "string"
  ),
  endpoint = "string",
  region = "string"
)

Examples

# Create a config object with custom credentials and endpoint.
config <- set_config(
  svc = list(),
  cfgs = list(
    credentials = list(
      creds = list(
        access_key_id = "abc",
        secret_access_key = "123"
      )
    ),
    endpoint = "https://foo.com"
  )
)

Set service parameters

Description

Help functions for setting the parameters for services

Usage

config(
  credentials = list(creds = list(access_key_id = "", secret_access_key = "",
    session_token = "", access_token = "", expiration = Inf), profile = "", anonymous =
    FALSE),
  endpoint = "",
  region = "",
  close_connection = FALSE,
  max_retries = 3,
  connect_timeout = 60,
  s3_force_path_style = FALSE,
  sts_regional_endpoint = "",
  signature_version = ""
)

credentials(
  creds = list(access_key_id = "", secret_access_key = "", session_token = "",
    access_token = "", expiration = Inf),
  profile = "",
  anonymous = FALSE
)

creds(
  access_key_id = "",
  secret_access_key = "",
  session_token = "",
  access_token = "",
  expiration = Inf
)

Arguments

Value

list set of parameter variables for paws services.

Examples

# set service parameter access_key_id and secret_access_key

config(credentials(creds("dummy", "secret")))

# set service parameter access_key_id and secret_access_key using using lists
config(
    credentials = list(
        creds = list(
            access_key_id = "dummy",
            secret_access_key = "secret"
        )
    )
)

Get, set, and delete object tags

Description

Tags are metadata stored in an object's attributes, used to store types and names needed to make AWS API requests.

tag_get returns the value of the given tag, or "" if the tag doesn't exist.

tag_has returns whether the object has the given tag.

tag_add returns the object after adding the given list of tags and values.

tag_del returns the object after recursively deleting tags in tags, or all tags if NULL.

type returns broadly what type an object is, based on its type tag.

Usage

tag_get(object, tag)

tag_get_all(object)

tag_has(object, tag)

tag_add(object, tags)

tag_del(object, tags = NULL)

type(object)

Arguments

Examples

foo <- list()
foo <- tag_add(foo, list(tag_name = "tag_value"))
tag_has(foo, "tag_name") # TRUE
tag_get(foo, "tag_name") # "tag_value"
tag_get(foo, "not_exist") # ""
foo <- tag_del(foo)
tag_has(foo, "tag_name") # FALSE