Low commit activity in last 3 years
A long-lived project that still receives updates
S3 library provides access to Amazon's Simple Storage Service.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
 Project Readme

S3¶ ↑

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¶ ↑

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