aws.s3 (version 0.3.12)

get_object: Get object

Description

Retrieve an object from an S3 bucket

Usage

get_object(object, bucket, headers = list(), parse_response = FALSE, ...)
save_object(object, bucket, file = basename(object), headers = list(),
  overwrite = TRUE, ...)
head_object(object, bucket, ...)

Arguments

object

Character string with the object key, or an object of class “s3_object”. In most cases, if object is specified as the latter, bucket can be omitted because the bucket name will be extracted from “Bucket” slot in object.

bucket

Character string with the name of the bucket, or an object of class “s3_bucket”.

headers

List of request headers for the REST call.

parse_response

Passed through to s3HTTP, as this function requires a non-default setting. There is probably no reason to ever change this.

…

Additional arguments passed to s3HTTP.

file

An R connection, or file name specifying the local file to save the object into.

overwrite

A logical indicating whether to overwrite file. Passed to write_disk. Default is TRUE.

Value

If file = NULL, a raw object. Otherwise, a character string containing the file name that the object is saved to.

Details

get_object retrieves an object into memory as a raw vector. save_object saves an object to a local file. head_object checks whether an object exists by executing an HTTP HEAD request; this can be useful for checking object headers such as “content-length” or “content-type”.

Some users may find the raw vector response format of get_object unfamiliar. The object will also carry attributes, including “content-type”, which may be useful for deciding how to subsequently process the vector. Two common strategies are as follows. For text content types, running charToRaw may be the most useful first step to make the response human-readable. Alternatively, converting the raw vector into a connection using rawConnection may also be useful, as that can often then be passed to parsing functions just like a file connection would be.

References

API Documentation: GET Object

API Documentation: GET Object torrent

API Document: HEAD Object

See Also

get_bucket, put_object, delete_object

Examples

# NOT RUN {
  # get an object in memory
  ## create bucket
  b <- put_bucket("myexamplebucket")
  
  ## save a dataset to the bucket
  s3save(mtcars, bucket = b, object = "mtcars")
  obj <- get_bucket(b)
  ## get the object in memory
  x <- get_object(obj[[1]])
  load(rawConnection(x))
  "mtcars" %in% ls()

  # save an object locally
  y <- save_object(obj[[1]], file = object[[1]][["Key"]])
  y %in% dir()

  # return object using 'S3 URI' syntax
  get_object("s3://myexamplebucket/mtcars")

  # return parts of an object
  ## use 'Range' header to specify bytes
  get_object(object = obj[[1]], headers = list('Range' = 'bytes=1-120'))
# }