class Fog::Storage::AWS::Real

Public Class Methods

new(options={}) click to toggle source

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.

# File lib/fog/aws/storage.rb, line 259
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, true)
    @port       = options[:port]        || 443
    @scheme     = options[:scheme]      || 'https'
  end
  @connection = Fog::Connection.new("#{@scheme}://#{@host}:#{@port}#{@path}", @persistent, @connection_options)
end

Public Instance Methods

abort_multipart_upload(bucket_name, object_name, upload_id) click to toggle source

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

# 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) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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_object(bucket_name, object_name, options = {}) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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() click to toggle source

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

# 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={}) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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 = {}) click to toggle source

Get a hash of hidden fields for form uploading to S3, in the form {:field_name => :field_value} Form should look like: <form action="#{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

# 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 = {}) click to toggle source

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

# File lib/fog/aws/requests/storage/put_bucket.rb, line 21
        def put_bucket(bucket_name, options = {})
          if location_constraint = options.delete('LocationConstraint')
            data =
"  <CreateBucketConfiguration>
    <LocationConstraint>#{location_constraint}</LocationConstraint>
  </CreateBucketConfiguration>
"
          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) click to toggle source

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

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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 =
"<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />
"
          else
            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>
"

            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 <<
"    </TargetGrants>
  </LoggingEnabled>
</BucketLoggingStatus>
"
          end

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

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

# 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) click to toggle source

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

# File lib/fog/aws/requests/storage/put_bucket_versioning.rb, line 15
        def put_bucket_versioning(bucket_name, status)
          data =
"<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Status>#{status}</Status>
</VersioningConfiguration>
"

          request({
            :body     => data,
            :expects  => 200,
            :headers  => {},
            :host     => "#{bucket_name}.#{@host}",
            :method   => 'PUT',
            :query    => {'versioning' => nil}
          })
        end
put_bucket_website(bucket_name, suffix, options = {}) click to toggle source

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

# File lib/fog/aws/requests/storage/put_bucket_website.rb, line 17
        def put_bucket_website(bucket_name, suffix, options = {})
          data =
"<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <IndexDocument>
        <Suffix>#{suffix}</Suffix>
    </IndexDocument>
"

          if options[:key]
            data <<
"<ErrorDocument>
    <Key>#{options[:key]}</Key>
</ErrorDocument>
"
          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 = {}) click to toggle source

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

# 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 = {}) click to toggle source

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

# 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) click to toggle source

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

# File lib/fog/aws/requests/storage/put_request_payment.rb, line 15
        def put_request_payment(bucket_name, payer)
          data =
"<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Payer>#{payer}</Payer>
</RequestPaymentConfiguration>
"
          request({
            :body     => data,
            :expects  => 200,
            :headers  => {},
            :host     => "#{bucket_name}.#{@host}",
            :method   => 'PUT',
            :query    => {'requestPayment' => nil}
          })
        end
reload() click to toggle source
# File lib/fog/aws/storage.rb, line 294
def reload
  @connection.reset
end
signature(params) click to toggle source
# File lib/fog/aws/storage.rb, line 298
        def signature(params)
          string_to_sign =
"#{params[:method].to_s.upcase}
#{params[:headers]['Content-MD5']}
#{params[:headers]['Content-Type']}
#{params[:headers]['Date']}
"

          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 =~ %r^(?:[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
              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() click to toggle source

Sync clock against S3 to avoid skew errors

# 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 = {}) click to toggle source

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

# 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,
    :headers    => headers,
    :host       => "#{bucket_name}.#{@host}",
    :method     => 'PUT',
    :path       => CGI.escape(object_name),
    :query      => {'uploadId' => upload_id, 'partNumber' => part_number}
  })
end