Class: Fog::AWS::Storage::Real

Inherits:
Object
  • Object
show all
Extended by:
Deprecation
Includes:
Utils
Defined in:
lib/fog/aws/storage.rb,
lib/fog/aws/requests/storage/get_bucket.rb,
lib/fog/aws/requests/storage/get_object.rb,
lib/fog/aws/requests/storage/put_bucket.rb,
lib/fog/aws/requests/storage/put_object.rb,
lib/fog/aws/requests/storage/copy_object.rb,
lib/fog/aws/requests/storage/get_service.rb,
lib/fog/aws/requests/storage/head_object.rb,
lib/fog/aws/requests/storage/delete_bucket.rb,
lib/fog/aws/requests/storage/delete_object.rb,
lib/fog/aws/requests/storage/get_bucket_acl.rb,
lib/fog/aws/requests/storage/get_object_acl.rb,
lib/fog/aws/requests/storage/get_object_url.rb,
lib/fog/aws/requests/storage/put_bucket_acl.rb,
lib/fog/aws/requests/storage/put_object_url.rb,
lib/fog/aws/requests/storage/get_bucket_logging.rb,
lib/fog/aws/requests/storage/get_object_torrent.rb,
lib/fog/aws/requests/storage/put_bucket_logging.rb,
lib/fog/aws/requests/storage/get_bucket_location.rb,
lib/fog/aws/requests/storage/get_request_payment.rb,
lib/fog/aws/requests/storage/put_request_payment.rb,
lib/fog/aws/requests/storage/get_bucket_versioning.rb,
lib/fog/aws/requests/storage/put_bucket_versioning.rb,
lib/fog/aws/requests/storage/get_bucket_object_versions.rb

Instance Method Summary collapse

Methods included from Deprecation

deprecate

Methods included from Utils

#parse_data, #url

Constructor Details

#initialize(options = {}) ⇒ Real

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.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/fog/aws/storage.rb', line 137

def initialize(options={})
  @aws_access_key_id = options[:aws_access_key_id]
  @aws_secret_access_key = options[:aws_secret_access_key]
  @hmac = Fog::HMAC.new('sha1', @aws_secret_access_key)
  if @endpoint = options[:endpoint]
    endpoint = URI.parse(@endpoint)
    @host = endpoint.host
    @path = endpoint.path
    @port = endpoint.port
    @scheme = endpoint.scheme
  else
    options[:region] ||= 'us-east-1'
    @host = options[:host] || case options[:region]
    when 'eu-west-1'
      's3-eu-west-1.amazonaws.com'
    when 'us-east-1'
      's3.amazonaws.com'
    when 'ap-southeast-1'
      's3-ap-southeast-1.amazonaws.com'
    when 'us-west-1'
      's3-us-west-1.amazonaws.com'
    else
      raise ArgumentError, "Unknown region: #{options[:region].inspect}"
    end
    @path   = options[:path]      || '/'
    @port   = options[:port]      || 443
    @scheme = options[:scheme]    || 'https'
  end
  @connection = Fog::Connection.new("#{@scheme}://#{@host}:#{@port}#{@path}", options[:persistent] || true)
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



28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/fog/aws/requests/storage/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::Storage::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



14
15
16
17
18
19
20
21
 
# File 'lib/fog/aws/requests/storage/delete_bucket.rb', line 14

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



15
16
17
18
19
20
21
22
23
24
 
# File 'lib/fog/aws/requests/storage/delete_object.rb', line 15

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

List information about objects in an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to list object keys from

  • options<~Hash> - config arguments for list. Defaults to {}.

    • ‘delimiter’<~String> - causes keys with the same string between the prefix value and the first occurence of delimiter to be rolled up

    • ‘marker’<~String> - limits object keys to only those that appear lexicographically after its value.

    • ‘max-keys’<~Integer> - limits number of object keys returned

    • ‘prefix’<~String> - limits object keys to those beginning with its value.

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘Delimeter’<~String> - Delimiter specified for query

      • ‘IsTruncated’<~Boolean> - Whether or not the listing is truncated

      • ‘Marker’<~String> - Marker specified for query

      • ‘MaxKeys’<~Integer> - Maximum number of keys specified for query

      • ‘Name’<~String> - Name of the bucket

      • ‘Prefix’<~String> - Prefix specified for query

      • ‘Contents’<~Array>:

        • ‘ETag’<~String>: Etag of object

        • ‘Key’<~String>: Name of object

        • ‘LastModified’<~String>: Timestamp of last modification of object

        • ‘Owner’<~Hash>:

          • ‘DisplayName’<~String> - Display name of object owner

          • ‘ID’<~String> - Id of object owner

        • ‘Size’<~Integer> - Size of object

        • ‘StorageClass’<~String> - Storage class of object



39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/fog/aws/requests/storage/get_bucket.rb', line 39

def get_bucket(bucket_name, options = {})
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::AWS::Storage::GetBucket.new,
    :query    => options
  })
end

#get_bucket_acl(bucket_name) ⇒ Object

Get access control list for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to get access control list for

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘AccessControlPolicy’<~Hash>

        • ‘Owner’<~Hash>:

          • ‘DisplayName’<~String> - Display name of object owner

          • ‘ID’<~String> - Id of object owner

        • ‘AccessControlList’<~Array>:

          • ‘Grant’<~Hash>:

            • ‘Grantee’<~Hash>:

              * 'DisplayName'<~String> - Display name of grantee
* 'ID'<~String> - Id of grantee

              or

              * 'URI'<~String> - URI of group to grant access for

            • ‘Permission’<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]



29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/fog/aws/requests/storage/get_bucket_acl.rb', line 29

def get_bucket_acl(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::AWS::Storage::AccessControlList.new,
    :query      => {'acl' => nil}
  })
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



17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/fog/aws/requests/storage/get_bucket_location.rb', line 17

def get_bucket_location(bucket_name)
  request({
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::AWS::Storage::GetBucketLocation.new,
    :query    => {'location' => nil}
  })
end

#get_bucket_logging(bucket_name) ⇒ Object

Get logging status for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to get logging status for

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘BucketLoggingStatus’<~Hash>: (will be empty if logging is disabled)

        • ‘LoggingEnabled’<~Hash>:

          • ‘TargetBucket’<~String> - bucket where logs are stored

          • ‘TargetPrefix’<~String> - prefix logs are stored with

          • ‘TargetGrants’<~Array>:

            • ‘Grant’<~Hash>:

              • ‘Grantee’<~Hash>:

                * 'DisplayName'<~String> - Display name of grantee
* 'ID'<~String> - Id of grantee

                or

                * 'URI'<~String> - URI of group to grant access for

              • ‘Permission’<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]



29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/fog/aws/requests/storage/get_bucket_logging.rb', line 29

def get_bucket_logging(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::AWS::Storage::GetBucketLogging.new,
    :query      => {'logging' => nil}
  })
end

#get_bucket_object_versions(bucket_name, options = {}) ⇒ Object

List information about object versions in an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to list object keys from

  • options<~Hash> - config arguments for list. Defaults to {}.

    • ‘delimiter’<~String> - causes keys with the same string between the prefix value and the first occurence of delimiter to be rolled up

    • ‘key-marker’<~String> - limits object keys to only those that appear lexicographically after its value.

    • ‘max-keys’<~Integer> - limits number of object keys returned

    • ‘prefix’<~String> - limits object keys to those beginning with its value.

    • ‘version-id-marker’<~String> - limits object versions to only those that appear lexicographically after its value

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘Delimeter’<~String> - Delimiter specified for query

      • ‘KeyMarker’<~String> - Key marker specified for query

      • ‘MaxKeys’<~Integer> - Maximum number of keys specified for query

      • ‘Name’<~String> - Name of the bucket

      • ‘Prefix’<~String> - Prefix specified for query

      • ‘VersionIdMarker’<~String> - Version id marker specified for query

      • ‘IsTruncated’<~Boolean> - Whether or not this is the totality of the bucket

      • ‘Versions’<~Array>:

        * 'DeleteMarker'<~Hash>:
  * 'IsLatest'<~Boolean> - Whether or not this is the latest version
  * 'Key'<~String> - Name of object
  * 'LastModified'<~String>: Timestamp of last modification of object
  * 'Owner'<~Hash>:
    * 'DisplayName'<~String> - Display name of object owner
    * 'ID'<~String> - Id of object owner
  * 'VersionId'<~String> - The id of this version

        or

        * 'Version'<~Hash>:
  * 'ETag'<~String>: Etag of object
  * 'IsLatest'<~Boolean> - Whether or not this is the latest version
  * 'Key'<~String> - Name of object
  * 'LastModified'<~String>: Timestamp of last modification of object
  * 'Owner'<~Hash>:
    * 'DisplayName'<~String> - Display name of object owner
    * 'ID'<~String> - Id of object owner
  * 'Size'<~Integer> - Size of object
  * 'StorageClass'<~String> - Storage class of object
  * 'VersionId'<~String> - The id of this version



54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/fog/aws/requests/storage/get_bucket_object_versions.rb', line 54

def get_bucket_object_versions(bucket_name, options = {})
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::AWS::Storage::GetBucketObjectVersions.new,
    :query    => {'versions' => nil}.merge!(options)
  })
end

#get_bucket_versioning(bucket_name) ⇒ Object

Get versioning status for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to get versioning status for

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘VersioningConfiguration’<~Hash>

        * Status<~String>: Versioning status in ['Enabled', 'Suspended', nil]



19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/fog/aws/requests/storage/get_bucket_versioning.rb', line 19

def get_bucket_versioning(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::AWS::Storage::GetBucketVersioning.new,
    :query      => {'versioning' => nil}
  })
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

    • ‘versionId’<~String> - specify a particular version to retrieve

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



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/fog/aws/requests/storage/get_object.rb', line 28

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
  if version_id = options.delete('versionId')
    query = {'versionId' => version_id}
  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),
    :query    => query
  }, &block)
end

#get_object_acl(bucket_name, object_name, options = {}) ⇒ Object

Get access control list for an S3 object

Parameters

  • bucket_name<~String> - name of bucket containing object

  • object_name<~String> - name of object to get access control list for

  • options<~Hash>:

    • ‘versionId’<~String> - specify a particular version to retrieve

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘AccessControlPolicy’<~Hash>

        • ‘Owner’<~Hash>:

          • ‘DisplayName’<~String> - Display name of object owner

          • ‘ID’<~String> - Id of object owner

        • ‘AccessControlList’<~Array>:

          • ‘Grant’<~Hash>:

            • ‘Grantee’<~Hash>:

              * 'DisplayName'<~String> - Display name of grantee
* 'ID'<~String> - Id of grantee

              or

              * 'URI'<~String> - URI of group to grant access for

            • ‘Permission’<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/fog/aws/requests/storage/get_object_acl.rb', line 32

def get_object_acl(bucket_name, object_name, options = {})
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  unless object_name
    raise ArgumentError.new('object_name is required')
  end
  query = {'acl' => nil}
  if version_id = options.delete('versionId')
    query['versionId'] = version_id
  end
  request({
    :expects    => 200,
    :headers    => {},
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::AWS::Storage::AccessControlList.new,
    :path       => CGI.escape(object_name),
    :query      => query
  })
end

#get_object_torrent(bucket_name, object_name) ⇒ Object

Get torrent for an S3 object

Parameters

  • bucket_name<~String> - name of bucket containing object

  • object_name<~String> - name of object to get torrent for

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘AccessControlPolicy’<~Hash>

        • ‘Owner’<~Hash>:

          • ‘DisplayName’<~String> - Display name of object owner

          • ‘ID’<~String> - Id of object owner

        • ‘AccessControlList’<~Array>:

          • ‘Grant’<~Hash>:

            • ‘Grantee’<~Hash>:

              • ‘DisplayName’<~String> - Display name of grantee

              • ‘ID’<~String> - Id of grantee

            • ‘Permission’<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/fog/aws/requests/storage/get_object_torrent.rb', line 26

def get_object_torrent(bucket_name, object_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  unless object_name
    raise ArgumentError.new('object_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'GET',
    :path       => CGI.escape(object_name),
    :query      => {'torrent' => nil}
  })
end

#get_object_url(bucket_name, object_name, expires) ⇒ Object

Get an expiring object url from S3

Parameters

  • bucket_name<~String> - Name of bucket containing object

  • object_name<~String> - Name of object to get expiring url for

  • expires<~Time> - An expiry time for this url

Returns

  • response<~Excon::Response>:

    • body<~String> - url for object



17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/fog/aws/requests/storage/get_object_url.rb', line 17

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     => @host,
    :method   => 'GET',
    :path     => [bucket_name, CGI.escape(object_name)].join('/')
  }, 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



17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/fog/aws/requests/storage/get_request_payment.rb', line 17

def get_request_payment(bucket_name)
  request({
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::AWS::Storage::GetRequestPayment.new,
    :query    => {'requestPayment' => nil}
  })
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



19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/fog/aws/requests/storage/get_service.rb', line 19

def get_service
  request({
    :expects  => 200,
    :headers  => {},
    :host     => @host,
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::AWS::Storage::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

    • ‘versionId’<~String> - specify a particular version to retrieve

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
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/fog/aws/requests/storage/head_object.rb', line 27

def head_object(bucket_name, object_name, options={})
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  unless object_name
    raise ArgumentError.new('object_name is required')
  end
  if version_id = options.delete('versionId')
    query = {'versionId' => version_id}
  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}",
    :method   => 'HEAD',
    :path     => CGI.escape(object_name),
    :query    => query
  })
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



16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/fog/aws/requests/storage/put_bucket.rb', line 16

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_bucket_acl(bucket_name, acl) ⇒ Object

Change access control list for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to modify

  • acl<~Hash>:

    • Owner<~Hash>:

      • ID<~String>: id of owner

      • DisplayName<~String>: display name of owner

    • AccessControlList<~Array>:

      • Grantee<~Hash>:

        * 'DisplayName'<~String> - Display name of grantee
* 'ID'<~String> - Id of grantee

        or

        * 'EmailAddress'<~String> - Email address of grantee

        or

        * 'URI'<~String> - URI of group to grant access for

      • Permission<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/fog/aws/requests/storage/put_bucket_acl.rb', line 23

def put_bucket_acl(bucket_name, acl)
  data =
<<-DATA
<AccessControlPolicy>
  <Owner>
    <ID>#{acl['Owner']['ID']}</ID>
    <DisplayName>#{acl['Owner']['DisplayName']}</DisplayName>
  </Owner>
  <AccessControlList>
DATA

  acl['AccessControlList'].each do |grant|
    data << "    <Grant>"
    type = case grant['Grantee'].keys.sort
    when ['DisplayName', 'ID']
      'CanonicalUser'
    when ['EmailAddress']
      'AmazonCustomerByEmail'
    when ['URI']
      'Group'
    end
    data << "      <Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"#{type}\">"
    for key, value in grant['Grantee']
      data << "        <#{key}>#{value}</#{key}>"
    end
    data << "      </Grantee>"
    data << "      <Permission>#{grant['Permission']}</Permission>"
    data << "    </Grant>"
  end

  data <<
<<-DATA
  </AccessControlList>
</AccessControlPolicy>
DATA

  request({
    :body     => data,
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'PUT',
    :query    => {'acl' => nil}
  })
end

#put_bucket_logging(bucket_name, logging_status) ⇒ Object

Change logging status for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to modify

  • logging_status<~Hash>:

    • Owner<~Hash>:

      • ID<~String>: id of owner

      • DisplayName<~String>: display name of owner

    • AccessControlList<~Array>:

      • Grantee<~Hash>:

        * 'DisplayName'<~String> - Display name of grantee
* 'ID'<~String> - Id of grantee

        or

        * 'EmailAddress'<~String> - Email address of grantee

        or

        * 'URI'<~String> - URI of group to grant access for

      • Permission<~String> - Permission, in [FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP]



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/fog/aws/requests/storage/put_bucket_logging.rb', line 23

def put_bucket_logging(bucket_name, logging_status)
  if logging_status['LoggingEnabled'].empty?
    data =
<<-DATA
<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />
DATA
  else
    data =
<<-DATA
<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
  <LoggingEnabled>
    <TargetBucket>#{logging_status['LoggingEnabled']['TargetBucket']}</TargetBucket>
    <TargetPrefix>#{logging_status['LoggingEnabled']['TargetBucket']}</TargetPrefix>
    <TargetGrants>
DATA

    acl['AccessControlList'].each do |grant|
      data << "      <Grant>"
      type = case grant['Grantee'].keys.sort
      when ['DisplayName', 'ID']
        'CanonicalUser'
      when ['EmailAddress']
        'AmazonCustomerByEmail'
      when ['URI']
        'Group'
      end
      data << "        <Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"#{type}\">"
      for key, value in grant['Grantee']
        data << "          <#{key}>#{value}</#{key}>"
      end
      data << "        </Grantee>"
      data << "        <Permission>#{grant['Permission']}</Permission>"
      data << "      </Grant>"
    end

    data <<
<<-DATA
    </TargetGrants>
  </LoggingEnabled>
</BucketLoggingStatus>
DATA
  end

  request({
    :body     => data,
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'PUT',
    :query    => {'logging' => nil}
  })
end

#put_bucket_versioning(bucket_name, status) ⇒ Object

Change versioning status for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to modify

  • status<~String> - Status to change to in [‘Enabled’, ‘Suspended’]



11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/fog/aws/requests/storage/put_bucket_versioning.rb', line 11

def put_bucket_versioning(bucket_name, status)
  data =
<<-DATA
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Status>#{status}</Status>
</VersioningConfiguration>
DATA

  request({
    :body     => data,
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'PUT',
    :query    => {'versioning' => nil}
  })
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



26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/fog/aws/requests/storage/put_object.rb', line 26

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_object_url(bucket_name, object_name, expires) ⇒ Object

Get an expiring object url from S3 for putting an object

Parameters

  • bucket_name<~String> - Name of bucket containing object

  • object_name<~String> - Name of object to get expiring url for

  • expires<~Time> - An expiry time for this url

Returns

  • response<~Excon::Response>:

    • body<~String> - url for object



17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/fog/aws/requests/storage/put_object_url.rb', line 17

def put_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     => @host,
    :method   => 'PUT',
    :path     => [bucket_name, CGI.escape(object_name)].join('/')
  }, expires)
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



11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/fog/aws/requests/storage/put_request_payment.rb', line 11

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' => nil}
  })
end

#reload ⇒ Object 



168
169
170
 
# File 'lib/fog/aws/storage.rb', line 168

def reload
  @connection.reset
end