# AWS S3 Client Package #

**aws.s3** is a simple client package for the Amazon Web Services (AWS) Simple Storage Service (S3) REST API. While [other packages](https://github.com/ropensci/webservices#amazon) currently connect R to S3, they do so incompletely (mapping only some of the API endpoints to R) and most implementations rely on the AWS command-line tools, which users may not have installed on their system.

## Installation ##

[![CRAN](http://www.r-pkg.org/badges/version/aws.s3)](http://cran.r-project.org/package=aws.s3)
[![Build Status](https://travis-ci.org/cloudyr/aws.s3.png?branch=master)](https://travis-ci.org/cloudyr/aws.s3) [![codecov.io](http://codecov.io/github/cloudyr/aws.s3/coverage.svg?branch=master)](http://codecov.io/github/cloudyr/aws.s3?branch=master)

This package is not yet on CRAN. To install the latest development version from GitHub, run the following:

```R
if(!require("devtools")){
    install.packages("devtools")
    library("devtools")
}
install_github("cloudyr/aws.signature")
install_github("cloudyr/aws.s3")
```

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. 

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:

```R
Sys.getenv("AWS_ACCESS_KEY_ID" = "mykey",
           "AWS_SECRET_ACCESS_KEY" = "mysecretkey",
           "AWS_DEFAULT_REGION" = "us-east-1")
```

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)).


## Code Examples ##

The package can be used to examine publicly accessible S3 buckets and publicly accessible S3 objects without registering an AWS account. If credentials have been generated in the AWS console and made available in R, you can find your available buckets using:

```
bucketlist()
```

If your credentials are incorrect, this function will return an error. Otherwise, it will return a list of information about the buckets you have access to.

### Buckets ###

To get a listing of all objects in a public bucket, simply call
```
aws.s3::getbucket(bucket = '1000genomes')
```
Amazon maintains a listing of [Public Data Sets](https://aws.amazon.com/datasets) on S3.

To get a listing for all objects in a private bucket, pass your AWS key and secret in as parameters.  (As described above, all functions in `aws.s3` will look for your keys as environment variables by default, greatly simplifying the process of making a s3 request.)

```
aws.s3::getbucket(
  bucket = 'hpk',
  key = YOUR_AWS_ACCESS_KEY,
  secret = YOUR_AWS_SECRET_ACCESS_KEY
)
```

### Objects ###

Coming soon...


---
[![cloudyr project logo](http://i.imgur.com/JHS98Y7.png)](https://github.com/cloudyr)