Class: Aws::S3

Inherits:
Object
  • Object
show all
Defined in:
lib/s3/s3.rb

Overview

Aws::S3 – RightScale’s Amazon S3 interface

The Aws::S3 class provides a complete interface to Amazon’s Simple Storage Service. For explanations of the semantics of each call, please refer to Amazon’s documentation at developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=48

See examples below for the bucket and buckets methods.

Error handling: all operations raise an Aws::AwsError in case of problems. Note that transient errors are automatically retried.

It is a good way to use domain naming style getting a name for the buckets. See docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingBucket.html about the naming convention for the buckets. This case they can be accessed using a virtual domains.

Let assume you have 3 buckets: ‘awesome-bucket’, ‘awesome_bucket’ and ‘AWEsomE-bucket’. The first ones objects can be accessed as: http:// awesome-bucket.s3.amazonaws.com/key/object

But the rest have to be accessed as: http:// s3.amazonaws.com/awesome_bucket/key/object and http:// s3.amazonaws.com/AWEsomE-bucket/key/object

See: docs.amazonwebservices.com/AmazonS3/2006-03-01/VirtualHosting.html for better explanation.

Defined Under Namespace

Classes: Bucket, Grantee, Key, Owner

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(aws_access_key_id = nil, aws_secret_access_key = nil, params = {}) ⇒ S3

Create a new handle to an S3 account. All handles share the same per process or per thread HTTP connection to Amazon S3. Each handle is for a specific account. The params are passed through as-is to Aws::S3Interface.new

Params is a hash:

{:server       => 's3.amazonaws.com'   # Amazon service host: 's3.amazonaws.com'(default)
 :port         => 443                  # Amazon service port: 80 or 443(default)
 :protocol     => 'https'              # Amazon service protocol: 'http' or 'https'(default)
 :virtual_hosting  => false            # Force using bucket virtual hosting: https://s3.amazonaws.com/my-bucket vs. https://my-bucket.s3.amazonaws.com
 :connection_mode  => :default         # options are
                                              :default (will use best known safe (as in won't need explicit close) option, may change in the future)
                                              :per_request (opens and closes a connection on every request)
                                              :single (one thread across entire app)
                                              :per_thread (one connection per thread)
 :logger       => Logger Object}       # Logger instance: logs to STDOUT if omitted }



90
91
92
 
# File 'lib/s3/s3.rb', line 90

def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
  @interface = S3Interface.new(aws_access_key_id, aws_secret_access_key, params)
end

Instance Attribute Details

#interface ⇒ Object (readonly)

Returns the value of attribute interface.



71
72
73
 
# File 'lib/s3/s3.rb', line 71

def interface
  @interface
end

Instance Method Details

#bucket(name, create = false, perms = nil, headers = {}) ⇒ Object

Retrieve an individual bucket. If the bucket does not exist and create is set, a new bucket is created on S3. Launching this method with create=true may affect on the bucket’s ACL if the bucket already exists. Returns a Aws::S3::Bucket instance or nil if the bucket does not exist and create is not set.

s3 = Aws::S3.new(aws_access_key_id, aws_secret_access_key)
bucket1 = s3.bucket('my_awesome_bucket_1')
bucket1.keys  #=> exception here if the bucket does not exists
 ...
bucket2 = s3.bucket('my_awesome_bucket_2', true)
bucket2.keys  #=> list of keys
# create a bucket at the European location with public read access
bucket3 = s3.bucket('my-awesome-bucket-3', true, 'public-read', :location => :eu)

see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html
(section: Canned Access Policies)



130
131
132
133
134
135
136
137
138
 
# File 'lib/s3/s3.rb', line 130

def bucket(name, create=false, perms=nil, headers={})
  headers['x-amz-acl'] = perms if perms
  @interface.create_bucket(name, headers) if create
  return Bucket.new(self, name)
  # The old way below was too slow and unnecessary because it retreived all the buckets every time.
  #            owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
#       buckets.each { |bucket| return bucket if bucket.name == name }
#      nil
end

#buckets ⇒ Object

Retrieve a list of buckets. Returns an array of Aws::S3::Bucket instances.

# Create handle to S3 account
s3 = Aws::S3.new(aws_access_key_id, aws_secret_access_key)
my_buckets_names = s3.buckets.map{|b| b.name}
puts "Buckets on S3: #{my_bucket_names.join(', ')}"



104
105
106
107
108
109
 
# File 'lib/s3/s3.rb', line 104

def buckets
  @interface.list_all_my_buckets.map! do |entry|
    owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
    Bucket.new(self, entry[:name], entry[:creation_date], owner)
  end
end

#close_connection ⇒ Object 



94
95
96
 
# File 'lib/s3/s3.rb', line 94

def close_connection
  @interface.close_connection
end