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

Inherits:
Object
  • Object
show all
Includes:
AWS::CredentialFetcher::ConnectionMethods, GetObjectHttpUrl, GetObjectHttpsUrl, GetObjectUrl, PutObjectUrl, 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/list_parts.rb,
lib/fog/aws/requests/storage/put_bucket.rb,
lib/fog/aws/requests/storage/put_object.rb,
lib/fog/aws/requests/storage/sync_clock.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/upload_part.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_acl.rb,
lib/fog/aws/requests/storage/put_object_url.rb,
lib/fog/aws/requests/storage/get_bucket_policy.rb,
lib/fog/aws/requests/storage/put_bucket_policy.rb,
lib/fog/aws/requests/storage/get_bucket_logging.rb,
lib/fog/aws/requests/storage/get_bucket_website.rb,
lib/fog/aws/requests/storage/get_object_torrent.rb,
lib/fog/aws/requests/storage/put_bucket_logging.rb,
lib/fog/aws/requests/storage/put_bucket_website.rb,
lib/fog/aws/requests/storage/get_bucket_location.rb,
lib/fog/aws/requests/storage/get_object_http_url.rb,
lib/fog/aws/requests/storage/get_request_payment.rb,
lib/fog/aws/requests/storage/put_request_payment.rb,
lib/fog/aws/requests/storage/delete_bucket_policy.rb,
lib/fog/aws/requests/storage/get_bucket_lifecycle.rb,
lib/fog/aws/requests/storage/get_object_https_url.rb,
lib/fog/aws/requests/storage/put_bucket_lifecycle.rb,
lib/fog/aws/requests/storage/delete_bucket_website.rb,
lib/fog/aws/requests/storage/get_bucket_versioning.rb,
lib/fog/aws/requests/storage/put_bucket_versioning.rb,
lib/fog/aws/requests/storage/abort_multipart_upload.rb,
lib/fog/aws/requests/storage/list_multipart_uploads.rb,
lib/fog/aws/requests/storage/delete_bucket_lifecycle.rb,
lib/fog/aws/requests/storage/delete_multiple_objects.rb,
lib/fog/aws/requests/storage/complete_multipart_upload.rb,
lib/fog/aws/requests/storage/initiate_multipart_upload.rb,
lib/fog/aws/requests/storage/post_object_hidden_fields.rb,
lib/fog/aws/requests/storage/get_bucket_object_versions.rb

Instance Attribute Summary

Attributes included from Utils

#region

Instance Method Summary collapse

Methods included from GetObjectHttpsUrl

#get_object_https_url

Methods included from GetObjectHttpUrl

#get_object_http_url

Methods included from PutObjectUrl

#put_object_url

Methods included from GetObjectUrl

#get_object_url

Methods included from AWS::CredentialFetcher::ConnectionMethods

#refresh_credentials_if_expired

Methods included from Utils

#cdn, #http_url, #https_url, #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 = Fog::Storage.new(
  :provider => "AWS",
  :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.



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/fog/aws/storage.rb', line 260

def initialize(options={})
  require 'fog/core/parser'
  require 'mime/types'

  @use_iam_profile = options[:use_iam_profile]
  setup_credentials(options)
  @connection_options     = options[:connection_options] || {}

  if @endpoint = options[:endpoint]
    endpoint = URI.parse(@endpoint)
    @host = endpoint.host
    @path = if endpoint.path.empty?
      '/'
    else
      endpoint.path
    end
    @port = endpoint.port
    @scheme = endpoint.scheme
  else
    options[:region] ||= 'us-east-1'
    @region = options[:region]
    @host = options[:host] || case options[:region]
    when 'us-east-1'
      's3.amazonaws.com'
    else
      "s3-#{options[:region]}.amazonaws.com"
    end
    @path       = options[:path]        || '/'
    @persistent = options.fetch(:persistent, false)
    @port       = options[:port]        || 443
    @scheme     = options[:scheme]      || 'https'
  end
  @connection = Fog::Connection.new("#{@scheme}://#{@host}:#{@port}#{@path}", @persistent, @connection_options)
end

Instance Method Details

#abort_multipart_upload(bucket_name, object_name, upload_id) ⇒ Object

Abort a multipart upload

Parameters

  • bucket_name<~String> - Name of bucket to abort multipart upload on

  • object_name<~String> - Name of object to abort multipart upload on

  • upload_id<~String> - Id of upload to add part to

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadAbort.html



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

def abort_multipart_upload(bucket_name, object_name, upload_id)
  request({
    :expects    => 204,
    :headers    => {},
    :host       => "#{bucket_name}.#{@host}",
    :method     => 'DELETE',
    :path       => CGI.escape(object_name),
    :query      => {'uploadId' => upload_id}
  })
end

#complete_multipart_upload(bucket_name, object_name, upload_id, parts) ⇒ Object

Complete a multipart upload

Parameters

  • bucket_name<~String> - Name of bucket to complete multipart upload for

  • object_name<~String> - Name of object to complete multipart upload for

  • upload_id<~String> - Id of upload to add part to

  • parts<~Array>: Array of etags for parts

    • :etag<~String> - Etag for this part

Returns

  • response<~Excon::Response>:

    • headers<~Hash>:

      • ‘Bucket’<~String> - bucket of new object

      • ‘ETag’<~String> - etag of new object (will be needed to complete upload)

      • ‘Key’<~String> - key of new object

      • ‘Location’<~String> - location of new object

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadComplete.html



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

def complete_multipart_upload(bucket_name, object_name, upload_id, parts)
  data = "<CompleteMultipartUpload>"
  parts.each_with_index do |part, index|
    data << "<Part>"
    data << "<PartNumber>#{index + 1}</PartNumber>"
    data << "<ETag>#{part}</ETag>"
    data << "</Part>"
  end
  data << "</CompleteMultipartUpload>"
  request({
    :body       => data,
    :expects    => 200,
    :headers    => { 'Content-Length' => data.length },
    :host       => "#{bucket_name}.#{@host}",
    :method     => 'POST',
    :parser     => Fog::Parsers::Storage::AWS::CompleteMultipartUpload.new,
    :path       => CGI.escape(object_name),
    :query      => {'uploadId' => upload_id}
  })
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

    • ‘x-amz-storage-class’<~String> - Default is ‘STANDARD’, set to ‘REDUCED_REDUNDANCY’ for non-critical, reproducable data

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘ETag’<~String> - etag of new object

      • ‘LastModified’<~Time> - date object was last modified

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectCOPY.html



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

def copy_object(source_bucket_name, source_object_name, target_bucket_name, target_object_name, options = {})
  headers = { 'x-amz-copy-source' => "/#{source_bucket_name}/#{CGI.escape(source_object_name)}" }.merge!(options)
  request({
    :expects  => 200,
    :headers  => headers,
    :host     => "#{target_bucket_name}.#{@host}",
    :method   => 'PUT',
    :parser   => Fog::Parsers::Storage::AWS::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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETE.html



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

def delete_bucket(bucket_name)
  request({
    :expects  => 204,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'DELETE'
  })
end

#delete_bucket_lifecycle(bucket_name) ⇒ Object

Delete lifecycle configuration for a bucket

Parameters

  • bucket_name<~String> - name of bucket to delete lifecycle configuration from

Returns

  • response<~Excon::Response>:

    • status<~Integer> - 204

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETElifecycle.html



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

def delete_bucket_lifecycle(bucket_name)
  request({
            :expects  => 204,
            :headers  => {},
            :host     => "#{bucket_name}.#{@host}",
            :method   => 'DELETE',
            :query    => {'lifecycle' => nil}
          })
end

#delete_bucket_policy(bucket_name) ⇒ Object

Delete policy for a bucket

Parameters

  • bucket_name<~String> - name of bucket to delete policy from

Returns

  • response<~Excon::Response>:

    • status<~Integer> - 204

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETEpolicy.html



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

def delete_bucket_policy(bucket_name)
  request({
    :expects  => 204,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'DELETE',
    :query    => {'policy' => nil}
  })
end

#delete_bucket_website(bucket_name) ⇒ Object

Delete website configuration for a bucket

Parameters

  • bucket_name<~String> - name of bucket to delete website configuration from

Returns

  • response<~Excon::Response>:

    • status<~Integer> - 204

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketDELETEwebsite.html



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

def delete_bucket_website(bucket_name)
  request({
    :expects  => 204,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'DELETE',
    :query    => {'website' => nil}
  })
end

#delete_multiple_objects(bucket_name, object_names, options = {}) ⇒ Object

bucket_name – name of the bucket to use object_names – filename For versioned deletes, options should include a version_ids hash, which maps from filename to an array of versions. The semantics are that for each (object_name, version) tuple, the caller must insert the object_name and an associated version (if desired), so for n versions, the object must be inserted n times.



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
 
# File 'lib/fog/aws/requests/storage/delete_multiple_objects.rb', line 39

def delete_multiple_objects(bucket_name, object_names, options = {})
  data = "<Delete>"
  data << "<Quiet>true</Quiet>" if options.delete(:quiet)
  version_ids = options.delete('versionId')
  object_names.each do |object_name|
    data << "<Object>"
    data << "<Key>#{CGI.escape(object_name)}</Key>"
    object_version = version_ids.nil? ? nil : version_ids[object_name]
    if object_version
      data << "<VersionId>#{CGI.escape(object_version)}</VersionId>"
    end
    data << "</Object>"
  end
  data << "</Delete>"

  headers = options
  headers['Content-Length'] = data.length
  headers['Content-MD5'] = Base64.encode64(Digest::MD5.digest(data)).
                           gsub("\n", '')

  request({
    :body       => data,
    :expects    => 200,
    :headers    => headers,
    :host       => "#{bucket_name}.#{@host}",
    :method     => 'POST',
    :parser     => Fog::Parsers::Storage::AWS::DeleteMultipleObjects.new,
    :query      => {'delete' => nil}
  })
end

#delete_object(bucket_name, object_name, options = {}) ⇒ 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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectDELETE.html



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

def delete_object(bucket_name, object_name, options = {})
  if version_id = options.delete('versionId')
    path = "#{CGI.escape(object_name)}?versionId=#{CGI.escape(version_id)}"
  else
    path = CGI.escape(object_name)
  end

  headers = options
  request({
    :expects    => 204,
    :headers    => headers,
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'DELETE',
    :path       => path
  })
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

      • ‘CommonPrefixes’<~Array> - Array of strings for common prefixes

      • ‘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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGET.html



43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/fog/aws/requests/storage/get_bucket.rb', line 43

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::Storage::AWS::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]

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETacl.html



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

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::Storage::AWS::AccessControlList.new,
    :query      => {'acl' => nil}
  })
end

#get_bucket_lifecycle(bucket_name) ⇒ Object

Get bucket lifecycle configuration

Parameters

  • bucket_name<~String> - name of bucket to get lifecycle configuration for

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘Rules’<~Array> - object expire rules

        * 'ID'<~String>      - Unique identifier for the rule
* 'Prefix'<~String>  - Prefix identifying one or more objects to which the rule applies
* 'Enabled'<~Boolean> - if rule is currently being applied
* 'Days'<~Integer>   - lifetime, in days, of the objects that are subject to the rule

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETlifecycle.html



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/fog/aws/requests/storage/get_bucket_lifecycle.rb', line 25

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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETlocation.html



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

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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETlogging.html



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

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::Storage::AWS::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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETVersion.html



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

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::Storage::AWS::GetBucketObjectVersions.new,
    :query    => {'versions' => nil}.merge!(options)          })
end

#get_bucket_policy(bucket_name) ⇒ Object

Get bucket policy for an S3 bucket

Parameters

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

Returns

  • response<~Excon::Response>:

    • body<~Hash> - policy document

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETpolicy.html



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

def get_bucket_policy(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  response = request({
    :expects    => 200,
    :headers    => {},
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'GET',
    :query      => {'policy' => nil}
  })
  response.body = Fog::JSON.decode(response.body) unless response.body.nil?
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]

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETversioningStatus.html



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

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::Storage::AWS::GetBucketVersioning.new,
    :query      => {'versioning' => nil}
  })
end

#get_bucket_website(bucket_name) ⇒ Object

Get website configuration for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to get website configuration for

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • IndexDocument<~Hash>

        • Suffix<~String> - Suffix appended when directory is requested

      • ErrorDocument<~Hash>

        • Key<~String> - Object key to return for 4XX class errors

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketGETwebsite.html



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

def get_bucket_website(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::Storage::AWS::GetBucketWebsite.new,
    :query      => {'website' => 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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectGET.html



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
 
# File 'lib/fog/aws/requests/storage/get_object.rb', line 31

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

  params = { :headers => {} }
  if version_id = options.delete('versionId')
    params[:query] = {'versionId' => version_id}
  end
  params[:headers].merge!(options)
  if options['If-Modified-Since']
    params[:headers]['If-Modified-Since'] = Fog::Time.at(options['If-Modified-Since'].to_i).to_date_header
  end
  if options['If-Unmodified-Since']
    params[:headers]['If-Unmodified-Since'] = Fog::Time.at(options['If-Unmodified-Since'].to_i).to_date_header
  end

  if block_given?
    params[:response_block] = Proc.new
  end

  request(params.merge!({
    :expects  => [ 200, 206 ],
    :host     => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method   => 'GET',
    :path     => CGI.escape(object_name),
  }))
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]

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectGETacl.html



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

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::Storage::AWS::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]

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectGETtorrent.html



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

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_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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTrequestPaymentGET.html



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

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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTServiceGET.html



23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/fog/aws/requests/storage/get_service.rb', line 23

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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectHEAD.html



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

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'] = Fog::Time.at(options['If-Modified-Since'].to_i).to_date_header if options['If-Modified-Since']
  headers['If-Unmodified-Since'] = Fog::Time.at(options['If-Unmodified-Since'].to_i).to_date_header if options['If-Modified-Since']
  headers.merge!(options)
  request({
    :expects    => 200,
    :headers    => headers,
    :host       => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method     => 'HEAD',
    :path       => CGI.escape(object_name),
    :query      => query
  })
end

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

Initiate a multipart upload to an S3 bucket

Parameters

  • bucket_name<~String> - Name of bucket to create object in

  • object_name<~String> - Name of object to create

  • options<~Hash>:

    • ‘Cache-Control’<~String> - Caching behaviour

    • ‘Content-Disposition’<~String> - Presentational information for the object

    • ‘Content-Encoding’<~String> - Encoding of object data

    • ‘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>:

    • body<~Hash>:

      • ‘Bucket’<~String> - Bucket where upload was initiated

      • ‘Key’<~String> - Object key where the upload was initiated

      • ‘UploadId’<~String> - Id for initiated multipart upload

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadInitiate.html



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

def initiate_multipart_upload(bucket_name, object_name, options = {})
  request({
    :expects    => 200,
    :headers    => options,
    :host       => "#{bucket_name}.#{@host}",
    :method     => 'POST',
    :parser     => Fog::Parsers::Storage::AWS::InitiateMultipartUpload.new,
    :path       => CGI.escape(object_name),
    :query      => {'uploads' => nil}
  })
end

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

List multipart uploads for a bucket

Parameters

  • bucket_name<~String> - Name of bucket to list multipart uploads for

  • upload_id<~String> - upload id to list objects for

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

    • ‘key-marker’<~String> - limits parts to only those that appear lexicographically after this key.

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

    • ‘upload-id-marker’<~String> - limits uploads to only those that appear lexicographically after this upload id.

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘Bucket’<~string> - Bucket where the multipart upload was initiated

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

      • ‘KeyMarker’<~String> - first key in list, only upload ids after this lexographically will appear

      • ‘MaxUploads’<~Integer> - Maximum results to return

      • ‘NextKeyMarker’<~String> - last key in list, for further pagination

      • ‘NextUploadIdMarker’<~String> - last key in list, for further pagination

      • ‘Upload’<~Hash>:

        • ‘Initiated’<~Time> - Time when upload was initiated

        • ‘Initiator’<~Hash>:

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

          • ‘ID’<~String> - Id of upload initiator

        • ‘Key’<~String> - Key where multipart upload was initiated

        • ‘Owner’<~Hash>:

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

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

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

        • ‘UploadId’<~String> - upload id of upload containing part

      • ‘UploadIdMarker’<String> - first key in list, only upload ids after this lexographically will appear

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadListMPUpload.html



45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/fog/aws/requests/storage/list_multipart_uploads.rb', line 45

def list_multipart_uploads(bucket_name, options = {})
  request({
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::Storage::AWS::ListMultipartUploads.new,
    :query    => options.merge!({'uploads' => nil})
  })
end

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

List parts for a multipart upload

Parameters

  • bucket_name<~String> - Name of bucket to list parts for

  • object_name<~String> - Name of object to list parts for

  • upload_id<~String> - upload id to list objects for

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

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

    • ‘part-number-marker’<~String> - limits parts to only those that appear lexicographically after this part number.

Returns

  • response<~Excon::Response>:

    • body<~Hash>:

      • ‘Bucket’<~string> - Bucket where the multipart upload was initiated

      • ‘Initiator’<~Hash>:

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

        • ‘ID’<~String> - Id of upload initiator

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

      • ‘Key’<~String> - Key where multipart upload was initiated

      • ‘MaxParts’<~String> - maximum number of replies alllowed in response

      • ‘NextPartNumberMarker’<~String> - last item in list, for further pagination

      • ‘Part’<~Array>:

        • ‘ETag’<~String> - ETag of part

        • ‘LastModified’<~Timestamp> - Last modified for part

        • ‘PartNumber’<~String> - Part number for part

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

      • ‘PartNumberMarker’<~String> - Part number after which listing begins

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

      • ‘UploadId’<~String> - upload id of upload containing part

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadListParts.html



42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/fog/aws/requests/storage/list_parts.rb', line 42

def list_parts(bucket_name, object_name, upload_id, options = {})
  options['uploadId'] = upload_id
  request({
    :expects  => 200,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::Storage::AWS::ListParts.new,
    :path     => CGI.escape(object_name),
    :query    => options.merge!({'uploadId' => upload_id})
  })
end

#post_object_hidden_fields(options = {}) ⇒ Object

Get a hash of hidden fields for form uploading to S3, in the form => :field_value Form should look like: <form action=“http://#bucket_name.s3.amazonaws.com/” method=“post” enctype=“multipart/form-data”> These hidden fields should then appear, followed by a field named ‘file’ which is either a textarea or file input.

Parameters

  • options<~Hash>:

    • acl<~String> - access control list, in [‘private’, ‘public-read’, ‘public-read-write’, ‘authenticated-read’, ‘bucket-owner-read’, ‘bucket-owner-full-control’]

    • Cache-Control - same as REST header

    • Content-Type - same as REST header

    • Content-Disposition - same as REST header

    • Content-Encoding - same as REST header

    • Expires - same as REST header

    • key - key for object, set to ‘$filename’ to use filename provided by user

    • policy - security policy for upload

    • success_action_redirect - url to redirct to upon success

    • success_action_status - status code to return on success, in [200, 201, 204]

    • x-amz-security-token - devpay security token

    • x-amz-meta-… - meta data tags

See Also

docs.amazonwebservices.com/AmazonS3/latest/dev/HTTPPOSTForms.html



28
29
30
31
32
33
34
35
 
# File 'lib/fog/aws/requests/storage/post_object_hidden_fields.rb', line 28

def post_object_hidden_fields(options = {})
  if options['policy']
    options['policy'] = Base64.encode64(Fog::JSON.encode(options['policy'])).gsub("\n", "")
    options['AWSAccessKeyId'] = @aws_access_key_id
    options['Signature'] = Base64.encode64(@hmac.sign(options['policy'])).gsub("\n", "")
  end
  options
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 {}.

    • ‘LocationConstraint’<~Symbol> - sets the location for the bucket

    • ‘x-amz-acl’<~String> - Permissions, must be in [‘private’, ‘public-read’, ‘public-read-write’, ‘authenticated-read’]

Returns

  • response<~Excon::Response>:

    • status<~Integer> - 200

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUT.html



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/fog/aws/requests/storage/put_bucket.rb', line 21

def put_bucket(bucket_name, options = {})
  if location_constraint = options.delete('LocationConstraint')
    data =
<<-DATA
  <CreateBucketConfiguration>
    <LocationConstraint>#{location_constraint}</LocationConstraint>
  </CreateBucketConfiguration>
DATA
  else
    data = nil
  end
  request({
    :expects    => 200,
    :body       => data,
    :headers    => options,
    :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]

  • acl<~String> - Permissions, must be in [‘private’, ‘public-read’, ‘public-read-write’, ‘authenticated-read’]

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTacl.html



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
 
# File 'lib/fog/aws/requests/storage/put_bucket_acl.rb', line 30

def put_bucket_acl(bucket_name, acl)
  data = ""
  headers = {}
  
  if acl.is_a?(Hash)
    data = Fog::Storage::AWS.hash_to_acl(acl)
  else
    if !['private', 'public-read', 'public-read-write', 'authenticated-read'].include?(acl)
      raise Excon::Errors::BadRequest.new('invalid x-amz-acl')
    end
    headers['x-amz-acl'] = acl
  end

  headers['Content-MD5'] = Base64.encode64(Digest::MD5.digest(data)).strip
  headers['Content-Type'] = 'application/json'
  headers['Date'] = Fog::Time.now.to_date_header

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

#put_bucket_lifecycle(bucket_name, lifecycle) ⇒ Object

Change lifecycle configuration for an S3 bucket

Parameters

  • bucket_name<~String> - name of bucket to set lifecycle configuration for

  • lifecycle<~Hash>:

    • ‘Rules’<~Array> - object expire rules

      * 'ID'<~String>       - Unique identifier for the rule
* 'Prefix'<~String>   - Prefix identifying one or more objects to which the rule applies
* 'Enabled'<~Boolean> - if rule is currently being applied
* 'Days'<~Integer>    - lifetime, in days, of the objects that are subject to the rule

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/fog/aws/requests/storage/put_bucket_lifecycle.rb', line 19

def put_bucket_lifecycle(bucket_name, lifecycle)
  builder = Nokogiri::XML::Builder.new do
    LifecycleConfiguration {
      lifecycle['Rules'].each do |rule|
        Rule {
          ID rule['ID']
          Prefix rule['Prefix']
          Status rule['Enabled'] ? 'Enabled' : 'Disabled'
          Expiration { Days rule['Days'] }
        }
      end
    }
  end

  body = builder.to_xml

  request({
            :body     => body,
            :expects  => 200,
            :headers  => {'Content-MD5' => Base64.encode64(Digest::MD5.digest(body)).chomp!,
              'Content-Type' => 'application/xml'},
            :host     => "#{bucket_name}.#{@host}",
            :method   => 'PUT',
            :query    => {'lifecycle' => 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]

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTlogging.html



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
75
76
77
78
 
# File 'lib/fog/aws/requests/storage/put_bucket_logging.rb', line 27

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_policy(bucket_name, policy) ⇒ Object

Change bucket policy for an S3 bucket

Parameters

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

  • policy<~Hash> - policy document

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTpolicy.html



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

def put_bucket_policy(bucket_name, policy)
  request({
    :body     => Fog::JSON.encode(policy),
    :expects  => 204,
    :headers  => {},
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'PUT',
    :query    => {'policy' => 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’]

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTVersioningStatus.html



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

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_bucket_website(bucket_name, suffix, options = {}) ⇒ Object

Change website configuration for an S3 bucket

Parameters

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

  • suffix<~String> - suffix to append to requests for the bucket

  • options<~Hash>

    • key<~String> - key to use for 4XX class errors

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTwebsite.html



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
43
44
 
# File 'lib/fog/aws/requests/storage/put_bucket_website.rb', line 17

def put_bucket_website(bucket_name, suffix, options = {})
  data =
<<-DATA
<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <IndexDocument>
<Suffix>#{suffix}</Suffix>
    </IndexDocument>
DATA

  if options[:key]
    data <<
<<-DATA
<ErrorDocument>
    <Key>#{options[:key]}</Key>
</ErrorDocument>
DATA
  end

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

    • ‘Content-Type’<~String> - Standard MIME type describing contents (defaults to MIME::Types.of.first)

    • ‘Expires’<~String> - Cache expiry

    • ‘x-amz-acl’<~String> - Permissions, must be in [‘private’, ‘public-read’, ‘public-read-write’, ‘authenticated-read’]

    • ‘x-amz-storage-class’<~String> - Default is ‘STANDARD’, set to ‘REDUCED_REDUNDANCY’ for non-critical, reproducable data

    • “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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectPUT.html



32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/fog/aws/requests/storage/put_object.rb', line 32

def put_object(bucket_name, object_name, data, options = {})
  data = Fog::Storage.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_acl(bucket_name, object_name, acl, options = {}) ⇒ Object

Change access control list for an S3 object

Parameters

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

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

  • 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]

  • acl<~String> - Permissions, must be in [‘private’, ‘public-read’, ‘public-read-write’, ‘authenticated-read’]

  • options<~Hash>:

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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectPUTacl.html



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
 
# File 'lib/fog/aws/requests/storage/put_object_acl.rb', line 33

def put_object_acl(bucket_name, object_name, acl, options = {})
  query = {'acl' => nil}
  if version_id = options.delete('versionId')
    query['versionId'] = version_id
  end
  
  data = ""
  headers = {}
  
  if acl.is_a?(Hash)
    data = Fog::Storage::AWS.hash_to_acl(acl)
  else
    if !['private', 'public-read', 'public-read-write', 'authenticated-read'].include?(acl)
      raise Excon::Errors::BadRequest.new('invalid x-amz-acl')
    end
    headers['x-amz-acl'] = acl
  end

  headers['Content-MD5'] = Base64.encode64(Digest::MD5.digest(data)).strip
  headers['Content-Type'] = 'application/json'
  headers['Date'] = Fog::Time.now.to_date_header
  
  request({
    :body     => data,
    :expects  => 200,
    :headers  => headers,
    :host     => "#{bucket_name}.#{@host}",
    :method   => 'PUT',
    :path       => CGI.escape(object_name),
    :query    => query
  })
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

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/RESTrequestPaymentPUT.html



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

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 



295
296
297
 
# File 'lib/fog/aws/storage.rb', line 295

def reload
  @connection.reset
end

#signature(params) ⇒ Object 



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/fog/aws/storage.rb', line 299

def signature(params)
  string_to_sign =
<<-DATA
#{params[:method].to_s.upcase}
#{params[:headers]['Content-MD5']}
#{params[:headers]['Content-Type']}
#{params[:headers]['Date']}
DATA

  amz_headers, canonical_amz_headers = {}, ''
  for key, value in params[:headers]
    if key[0..5] == 'x-amz-'
      amz_headers[key] = value
    end
  end
  amz_headers = amz_headers.sort {|x, y| x[0] <=> y[0]}
  for key, value in amz_headers
    canonical_amz_headers << "#{key}:#{value}\n"
  end
  string_to_sign << canonical_amz_headers

  subdomain = params[:host].split(".#{@host}").first
  unless subdomain =~ /^(?:[a-z]|\d(?!\d{0,2}(?:\.\d{1,3}){3}$))(?:[a-z0-9]|\.(?![\.\-])|\-(?![\.])){1,61}[a-z0-9]$/
    Fog::Logger.warning("fog: the specified s3 bucket name(#{subdomain}) is not a valid dns name, which will negatively impact performance.  For details see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/BucketRestrictions.html")
    params[:host] = params[:host].split("#{subdomain}.")[-1]
    if params[:path]
      params[:path] = "#{subdomain}/#{params[:path]}"
    else
      params[:path] = subdomain
    end
    subdomain = nil
  end

  canonical_resource  = @path.dup
  unless subdomain.nil? || subdomain == @host
    canonical_resource << "#{Fog::AWS.escape(subdomain).downcase}/"
  end
  canonical_resource << params[:path].to_s
  canonical_resource << '?'
  for key in (params[:query] || {}).keys.sort
    if %w{
      acl
      delete
      lifecycle
      location
      logging
      notification
      partNumber
      policy
      requestPayment
      response-cache-control
      response-content-disposition
      response-content-encoding
      response-content-language
      response-content-type
      response-expires
      torrent
      uploadId
      uploads
      versionId
      versioning
      versions
      website
    }.include?(key)
      canonical_resource << "#{key}#{"=#{params[:query][key]}" unless params[:query][key].nil?}&"
    end
  end
  canonical_resource.chop!
  string_to_sign << canonical_resource

  signed_string = @hmac.sign(string_to_sign)
  Base64.encode64(signed_string).chomp!
end

#sync_clock ⇒ Object

Sync clock against S3 to avoid skew errors



8
9
10
11
12
13
14
15
 
# File 'lib/fog/aws/requests/storage/sync_clock.rb', line 8

def sync_clock
  response = begin
    get_service
  rescue Excon::Errors::HTTPStatusError => error
    error.response
  end
  Fog::Time.now = Time.parse(response.headers['Date'])
end

#upload_part(bucket_name, object_name, upload_id, part_number, data, options = {}) ⇒ Object

Upload a part for a multipart upload

Parameters

  • bucket_name<~String> - Name of bucket to add part to

  • object_name<~String> - Name of object to add part to

  • upload_id<~String> - Id of upload to add part to

  • part_number<~String> - Index of part in upload

  • data<~File||String> - Content for part

  • options<~Hash>:

    • ‘Content-MD5’<~String> - Base64 encoded 128-bit MD5 digest of message

Returns

  • response<~Excon::Response>:

    • headers<~Hash>:

      • ‘ETag’<~String> - etag of new object (will be needed to complete upload)

See Also

docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadUploadPart.html



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

def upload_part(bucket_name, object_name, upload_id, part_number, data, options = {})
  data = Fog::Storage.parse_data(data)
  headers = options
  headers['Content-Length'] = data[:headers]['Content-Length']
  request({
    :body       => data[:body],
    :expects    => 200,
    :idempotent => true,
    :headers    => headers,
    :host       => "#{bucket_name}.#{@host}",
    :method     => 'PUT',
    :path       => CGI.escape(object_name),
    :query      => {'uploadId' => upload_id, 'partNumber' => part_number}
  })
end