class AWS::S3

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

To use Amazon S3 you must first [sign up here](aws.amazon.com/s3/).

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

Before you can upload files to S3, you need to create a bucket.

s3 = AWS::S3.new
bucket = s3.buckets.create('my-bucket')

If a bucket already exists, you can get a reference to the bucket.

bucket = s3.buckets['my-bucket'] # no request made

You can also enumerate all buckets in your account.

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

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

# Objects

Buckets contain objects. Each object in a bucket has a unique key.

## Getting an Object

If the object already exists, you can get a reference to the object.

# makes no request, returns an AWS::S3::S3Object
obj = bucket.objects['key']

## Reading and Writing an Object

The example above returns an {S3Object}. You call {S3Object#write} and {S3Object#read} to upload to and download from S3 respectively.

# streaming upload a file to S3
obj.write(Pathname.new('/path/to/file.txt'))

# streaming download from S3 to a file on disk
File.open('file.txt', 'wb') do |file|
  obj.read do |chunk|
     file.write(chunk)
  end
end

## Enumerating Objects

You can enumerate objects in your buckets.

# enumerate ALL objects in the bucket (even if the bucket contains
# more than 1k objects)
bucket.objects.each do |obj|
  puts obj.key
end

# enumerate at most 20 objects with the given prefix
bucket.objects.with_prefix('photos/').each(:limit => 20) do |photo|
  puts photo.key
end

See {ObjectCollection} and {S3Object} for more information on working with objects.

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 151
def buckets
  BucketCollection.new(:config => @config)
end