Class: Fog::AWS::S3

Inherits:
Object
  • Object
show all
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

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
70
71
72
73
 
# File 'lib/fog/aws/s3.rb', line 61

def initialize(options={})
  unless @aws_access_key_id = options[:aws_access_key_id]
    raise ArgumentError.new('aws_access_key_id is required to access ec2')
  end
  unless @aws_secret_access_key = options[:aws_secret_access_key]
    raise ArgumentError.new('aws_secret_access_key is required to access ec2')
  end
  @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

.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, 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

#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, options = {})
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  query = ''
  for key, value in options
    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, 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_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, 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