Class: Fog::AWS::S3
- Inherits:
-
Object
- Object
- Fog::AWS::S3
- Defined in:
- lib/fog/aws/s3.rb,
lib/fog/aws/models/s3/file.rb,
lib/fog/aws/models/s3/files.rb,
lib/fog/aws/models/s3/directory.rb,
lib/fog/aws/models/s3/directories.rb,
lib/fog/aws/requests/s3/get_bucket.rb,
lib/fog/aws/requests/s3/get_bucket.rb,
lib/fog/aws/requests/s3/get_object.rb,
lib/fog/aws/requests/s3/get_object.rb,
lib/fog/aws/requests/s3/put_bucket.rb,
lib/fog/aws/requests/s3/put_bucket.rb,
lib/fog/aws/requests/s3/put_object.rb,
lib/fog/aws/requests/s3/put_object.rb,
lib/fog/aws/requests/s3/copy_object.rb,
lib/fog/aws/requests/s3/copy_object.rb,
lib/fog/aws/requests/s3/get_service.rb,
lib/fog/aws/requests/s3/get_service.rb,
lib/fog/aws/requests/s3/head_object.rb,
lib/fog/aws/requests/s3/head_object.rb,
lib/fog/aws/requests/s3/delete_bucket.rb,
lib/fog/aws/requests/s3/delete_bucket.rb,
lib/fog/aws/requests/s3/delete_object.rb,
lib/fog/aws/requests/s3/delete_object.rb,
lib/fog/aws/requests/s3/get_bucket_location.rb,
lib/fog/aws/requests/s3/get_bucket_location.rb,
lib/fog/aws/requests/s3/get_request_payment.rb,
lib/fog/aws/requests/s3/get_request_payment.rb,
lib/fog/aws/requests/s3/put_request_payment.rb,
lib/fog/aws/requests/s3/put_request_payment.rb
Defined Under Namespace
Classes: Directories, Directory, File, Files
Class Method Summary collapse
Instance Method Summary collapse
-
#copy_object(source_bucket_name, source_object_name, target_bucket_name, target_object_name, options = {}) ⇒ Object
Copy an object from one S3 bucket to another.
-
#delete_bucket(bucket_name) ⇒ Object
Delete an S3 bucket.
-
#delete_object(bucket_name, object_name) ⇒ Object
Delete an object from S3.
- #directories ⇒ Object
-
#get_bucket(bucket_name, options = {}) ⇒ Object
FIXME: implement delimiter.
-
#get_bucket_location(bucket_name) ⇒ Object
Get location constraint for an S3 bucket.
-
#get_object(bucket_name, object_name, options = {}, &block) ⇒ Object
Get an object from S3.
- #get_object_url(bucket_name, object_name, expires) ⇒ Object
-
#get_request_payment(bucket_name) ⇒ Object
Get configured payer for an S3 bucket.
-
#get_service ⇒ Object
List information about S3 buckets for authorized user.
-
#head_object(bucket_name, object_name, options = {}) ⇒ Object
Get headers for an object from S3.
-
#initialize(options = {}) ⇒ S3
constructor
Initialize connection to S3.
-
#put_bucket(bucket_name, options = {}) ⇒ Object
Create an S3 bucket.
-
#put_object(bucket_name, object_name, data, options = {}) ⇒ Object
Create an object in an S3 bucket.
-
#put_request_payment(bucket_name, payer) ⇒ Object
Change who pays for requests to an S3 bucket.
Constructor Details
#initialize(options = {}) ⇒ S3
Initialize connection to S3
Notes
options parameter must include values for :aws_access_key_id and :aws_secret_access_key in order to create a connection
Examples
s3 = S3.new(
:aws_access_key_id => your_aws_access_key_id,
:aws_secret_access_key => your_aws_secret_access_key
)
Parameters
-
options<~Hash> - config arguments for connection. Defaults to {}.
Returns
-
S3 object with connection to aws.
61 62 63 64 65 66 67 68 69 |
# File 'lib/fog/aws/s3.rb', line 61 def initialize(={}) @aws_access_key_id = [:aws_access_key_id] @aws_secret_access_key = [:aws_secret_access_key] @hmac = HMAC::SHA1.new(@aws_secret_access_key) @host = [:host] || 's3.amazonaws.com' @port = [:port] || 443 @scheme = [:scheme] || 'https' @connection = Fog::Connection.new("#{@scheme}://#{@host}:#{@port}") end |
Class Method Details
.data ⇒ Object
9 10 11 |
# File 'lib/fog/aws/s3.rb', line 9 def self.data @data end |
.reload ⇒ Object
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
# File 'lib/fog/aws/s3.rb', line 14 def self.reload load "fog/aws/models/s3/directory.rb" load "fog/aws/models/s3/directories.rb" load "fog/aws/models/s3/file.rb" load "fog/aws/models/s3/files.rb" load "fog/aws/parsers/s3/copy_object.rb" load "fog/aws/parsers/s3/get_bucket.rb" load "fog/aws/parsers/s3/get_bucket_location.rb" load "fog/aws/parsers/s3/get_request_payment.rb" load "fog/aws/parsers/s3/get_service.rb" load "fog/aws/requests/s3/copy_object.rb" load "fog/aws/requests/s3/delete_bucket.rb" load "fog/aws/requests/s3/delete_object.rb" load "fog/aws/requests/s3/get_bucket.rb" load "fog/aws/requests/s3/get_bucket_location.rb" load "fog/aws/requests/s3/get_object.rb" load "fog/aws/requests/s3/get_request_payment.rb" load "fog/aws/requests/s3/get_service.rb" load "fog/aws/requests/s3/head_object.rb" load "fog/aws/requests/s3/put_bucket.rb" load "fog/aws/requests/s3/put_object.rb" load "fog/aws/requests/s3/put_request_payment.rb" if Fog.mocking? reset_data end end |
.reset_data ⇒ Object
6 7 8 |
# File 'lib/fog/aws/s3.rb', line 6 def self.reset_data @data = { :buckets => {} } end |
Instance Method Details
#copy_object(source_bucket_name, source_object_name, target_bucket_name, target_object_name, options = {}) ⇒ Object
Copy an object from one S3 bucket to another
Parameters
-
source_bucket_name<~String> - Name of source bucket
-
source_object_name<~String> - Name of source object
-
target_bucket_name<~String> - Name of bucket to create copy in
-
target_object_name<~String> - Name for new copy of object
-
options<~Hash>:
-
‘x-amz-metadata-directive’<~String> - Specifies whether to copy metadata from source or replace with data in request. Must be in [‘COPY’, ‘REPLACE’]
-
‘x-amz-copy_source-if-match’<~String> - Copies object if its etag matches this value
-
‘x-amz-copy_source-if-modified_since’<~Time> - Copies object it it has been modified since this time
-
‘x-amz-copy_source-if-none-match’<~String> - Copies object if its etag does not match this value
-
‘x-amz-copy_source-if-unmodified-since’<~Time> - Copies object it it has not been modified since this time
-
Returns
-
response<~Excon::Response>:
-
body<~Hash>:
-
‘ETag’<~String> - etag of new object
-
‘LastModified’<~Time> - date object was last modified
-
-
TODO: allow specifying new metadata (support all/some of put_object?)
28 29 30 31 32 33 34 35 36 37 38 |
# File 'lib/fog/aws/requests/s3/copy_object.rb', line 28 def copy_object(source_bucket_name, source_object_name, target_bucket_name, target_object_name, = {}) headers = { 'x-amz-copy-source' => "/#{source_bucket_name}/#{source_object_name}" }.merge!() request({ :expects => 200, :headers => headers, :host => "#{target_bucket_name}.#{@host}", :method => 'PUT', :parser => Fog::Parsers::AWS::S3::CopyObject.new, :path => CGI.escape(target_object_name) }) end |
#delete_bucket(bucket_name) ⇒ Object
Delete an S3 bucket
Parameters
-
bucket_name<~String> - name of bucket to delete
Returns
-
response<~Excon::Response>:
-
status<~Integer> - 204
-
15 16 17 18 19 20 21 22 |
# File 'lib/fog/aws/requests/s3/delete_bucket.rb', line 15 def delete_bucket(bucket_name) request({ :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'DELETE' }) end |
#delete_object(bucket_name, object_name) ⇒ Object
Delete an object from S3
Parameters
-
bucket_name<~String> - Name of bucket containing object to delete
-
object_name<~String> - Name of object to delete
Returns
-
response<~Excon::Response>:
-
status<~Integer> - 204
-
16 17 18 19 20 21 22 23 24 25 |
# File 'lib/fog/aws/requests/s3/delete_object.rb', line 16 def delete_object(bucket_name, object_name) request({ :expects => 204, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'DELETE', :path => CGI.escape(object_name) }) end |
#directories ⇒ Object
5 6 7 |
# File 'lib/fog/aws/models/s3/directories.rb', line 5 def directories Fog::AWS::S3::Directories.new(:connection => self) end |
#get_bucket(bucket_name, options = {}) ⇒ Object
FIXME: implement delimiter
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
# File 'lib/fog/aws/requests/s3/get_bucket.rb', line 36 def get_bucket(bucket_name, = {}) unless bucket_name raise ArgumentError.new('bucket_name is required') end query = '' for key, value in query << "#{key}=#{CGI.escape(value.to_s).gsub(/\+/, '%20')};" end query.chop! request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::AWS::S3::GetBucket.new, :query => query }) end |
#get_bucket_location(bucket_name) ⇒ Object
Get location constraint for an S3 bucket
Parameters
-
bucket_name<~String> - name of bucket to get location constraint for
Returns
-
response<~Excon::Response>:
-
body<~Hash>:
-
‘LocationConstraint’<~String> - Location constraint of the bucket
-
-
16 17 18 19 20 21 22 23 24 25 26 |
# File 'lib/fog/aws/requests/s3/get_bucket_location.rb', line 16 def get_bucket_location(bucket_name) request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::AWS::S3::GetBucketLocation.new, :query => 'location' }) end |
#get_object(bucket_name, object_name, options = {}, &block) ⇒ Object
Get an object from S3
Parameters
-
bucket_name<~String> - Name of bucket to read from
-
object_name<~String> - Name of object to read
-
options<~Hash>:
-
‘If-Match’<~String> - Returns object only if its etag matches this value, otherwise returns 412 (Precondition Failed).
-
‘If-Modified-Since’<~Time> - Returns object only if it has been modified since this time, otherwise returns 304 (Not Modified).
-
‘If-None-Match’<~String> - Returns object only if its etag differs from this value, otherwise returns 304 (Not Modified)
-
‘If-Unmodified-Since’<~Time> - Returns object only if it has not been modified since this time, otherwise returns 412 (Precodition Failed).
-
‘Range’<~String> - Range of object to download
-
Returns
-
response<~Excon::Response>:
-
body<~String> - Contents of object
-
headers<~Hash>:
-
‘Content-Length’<~String> - Size of object contents
-
‘Content-Type’<~String> - MIME type of object
-
‘ETag’<~String> - Etag of object
-
‘Last-Modified’<~String> - Last modified timestamp for object
-
-
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
# File 'lib/fog/aws/requests/s3/get_object.rb', line 26 def get_object(bucket_name, object_name, = {}, &block) unless bucket_name raise ArgumentError.new('bucket_name is required') end unless object_name raise ArgumentError.new('object_name is required') end headers = {} headers['If-Modified-Since'] = ['If-Modified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if ['If-Modified-Since'] headers['If-Unmodified-Since'] = ['If-Unmodified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if ['If-Modified-Since'] headers.merge!() request({ :expects => 200, :headers => headers, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :path => CGI.escape(object_name), :block => block }) end |
#get_object_url(bucket_name, object_name, expires) ⇒ Object
48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
# File 'lib/fog/aws/requests/s3/get_object.rb', line 48 def get_object_url(bucket_name, object_name, expires) unless bucket_name raise ArgumentError.new('bucket_name is required') end unless object_name raise ArgumentError.new('object_name is required') end url({ :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'GET', :path => object_name }, expires) end |
#get_request_payment(bucket_name) ⇒ Object
Get configured payer for an S3 bucket
Parameters
-
bucket_name<~String> - name of bucket to get payer for
Returns
-
response<~Excon::Response>:
-
body<~Hash>:
-
‘Payer’<~String> - Specifies who pays for download and requests
-
-
16 17 18 19 20 21 22 23 24 25 26 |
# File 'lib/fog/aws/requests/s3/get_request_payment.rb', line 16 def get_request_payment(bucket_name) request({ :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'GET', :parser => Fog::Parsers::AWS::S3::GetRequestPayment.new, :query => 'requestPayment' }) end |
#get_service ⇒ Object
List information about S3 buckets for authorized user
Returns
-
response<~Excon::Response>:
-
body<~Hash>:
-
‘Buckets’<~Hash>:
-
‘Name’<~String> - Name of bucket
-
‘CreationTime’<~Time> - Timestamp of bucket creation
-
-
‘Owner’<~Hash>:
-
‘DisplayName’<~String> - Display name of bucket owner
-
‘ID’<~String> - Id of bucket owner
-
-
-
18 19 20 21 22 23 24 25 26 27 28 |
# File 'lib/fog/aws/requests/s3/get_service.rb', line 18 def get_service request({ :expects => 200, :headers => {}, :host => @host, :idempotent => true, :method => 'GET', :parser => Fog::Parsers::AWS::S3::GetService.new, :url => @host }) end |
#head_object(bucket_name, object_name, options = {}) ⇒ Object
Get headers for an object from S3
Parameters
-
bucket_name<~String> - Name of bucket to read from
-
object_name<~String> - Name of object to read
-
options<~Hash>:
-
‘If-Match’<~String> - Returns object only if its etag matches this value, otherwise returns 412 (Precondition Failed).
-
‘If-Modified-Since’<~Time> - Returns object only if it has been modified since this time, otherwise returns 304 (Not Modified).
-
‘If-None-Match’<~String> - Returns object only if its etag differs from this value, otherwise returns 304 (Not Modified)
-
‘If-Unmodified-Since’<~Time> - Returns object only if it has not been modified since this time, otherwise returns 412 (Precodition Failed).
-
‘Range’<~String> - Range of object to download
-
Returns
-
response<~Excon::Response>:
-
body<~String> - Contents of object
-
headers<~Hash>:
-
‘Content-Length’<~String> - Size of object contents
-
‘Content-Type’<~String> - MIME type of object
-
‘ETag’<~String> - Etag of object
-
‘Last-Modified’<~String> - Last modified timestamp for object
-
-
27 28 29 30 31 32 33 34 35 36 37 38 39 |
# File 'lib/fog/aws/requests/s3/head_object.rb', line 27 def head_object(bucket_name, object_name, ={}) headers = {} headers['If-Modified-Since'] = ['If-Modified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if ['If-Modified-Since'] headers['If-Unmodified-Since'] = ['If-Unmodified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if ['If-Modified-Since'] headers.merge!() request({ :expects => 200, :headers => headers, :host => "#{bucket_name}.#{@host}", :method => 'HEAD', :path => CGI.escape(object_name) }) end |
#put_bucket(bucket_name, options = {}) ⇒ Object
Create an S3 bucket
Parameters
-
bucket_name<~String> - name of bucket to create
-
options<~Hash> - config arguments for bucket. Defaults to {}.
-
:location_constraint<~Symbol> - sets the location for the bucket
-
Returns
-
response<~Excon::Response>:
-
status<~Integer> - 200
-
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
# File 'lib/fog/aws/requests/s3/put_bucket.rb', line 17 def put_bucket(bucket_name, = {}) if ['LocationConstraint'] data = <<-DATA <CreateBucketConfiguration> <LocationConstraint>#{['LocationConstraint']}</LocationConstraint> </CreateBucketConfiguration> DATA else data = nil end request({ :expects => 200, :body => data, :headers => {}, :idempotent => true, :host => "#{bucket_name}.#{@host}", :method => 'PUT' }) end |
#put_object(bucket_name, object_name, data, options = {}) ⇒ Object
Create an object in an S3 bucket
Parameters
-
bucket_name<~String> - Name of bucket to create object in
-
object_name<~String> - Name of object to create
-
data<~File> - File or String to create object from
-
options<~Hash>:
-
‘Cache-Control’<~String> - Caching behaviour
-
‘Content-Disposition’<~String> - Presentational information for the object
-
‘Content-Encoding’<~String> - Encoding of object data
-
‘Content-Length’<~String> - Size of object in bytes (defaults to object.read.length)
-
‘Content-MD5’<~String> - Base64 encoded 128-bit MD5 digest of message (defaults to Base64 encoded MD5 of object.read)
-
‘Content-Type’<~String> - Standard MIME type describing contents (defaults to MIME::Types.of.first)
-
‘x-amz-acl’<~String> - Permissions, must be in [‘private’, ‘public-read’, ‘public-read-write’, ‘authenticated-read’]
-
“x-amz-meta-#name” - Headers to be returned with object, note total size of request without body must be less than 8 KB.
-
Returns
-
response<~Excon::Response>:
-
headers<~Hash>:
-
‘ETag’<~String> - etag of new object
-
-
27 28 29 30 31 32 33 34 35 36 37 38 39 |
# File 'lib/fog/aws/requests/s3/put_object.rb', line 27 def put_object(bucket_name, object_name, data, = {}) data = parse_data(data) headers = data[:headers].merge!() request({ :body => data[:body], :expects => 200, :headers => headers, :host => "#{bucket_name}.#{@host}", :idempotent => true, :method => 'PUT', :path => CGI.escape(object_name) }) end |
#put_request_payment(bucket_name, payer) ⇒ Object
Change who pays for requests to an S3 bucket
Parameters
-
bucket_name<~String> - name of bucket to modify
-
payer<~String> - valid values are BucketOwner or Requester
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
# File 'lib/fog/aws/requests/s3/put_request_payment.rb', line 12 def put_request_payment(bucket_name, payer) data = <<-DATA <RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Payer>#{payer}</Payer> </RequestPaymentConfiguration> DATA request({ :body => data, :expects => 200, :headers => {}, :host => "#{bucket_name}.#{@host}", :method => 'PUT', :query => "requestPayment" }) end |