Class: Fog::AWS::S3

Inherits:
Object
  • Object
show all
Defined in:
lib/fog/aws/s3.rb,
lib/fog/aws/models/s3/object.rb,
lib/fog/aws/models/s3/bucket.rb,
lib/fog/aws/models/s3/objects.rb,
lib/fog/aws/models/s3/buckets.rb,
lib/fog/aws/requests/s3/put_bucket.rb,
lib/fog/aws/requests/s3/put_bucket.rb,
lib/fog/aws/requests/s3/get_object.rb,
lib/fog/aws/requests/s3/get_object.rb,
lib/fog/aws/requests/s3/put_object.rb,
lib/fog/aws/requests/s3/put_object.rb,
lib/fog/aws/requests/s3/get_bucket.rb,
lib/fog/aws/requests/s3/get_bucket.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_object.rb,
lib/fog/aws/requests/s3/delete_object.rb,
lib/fog/aws/requests/s3/delete_bucket.rb,
lib/fog/aws/requests/s3/delete_bucket.rb,
lib/fog/aws/requests/s3/get_request_payment.rb,
lib/fog/aws/requests/s3/get_request_payment.rb,
lib/fog/aws/requests/s3/get_bucket_location.rb,
lib/fog/aws/requests/s3/get_bucket_location.rb,
lib/fog/aws/requests/s3/put_request_payment.rb,
lib/fog/aws/requests/s3/put_request_payment.rb

Defined Under Namespace

Classes: Bucket, Buckets, Object, Objects

Class Method Summary collapse

Instance Method Summary collapse

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(options={})
  @aws_access_key_id      = options[:aws_access_key_id]
  @aws_secret_access_key  = options[:aws_secret_access_key]
  @hmac       = HMAC::SHA1.new(@aws_secret_access_key)
  @host       = options[:host]      || 's3.amazonaws.com'
  @port       = options[:port]      || 443
  @scheme     = options[:scheme]    || 'https'
  @connection = Fog::Connection.new("#{@scheme}://#{@host}:#{@port}")
end

Class Method Details

.dataObject


9
10
11
# File 'lib/fog/aws/s3.rb', line 9

def self.data
  @data
end

.reloadObject


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/bucket.rb"
  load "fog/aws/models/s3/buckets.rb"
  load "fog/aws/models/s3/object.rb"
  load "fog/aws/models/s3/objects.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_dataObject


6
7
8
# File 'lib/fog/aws/s3.rb', line 6

def self.reset_data
  @data = { :buckets => {} }
end

Instance Method Details

#bucketsObject


5
6
7
# File 'lib/fog/aws/models/s3/buckets.rb', line 5

def buckets
  Fog::AWS::S3::Buckets.new(:connection => self)
end

#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, options = {})
  headers = { 'x-amz-copy-source' => "/#{source_bucket_name}/#{source_object_name}" }.merge!(options)
  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

#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, options = {})
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  query = ''
  for key, value in options
    query << "#{key}=#{value};"
  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, options = {}, &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'] = options['If-Modified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if options['If-Modified-Since']
  headers['If-Unmodified-Since'] = options['If-Unmodified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if options['If-Modified-Since']
  headers.merge!(options)
  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_serviceObject

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, options={})
  headers = {}
  headers['If-Modified-Since'] = options['If-Modified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if options['If-Modified-Since']
  headers['If-Unmodified-Since'] = options['If-Unmodified-Since'].utc.strftime("%a, %d %b %Y %H:%M:%S +0000") if options['If-Modified-Since']
  headers.merge!(options)
  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, options = {})
  if options['LocationConstraint']
    data =
  <<-DATA
    <CreateBucketConfiguration>
      <LocationConstraint>#{options['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, options = {})
  data = parse_data(data)
  headers = data[:headers].merge!(options)
  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