Class: Net::Amazon::S3
- Inherits:
-
Object
- Object
- Net::Amazon::S3
- Includes:
- Enumerable
- Defined in:
- lib/net/amazon/s3.rb,
lib/net/amazon/s3/bucket.rb,
lib/net/amazon/s3/errors.rb,
lib/net/amazon/s3/object.rb
Overview
Net::Amazon::S3
This library implements the Amazon S3 REST API (Rubyfied for your pleasure). Its usage is hopefully pretty straightforward. See below for examples.
- Author
-
Ryan Grove ([email protected])
- Version
-
0.1.0
- Copyright
-
Copyright © 2006 Ryan Grove. All rights reserved.
- License
-
New BSD License (opensource.org/licenses/bsd-license.php)
- Website
A Brief Overview of Amazon S3
Amazon S3 stores arbitrary values (objects) identified by keys and organized into buckets. An S3 bucket is essentially a glorified Hash. Object values can be up to 5 GB in size, and objects can also have up to 2 KB of metadata associated with them.
Bucket names share a global namespace and must be unique across all of S3, but object keys only have to be unique within the bucket in which they are stored.
For more details, visit s3.amazonaws.com
Installation
gem install net-amazon-s3
Examples
Create an instance of the S3 client
require 'rubygems'
require 'net/amazon/s3'
access_key_id = 'DXM37ARQ25519H34E6W2'
secret_access_key = '43HM88c+8kYr/UeFp+shjTnzFgisO5AZzpEO06FU'
s3 = Net::Amazon::S3.new(access_key_id, secret_access_key)
Create a bucket and add an object to it
foo = s3.create_bucket('foo')
foo['bar'] = 'baz' # create object 'bar' and assign it the
# value 'baz'
Upload a large file to the bucket
File.open('mybigmovie.avi', 'rb') do |file|
foo['mybigmovie.avi'] = file
end
Download a large file from the bucket
File.open('mybigmovie.avi', 'wb') do |file|
foo['mybigmovie.avi'].value {|chunk| file.write(chunk) }
end
Get a hash containing all objects in the bucket
objects = foo.get_objects
Get all objects in the bucket whose keys begin with “my”
my_objects = foo.get_objects('my')
Delete the bucket and everything in it
s3.delete_bucket('foo', true)
TODO
-
Owner support
-
Object metadata support
-
ACLs
-
Logging configuration
Defined Under Namespace
Classes: Bucket, Object, S3Error
Constant Summary collapse
- REST_ENDPOINT =
's3.amazonaws.com'
Instance Attribute Summary collapse
-
#access_key_id ⇒ Object
Returns the value of attribute access_key_id.
-
#options ⇒ Object
readonly
Returns the value of attribute options.
-
#secret_access_key ⇒ Object
Returns the value of attribute secret_access_key.
Instance Method Summary collapse
-
#bucket_exist?(bucket_name) ⇒ Boolean
(also: #has_bucket?)
Returns
true
if a bucket with the specifiedbucket_name
exists in this S3 account,false
otherwise. -
#create_bucket(bucket_name) ⇒ Object
Creates a new bucket with the specified
bucket_name
and returns a Bucket object representing it. -
#delete_bucket(bucket_name, recursive = false) ⇒ Object
Deletes the bucket with the specified
bucket_name
. -
#each ⇒ Object
Iterates through the list of buckets.
-
#error?(response) ⇒ Boolean
Raises the appropriate error if the specified Net::HTTPResponse object contains an Amazon S3 error; returns
false
otherwise. -
#get_bucket(bucket_name) ⇒ Object
(also: #[])
Returns a Bucket object representing the specified bucket, or
nil
if the bucket doesn’t exist. -
#get_buckets ⇒ Object
Gets a list of all buckets owned by this account.
-
#initialize(access_key_id, secret_access_key, options = {}) ⇒ S3
constructor
Creates and returns a new S3 client.
-
#request_delete(path, headers = {}) ⇒ Object
Sends a properly-signed DELETE request to the specified S3 path and returns a Net::HTTPResponse object.
-
#request_get(path, headers = {}) ⇒ Object
Sends a properly-signed GET request to the specified S3 path and returns a Net::HTTPResponse object.
-
#request_head(path, headers = {}) ⇒ Object
Sends a properly-signed HEAD request to the specified S3 path and returns a Net::HTTPResponse object.
-
#request_put(path, content = nil, headers = {}) ⇒ Object
Sends a properly-signed PUT request to the specified S3 path and returns a Net::HTTPResponse object.
Constructor Details
#initialize(access_key_id, secret_access_key, options = {}) ⇒ S3
Creates and returns a new S3 client. The following options are available:
:enable_cache
-
Set to
true
to enable intelligent caching of frequently-used requests. This can improve performance, but may result in staleness if other clients are simultaneously modifying the buckets and objects in this S3 account. Default istrue
. :ssl
-
Set to
true
to use SSL for all requests. No verification is performed on the server’s certificate when SSL is used. Default istrue
.
108 109 110 111 112 113 114 115 116 117 118 119 120 |
# File 'lib/net/amazon/s3.rb', line 108 def initialize(access_key_id, secret_access_key, = {}) @access_key_id = access_key_id @secret_access_key = secret_access_key @options = { :enable_cache => true, :ssl => true } @options.merge!() @cache = {} end |
Instance Attribute Details
#access_key_id ⇒ Object
Returns the value of attribute access_key_id.
94 95 96 |
# File 'lib/net/amazon/s3.rb', line 94 def access_key_id @access_key_id end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
95 96 97 |
# File 'lib/net/amazon/s3.rb', line 95 def @options end |
#secret_access_key ⇒ Object
Returns the value of attribute secret_access_key.
94 95 96 |
# File 'lib/net/amazon/s3.rb', line 94 def secret_access_key @secret_access_key end |
Instance Method Details
#bucket_exist?(bucket_name) ⇒ Boolean Also known as: has_bucket?
Returns true
if a bucket with the specified bucket_name
exists in this S3 account, false
otherwise.
124 125 126 |
# File 'lib/net/amazon/s3.rb', line 124 def bucket_exist?(bucket_name) return get_buckets.has_key?(bucket_name) end |
#create_bucket(bucket_name) ⇒ Object
Creates a new bucket with the specified bucket_name
and returns a Bucket object representing it.
132 133 134 135 136 |
# File 'lib/net/amazon/s3.rb', line 132 def create_bucket(bucket_name) error?(request_put("/#{bucket_name}")) @cache.delete(:buckets) return get_bucket(bucket_name) end |
#delete_bucket(bucket_name, recursive = false) ⇒ Object
Deletes the bucket with the specified bucket_name
. If recursive
is true
, all objects contained in the bucket will also be deleted. If recursive
is false
and the bucket is not empty, a S3Error::BucketNotEmpty error will be raised.
142 143 144 145 146 147 148 149 150 151 152 153 154 |
# File 'lib/net/amazon/s3.rb', line 142 def delete_bucket(bucket_name, recursive = false) unless bucket = get_bucket(bucket_name) raise S3Error::NoSuchBucket, 'The specified bucket does not exist' end if recursive bucket.each {|object| bucket.delete_object(object.name) } end @cache.delete(:buckets) return true unless error?(request_delete("/#{bucket_name}")) end |
#each ⇒ Object
Iterates through the list of buckets.
157 158 159 |
# File 'lib/net/amazon/s3.rb', line 157 def each get_buckets.each {|key, value| yield key, value } end |
#error?(response) ⇒ Boolean
Raises the appropriate error if the specified Net::HTTPResponse object contains an Amazon S3 error; returns false
otherwise.
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 |
# File 'lib/net/amazon/s3.rb', line 163 def error?(response) return false if response.is_a?(Net::HTTPSuccess) xml = REXML::Document.new(response.body) unless xml.root.name == 'Error' raise S3Error, "Unknown error: #{response.body}" end error_code = xml.root.elements['Code'].text = xml.root.elements['Message'].text if S3Error.const_defined?(error_code) raise S3Error.const_get(error_code), else raise S3Error, "#{error_code}: #{}" end end |
#get_bucket(bucket_name) ⇒ Object Also known as: []
Returns a Bucket object representing the specified bucket, or nil
if the bucket doesn’t exist.
184 185 186 187 |
# File 'lib/net/amazon/s3.rb', line 184 def get_bucket(bucket_name) return nil unless bucket_exist?(bucket_name) return @cache[:buckets][bucket_name] end |
#get_buckets ⇒ Object
Gets a list of all buckets owned by this account. Returns a Hash of Bucket objects indexed by bucket name.
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 |
# File 'lib/net/amazon/s3.rb', line 193 def get_buckets if @options[:enable_cache] && !@cache[:buckets].nil? return @cache[:buckets] end response = request_get('/') error?(response) xml = REXML::Document.new(response.body) buckets = {} xml.root.elements.each('Buckets/Bucket') do |element| bucket_name = element.elements['Name'].text creation_date = Time.parse(element.elements['CreationDate'].text) buckets[bucket_name] = Bucket.new(self, bucket_name, creation_date) end return @cache[:buckets] = buckets end |
#request_delete(path, headers = {}) ⇒ Object
Sends a properly-signed DELETE request to the specified S3 path and returns a Net::HTTPResponse object.
217 218 219 220 221 222 223 224 225 226 227 |
# File 'lib/net/amazon/s3.rb', line 217 def request_delete(path, headers = {}) http = Net::HTTP.new(REST_ENDPOINT, @options[:ssl] ? 443 : 80) http.use_ssl = @options[:ssl] http.verify_mode = OpenSSL::SSL::VERIFY_NONE http.start do |http| req = sign_request(Net::HTTP::Delete.new(path), nil, headers) return http.request(req) end end |
#request_get(path, headers = {}) ⇒ Object
Sends a properly-signed GET request to the specified S3 path and returns a Net::HTTPResponse object.
When called with a block, yields a Net::HTTPResponse object whose body has not been read; the caller can process it using Net::HTTPResponse.read_body.
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 |
# File 'lib/net/amazon/s3.rb', line 235 def request_get(path, headers = {}) http = Net::HTTP.new(REST_ENDPOINT, @options[:ssl] ? 443 : 80) http.use_ssl = @options[:ssl] http.verify_mode = OpenSSL::SSL::VERIFY_NONE http.start do |http| req = sign_request(Net::HTTP::Get.new(path), nil, headers) if block_given? http.request(req) {|response| yield response } else return http.request(req) end end end |
#request_head(path, headers = {}) ⇒ Object
Sends a properly-signed HEAD request to the specified S3 path and returns a Net::HTTPResponse object.
254 255 256 257 258 259 260 261 262 263 264 |
# File 'lib/net/amazon/s3.rb', line 254 def request_head(path, headers = {}) http = Net::HTTP.new(REST_ENDPOINT, @options[:ssl] ? 443 : 80) http.use_ssl = @options[:ssl] http.verify_mode = OpenSSL::SSL::VERIFY_NONE http.start do |http| req = sign_request(Net::HTTP::Head.new(path), nil, headers) return http.request(req) end end |
#request_put(path, content = nil, headers = {}) ⇒ Object
Sends a properly-signed PUT request to the specified S3 path and returns a Net::HTTPResponse object.
If content
is an open IO stream, the body of the request will be read from the stream.
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 |
# File 'lib/net/amazon/s3.rb', line 271 def request_put(path, content = nil, headers = {}) http = Net::HTTP.new(REST_ENDPOINT, @options[:ssl] ? 443 : 80) http.use_ssl = @options[:ssl] http.verify_mode = OpenSSL::SSL::VERIFY_NONE http.start do |http| req = sign_request(Net::HTTP::Put.new(path), content, headers) if content.is_a?(IO) req.body_stream = content else req.body = content end response = http.request(req) return response end end |