class AWS::S3

Provides an expressive, object-oriented interface to Amazon S3.

To use Amazon S3 you must first sign up here.

For more information about Amazon S3, see:

Credentials

You can setup default credentials for all AWS services via AWS.config:

AWS.config(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Or you can set them directly on the S3 interface:

s3 = AWS::S3.new(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Buckets Keys and Objects

S3 stores objects in buckets.

To create a bucket:

bucket = s3.buckets.create('mybucket')

To get a bucket:

bucket = s3.buckets[:mybucket]
bucket = s3.buckets['mybucket']

Listing buckets:

s3.buckets.each do |bucket|
  puts bucket.name
end

See {Bucket} and {BucketCollection} for more information on working with S3 buckets.

Listing Objects

Enumerating objects in a bucket:

bucket.objects.each do |object|
  puts object.key #=> no data is fetched from s3, just a list of keys
end

You can limit the list of objects with a prefix, or explore the objects in a bucket as a tree. See {ObjectCollection} for more information.

Reading and Writing to S3

Each object in a bucket has a unique key.

photo = s3.buckets['mybucket'].objects['photo.jpg']

Writing to an S3Object:

photo.write(File.read('/some/photo.jpg'))

Reading from an S3Object:

File.open("/some/path/on/disk.jpg", "w") do |f|
  f.write(photo.read)
end

See {S3Object} for more information on reading and writing to S3.

Public Instance Methods

buckets() click to toggle source

@return [BucketCollection] Returns a collection that represents all

buckets in the account.

# File lib/aws/s3.rb, line 130
def buckets
  BucketCollection.new(:config => @config)
end

each(*args, &block) click to toggle source

# File spec/aws/s3/tree_spec.rb, line 23
def each(*args, &block)
  super(&block)
end

expect_copy_with_storage_class(sc) click to toggle source

# File spec/aws/s3/s3_object_spec.rb, line 1011
def expect_copy_with_storage_class(sc)
  client.should_receive(:copy_object).
    with(:bucket_name => "foobucket",
         :key => "foo",
         :copy_source => "foobucket/foo",
         :metadata_directive => "COPY",
         :storage_class => sc)
end

expect_file_body(path) click to toggle source

# File spec/aws/s3/client_spec.rb, line 548
def expect_file_body(path)
  stream = double("stream")
  File.should_receive(:open).
    with(path, *file_opts).and_return(stream)
  File.should_receive(:size).
    with(path).and_return(12)
  http_handler.should_receive(:handle).with do |req, resp|
    req.body_stream.should be(stream)
    req.headers["Content-Length"].should == 12
  end
end

expect_markers(client, value) click to toggle source

# File spec/aws/s3/bucket_version_collection_spec.rb, line 43
def expect_markers(client, value)
  client.should_receive(:list_object_versions).
    with(hash_including(:key_marker => value+"_key",
                        :version_id_marker => value+"_version_id"))
end

policy_conditions(post) click to toggle source

# File spec/aws/s3/presigned_post_spec.rb, line 31
def policy_conditions(post)
  JSON.load(Base64.decode64(post.policy))["conditions"]
end

should_add_param_as(opt_name, param_name) click to toggle source

# File spec/aws/s3/client_spec.rb, line 28
def should_add_param_as opt_name, param_name
  param = nil
  client.with_http_handler do |req, resp|
    param = req.get_param(param_name).value
  end.send(method, opts.merge(opt_name => 'value'))
  param.should == 'value'
end

should_determine_content_length_for(data, length) click to toggle source

# File spec/aws/s3/client_spec.rb, line 606
def should_determine_content_length_for data, length
  content_length_header = nil
  client = with_http_handler do |req, resp|
    content_length_header = req.headers['Content-Length']
  end
  client.send(method, opts.merge(:data => data))
  content_length_header.should == length
end

should_fail(name) click to toggle source

# File spec/aws/s3/client_spec.rb, line 1715
def should_fail(name)
  client.valid_bucket_name?(name).should be_false
end

should_pass(name) click to toggle source

# File spec/aws/s3/client_spec.rb, line 1711
def should_pass(name)
  client.valid_bucket_name?(name).should be_true
end

stub_markers(resp, value) click to toggle source

# File spec/aws/s3/bucket_version_collection_spec.rb, line 38
def stub_markers(resp, value)
  resp.stub(:next_key_marker).and_return(value+"_key")
  resp.stub(:next_version_id_marker).and_return(value+"_version_id")
end

stub_members(resp, quantity) click to toggle source

# File spec/aws/s3/bucket_version_collection_spec.rb, line 49
def stub_members(resp, quantity)
  resp.stub(:contents).
    and_return([double('v1',
                       :key => 'a',
                       :version_id => 'v1',
                       :delete_marker? => true,
                       :latest? => true),
                double('v1',
                       :key => 'b',
                       :version_id => 'v1',
                       :delete_marker? => false,
                       :latest? => false),
                double('v1',
                       :key => 'c',
                       :version_id => 'v1',
                       :delete_marker? => false,
                       :latest? => true)].first(quantity))
end

use_input(input) click to toggle source

# File spec/aws/s3/access_control_list_spec.rb, line 180
def use_input(input)
  acl.owner = input
end

with_http_handler() { |req, resp| ... } click to toggle source

# File spec/aws/s3/client_spec.rb, line 22
def with_http_handler &block
  client.with_http_handler do |req, resp|
    yield(req, resp)
  end
end