put_object {aws.s3}

Put object

Description

Puts an object into an S3 bucket

Usage

put_object(
  file,
  object,
  bucket,
  multipart = FALSE,
  acl = NULL,
  headers = list(),
  verbose = getOption("verbose", FALSE),
  show_progress = getOption("verbose", FALSE),
  ...
)

put_folder(folder, bucket, ...)

Arguments

file

A character string containing the filename (or full path) of the file you want to upload to S3. Alternatively, an raw vector containing the file can be passed directly, in which case object needs to be specified explicitly.

object

A character string containing the name the object should have in S3 (i.e., its "object key"). If missing, the filename is used.

bucket

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

multipart

A logical indicating whether to use multipart uploads. See http://docs.aws.amazon.com/AmazonS3/latest/dev/mpuoverview.html. If file is less than 100 MB, this is ignored.

acl

A character string indicating a “canned” access control list. By default all bucket contents and objects therein are given the ACL “private”. This can later be viewed using get_acl and modified using put_acl.

headers

List of request headers for the REST call. If multipart = TRUE, this only applies to the initialization call.

verbose

A logical indicating whether to be verbose. Default is given by options("verbose").

show_progress

A logical indicating whether to show a progress bar for uploads. Default is given by options("verbose").

...

Additional arguments passed to s3HTTP.

folder

A character string containing a folder name. (A trailing slash is not required.)

Details

This provide a generic interface for sending files (or serialized, in-memory representations thereof) to S3. Some convenience wrappers are provided for common tasks: e.g., s3save and s3saveRDS.

Note that S3 is a flat file store. So there is no folder hierarchy as in a traditional hard drive. However, S3 allows users to create pseudo-folders by prepending object keys with foldername/. The put_folder function is provided as a high-level convenience function for creating folders. This is not actually necessary as objects with slashes in their key will be displayed in the S3 web console as if they were in folders, but it may be useful for creating an empty directory (which is possible in the web console).

Value

If successful, TRUE.

References

API Documentation

See Also

put_bucket, get_object, delete_object, put_encryption

Examples

## Not run: 
  library("datasets")
  
  # write file to S3
  tmp <- tempfile()
  on.exit(unlink(tmp))
  utils::write.csv(mtcars, file = tmp)
  # put object with an upload progress bar
  put_object(tmp, object = "mtcars.csv", bucket = "myexamplebucket", show_progress = TRUE)

  # create a "folder" in a bucket
  put_folder("example", bucket = "myexamplebucket")
  ## write object to the "folder"
  put_object(tmp, object = "example/mtcars.csv", bucket = "myexamplebucket")

  # write serialized, in-memory object to S3
  x <- rawConnection(raw(0), "w")
  utils::write.csv(mtcars, x)
  put_object(rawConnectionValue(x), object = "mtcars.csv", bucket = "myexamplebucketname")

  # use `headers` for server-side encryption
  ## require appropriate bucket policy
  ## encryption can also be set at the bucket-level using \code{\link{put_encryption}}
  put_object(file = tmp, object = "mtcars.csv", bucket = "myexamplebucket",
             headers = c('x-amz-server-side-encryption' = 'AES256'))

  # alternative "S3 URI" syntax:
  put_object(rawConnectionValue(x), object = "s3://myexamplebucketname/mtcars.csv")
  close(x)

  # read the object back from S3
  read.csv(text = rawToChar(get_object(object = "s3://myexamplebucketname/mtcars.csv")))

  # multi-part uploads for objects over 5MB
  \donttest{
  x <- rnorm(3e6)
  saveRDS(x, tmp)
  put_object(tmp, object = "rnorm.rds", bucket = "myexamplebucket",
             show_progress = TRUE, multipart = TRUE)
  identical(x, s3readRDS("s3://myexamplebucket/rnorm.rds"))
  }

## End(Not run)