clearbit / s3

Library for accessing S3 objects and buckets, supports EU and US buckets

S3¶ ↑

<img src=“https://travis-ci.org/qoobaa/s3.svg?branch=master” alt=“Build Status” />

S3 library provides access to Amazon’s Simple Storage Service.

It supports all S3 regions through the REST API.

Installation¶ ↑

gem install s3

Usage¶ ↑

Initialize the service¶ ↑

require "s3"
service = S3::Service.new(:access_key_id => "...",
                          :secret_access_key => "...")
#=> #<S3::Service:...>

List buckets¶ ↑

service.buckets
#=> [#<S3::Bucket:first-bucket>,
#    #<S3::Bucket:second-bucket>]

Find bucket¶ ↑

first_bucket = service.buckets.find("first-bucket")
#=> #<S3::Bucket:first-bucket>

or

first_bucket = service.bucket("first-bucket")
#=> #<S3::Bucket:first-bucket>

service.bucket("first-bucket") does not check whether a bucket with the name "first-bucket" exists, but it also does not issue any HTTP requests. Thus, the second example is much faster than buckets.find. You can use first_bucket.exists? to check whether the bucket exists after calling service.bucket.

Create bucket¶ ↑

new_bucket = service.buckets.build("newbucketname")
new_bucket.save(:location => :eu)

Remember that bucket name for EU can’t include “_” (underscore).

Please refer to: docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html for more information about bucket name restrictions.

List objects in a bucket¶ ↑

first_bucket.objects
#=> [#<S3::Object:/first-bucket/lenna.png>,
#    #<S3::Object:/first-bucket/lenna_mini.png>]

Find object in a bucket¶ ↑

object = first_bucket.objects.find("lenna.png")
#=> #<S3::Object:/first-bucket/lenna.png>

Access object metadata (cached from find)¶ ↑

object.content_type
#=> "image/png"

Access object content (downloads the object)¶ ↑

object.content
#=> "\x89PNG\r\n\x1A\n\x00\x00\x00\rIHDR\x00..."

Delete an object¶ ↑

object.destroy
#=> true

Create an object¶ ↑

new_object = bucket.objects.build("bender.png")
#=> #<S3::Object:/synergy-staging/bender.png>

new_object.content = open("bender.png")

new_object.acl = :public_read

new_object.save
#=> true

Please note that new objects are created with “private” ACL by default.

Request access to a private object¶ ↑

Returns a temporary url to the object that expires on the timestamp given. Defaults to one hour expire time.

new_object.temporary_url(Time.now + 1800)

Fetch ACL¶ ↑

object = bucket.objects.find('lenna.png')
object.request_acl # or bucket.request_acl

This will return hash with all users/groups and theirs permissions

Modify ACL¶ ↑

object = bucket.objects.find("lenna.png")
object.copy(:key => "lenna.png", :bucket => bucket, :acl => :public_read)

Upload file direct to amazon¶ ↑

Rails 3¶ ↑

Check the example in this gist, which describes how to use a simple form element to upload files directly to S3.

See also¶ ↑

• rubygems

• repository

• issue tracker

• documentation

Copyright¶ ↑

Copyright © 2009 Jakub Kuźma, Mirosław Boruta. See LICENSE for details.