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_bucket.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_cors.rb,
lib/fog/aws/requests/storage/put_bucket_cors.rb,
lib/fog/aws/requests/storage/get_bucket_policy.rb,
lib/fog/aws/requests/storage/put_bucket_policy.rb,
lib/fog/aws/requests/storage/delete_bucket_cors.rb,
lib/fog/aws/requests/storage/get_bucket_logging.rb,
lib/fog/aws/requests/storage/get_bucket_tagging.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_tagging.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/post_object_restore.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_tagging.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

Defined Under Namespace

Classes: S3Streamer

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, #request_url, #signed_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.



419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/fog/aws/storage.rb', line 419

def initialize(options={})

  @use_iam_profile = options[:use_iam_profile]
  @instrumentor       = options[:instrumentor]
  @instrumentor_name  = options[:instrumentor_name] || 'fog.aws.storage'
  @connection_options     = options[:connection_options] || {}
  @persistent = options.fetch(:persistent, false)
  @signature_version = options.fetch(:aws_signature_version, 4)
  validate_signature_version!
  @path_style = options[:path_style]  || false

  if @endpoint = options[:endpoint]
    endpoint = URI.parse(@endpoint)
    @host = endpoint.host
    @scheme = endpoint.scheme
    @port = endpoint.port
  else
    @region     = options[:region]      || DEFAULT_REGION
    @host       = options[:host]        || region_to_host(@region)
    @scheme     = options[:scheme]      || DEFAULT_SCHEME
    @port       = options[:port]        || DEFAULT_SCHEME_PORT[@scheme]
  end

  setup_credentials(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:



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

def abort_multipart_upload(bucket_name, object_name, upload_id)
  request({
    :expects    => 204,
    :headers    => {},
    :bucket_name => bucket_name,
    :object_name => object_name,
    :method     => 'DELETE',
    :query      => {'uploadId' => upload_id}
  })
end

#complete_multipart_upload(bucket_name, object_name, upload_id, parts) ⇒ Excon::Response

Note:

This request could fail and still return 200 OK, so it’s important that you check the response.

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<String>) —

    Array of etags as Strings for parts

Returns:

  • (Excon::Response) —

    • body [Hash]: (success)

      • Bucket [String] - bucket of new object

      • ETag [String] - etag of new object

      • Key [String] - key of new object

      • Location [String] - location of new object

    • body [Hash]: (failure)

      • Code [String] - Error status code

      • Message [String] - Error description

See Also:



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

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 },
    :bucket_name => bucket_name,
    :object_name => object_name,
    :method     => 'POST',
    :parser     => Fog::Parsers::Storage::AWS::CompleteMultipartUpload.new,
    :query      => {'uploadId' => upload_id}
  })
end

#copy_object(source_bucket_name, source_object_name, target_bucket_name, target_object_name, options = {}) ⇒ Excon::Response

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) (defaults to: {}) —

    :

Options Hash (options):

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

  • (Excon::Response) —

    • body [Hash]:

      • ETag [String] - etag of new object

      • LastModified [Time] - date object was last modified

See Also:



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

def copy_object(source_bucket_name, source_object_name, target_bucket_name, target_object_name, options = {})
  headers = { 'x-amz-copy-source' => "/#{source_bucket_name}#{object_to_path(source_object_name)}" }.merge!(options)
  request({
    :expects  => 200,
    :headers  => headers,
    :bucket_name => target_bucket_name,
    :object_name => target_object_name,
    :method   => 'PUT',
    :parser   => Fog::Parsers::Storage::AWS::CopyObject.new,
  })
end

#delete_bucket(bucket_name) ⇒ Excon::Response

Delete an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to delete

Returns:

  • (Excon::Response) —

    response:

    • status [Integer] - 204

See Also:



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

def delete_bucket(bucket_name)
  request({
    :expects  => 204,
    :headers  => {},
    :bucket_name => bucket_name,
    :method   => 'DELETE'
  })
end

#delete_bucket_cors(bucket_name) ⇒ Excon::Response

Deletes the cors configuration information set for the bucket.

Parameters:

  • bucket_name (String) —

    name of bucket to delete cors rules from

Returns:

  • (Excon::Response) —

    response:

    • status [Integer] - 204

See Also:



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

def delete_bucket_cors(bucket_name)
  request({
    :expects  => 204,
    :headers  => {},
    :bucket_name => bucket_name,
    :method   => 'DELETE',
    :query    => {'cors' => nil}
  })
end

#delete_bucket_lifecycle(bucket_name) ⇒ Excon::Response

Delete lifecycle configuration for a bucket

Parameters:

  • bucket_name (String) —

    name of bucket to delete lifecycle configuration from

Returns:

  • (Excon::Response) —

    response:

    • status [Integer] - 204

See Also:



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

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

#delete_bucket_policy(bucket_name) ⇒ Excon::Response

Delete policy for a bucket

Parameters:

  • bucket_name (String) —

    name of bucket to delete policy from

Returns:

  • (Excon::Response) —

    response:

    • status [Integer] - 204

See Also:



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

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

#delete_bucket_tagging(bucket_name) ⇒ Excon::Response

Delete tagging for a bucket

Parameters:

  • bucket_name (String) —

    name of bucket to delete tagging from

Returns:

  • (Excon::Response) —

    response:

    • status [Integer] - 204

See Also:



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

def delete_bucket_tagging(bucket_name)
  request({
    :expects  => 204,
    :headers  => {},
    :bucket_name => bucket_name,
    :method   => 'DELETE',
    :query    => {'tagging' => nil}
  })
end

#delete_bucket_website(bucket_name) ⇒ Excon::Response

Delete website configuration for a bucket

Parameters:

  • bucket_name (String) —

    name of bucket to delete website configuration from

Returns:

  • (Excon::Response) —

    response:

    • status [Integer] - 204

See Also:



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

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

#delete_multiple_objects(bucket_name, object_names, options = {}) ⇒ Excon::Response

Note:

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.

Delete multiple objects from S3

Parameters:

  • bucket_name (String) —

    Name of bucket containing object to delete

  • object_names (Array) —

    Array of object names to delete

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • DeleteResult [Array]:

        • Deleted [Hash]:

          • Key [String] - Name of the object that was deleted

          • VersionId [String] - ID for the versioned onject in case of a versioned delete

          • DeleteMarker [Boolean] - Indicates if the request accessed a delete marker

          • DeleteMarkerVersionId [String] - Version ID of the delete marker accessed

        • Error [Hash]:

          • Key [String] - Name of the object that failed to be deleted

          • VersionId [String] - ID of the versioned object that was attempted to be deleted

          • Code [String] - Status code for the result of the failed delete

          • Message [String] - Error description

See Also:



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/delete_multiple_objects.rb', line 33

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

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

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

#delete_object(bucket_name, object_name, options = {}) ⇒ Excon::Response

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:

  • (Excon::Response) —

    response:

    • status [Integer] - 204

See Also:



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

def delete_object(bucket_name, object_name, options = {})
  if version_id = options.delete('versionId')
    query = {'versionId' => version_id}
  else
    query = {}
  end

  headers = options
  request({
    :expects    => 204,
    :headers    => headers,
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => true,
    :method     => 'DELETE',
    :query      => query
  })
end

#get_bucket(bucket_name, options = {}) ⇒ Excon::Response

List information about objects in an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to list object keys from

  • options (Hash) (defaults to: {}) —

    config arguments for list. Defaults to {}.

Options Hash (options):

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

  • (Excon::Response) —

    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:



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

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

#get_bucket_acl(bucket_name) ⇒ Excon::Response

Get access control list for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get access control list for

Returns:

  • (Excon::Response) —

    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:



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

def get_bucket_acl(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :bucket_name => bucket_name,
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::Storage::AWS::AccessControlList.new,
    :query      => {'acl' => nil}
  })
end

#get_bucket_cors(bucket_name) ⇒ Excon::Response

Gets the CORS configuration for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get access control list for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • CORSConfiguration [Array]:

        • CORSRule [Hash]:

          • AllowedHeader [String] - Which headers are allowed in a pre-flight OPTIONS request through the Access-Control-Request-Headers header.

          • AllowedMethod [String] - Identifies an HTTP method that the domain/origin specified in the rule is allowed to execute.

          • AllowedOrigin [String] - One or more response headers that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).

          • ExposeHeader [String] - One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).

          • ID [String] - An optional unique identifier for the rule. The ID value can be up to 255 characters long. The IDs help you find a rule in the configuration.

          • MaxAgeSeconds [Integer] - The time in seconds that your browser is to cache the preflight response for the specified resource.

See Also:



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

def get_bucket_cors(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :bucket_name => bucket_name,
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::Storage::AWS::CorsConfiguration.new,
    :query      => {'cors' => nil}
  })
end

#get_bucket_lifecycle(bucket_name) ⇒ Excon::Response

Get bucket lifecycle configuration

Parameters:

  • bucket_name (String) —

    name of bucket to get lifecycle configuration for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • Rules - object expire rules [Array]:

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



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

def get_bucket_lifecycle(bucket_name)
  request({
            :expects  => 200,
            :headers  => {},
            :bucket_name => bucket_name,
            :idempotent => true,
            :method   => 'GET',
            :parser   => Fog::Parsers::Storage::AWS::GetBucketLifecycle.new,
            :query    => {'lifecycle' => nil}
          })
end

#get_bucket_location(bucket_name) ⇒ Excon::Response

Get location constraint for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get location constraint for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • LocationConstraint [String] - Location constraint of the bucket

See Also:



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

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

#get_bucket_logging(bucket_name) ⇒ Excon::Response

Get logging status for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get logging status for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • BucketLoggingStatus (will be empty if logging is disabled) [Hash]:

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



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

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

#get_bucket_object_versions(bucket_name, options = {}) ⇒ Excon::Response

List information about object versions in an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to list object keys from

  • options (Hash) (defaults to: {}) —

    config arguments for list

Options Hash (options):

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

  • (Excon::Response) —

    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:



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/fog/aws/requests/storage/get_bucket_object_versions.rb', line 50

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

#get_bucket_policy(bucket_name) ⇒ Excon::Response

Get bucket policy for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get policy for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash] - policy document

See Also:



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

def get_bucket_policy(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  response = request({
    :expects    => 200,
    :headers    => {},
    :bucket_name => bucket_name,
    :idempotent => true,
    :method     => 'GET',
    :query      => {'policy' => nil}
  })
  response.body = Fog::JSON.decode(response.body) unless response.body.nil?
end

#get_bucket_tagging(bucket_name) ⇒ Excon::Response

Get tags for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get tags for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • BucketTagging [Hash]:

        • Key [String] - tag key

        • Value [String] - tag value

See Also:



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

def get_bucket_tagging(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :bucket_name => bucket_name,
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::Storage::AWS::GetBucketTagging.new,
    :query      => {'tagging' => nil}
  })
end

#get_bucket_versioning(bucket_name) ⇒ Excon::Response

Get versioning status for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get versioning status for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • VersioningConfiguration [Hash]:

        • Status [String] - Versioning status in [‘Enabled’, ‘Suspended’, nil]

See Also:



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

def get_bucket_versioning(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :bucket_name => bucket_name,
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::Storage::AWS::GetBucketVersioning.new,
    :query      => {'versioning' => nil}
  })
end

#get_bucket_website(bucket_name) ⇒ Excon::Response

Get website configuration for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get website configuration for

Returns:

  • (Excon::Response) —

    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:



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

def get_bucket_website(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :headers    => {},
    :bucket_name => bucket_name,
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::Storage::AWS::GetBucketWebsite.new,
    :query      => {'website' => nil}
  })
end

#get_object(bucket_name, object_name, options = {}, &block) ⇒ Excon::Response

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) (defaults to: {})

Options Hash (options):

  • 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

  • query (Hash) —

    specify additional query string

Returns:

  • (Excon::Response) —

    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:



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

def get_object(bucket_name, object_name, options = {}, &block)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  unless object_name
    raise ArgumentError.new('object_name is required')
  end

  params = { :headers => {} }

  params[:query] = options.delete('query') || {}

  if version_id = options.delete('versionId')
    params[:query] = params[:query].merge({'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 ],
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => true,
    :method   => 'GET',
  }))
end

#get_object_acl(bucket_name, object_name, options = {}) ⇒ Excon::Response

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) (defaults to: {})

Options Hash (options):

  • versionId (String) —

    specify a particular version to retrieve

Returns:

  • (Excon::Response) —

    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:



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

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    => {},
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => true,
    :method     => 'GET',
    :parser     => Fog::Parsers::Storage::AWS::AccessControlList.new,
    :query      => query
  })
end

#get_object_torrent(bucket_name, object_name) ⇒ Excon::Response

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:

  • (Excon::Response) —

    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:



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

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    => {},
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => true,
    :method     => 'GET',
    :query      => {'torrent' => nil}
  })
end

#get_request_payment(bucket_name) ⇒ Excon::Response

Get configured payer for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to get payer for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • Payer [String] - Specifies who pays for download and requests

See Also:



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

def get_request_payment(bucket_name)
  request({
    :expects  => 200,
    :headers  => {},
    :bucket_name => bucket_name,
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::Storage::AWS::GetRequestPayment.new,
    :query    => {'requestPayment' => nil}
  })
end

#get_service ⇒ Excon::Response

List information about S3 buckets for authorized user

Returns:

  • (Excon::Response) —

    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:



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

def get_service
  request({
    :expects  => 200,
    :headers  => {},
    :host     => @host,
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::Storage::AWS::GetService.new
  })
end

#head_bucket(bucket_name) ⇒ Excon::Response

Get headers for an S3 bucket, used to verify if it exists and if you have permission to access it

Parameters:

  • bucket_name (String) —

    Name of bucket to read from

Returns:

  • (Excon::Response) —

    200 response implies it exists, 404 does not exist, 403 no permissions

    • body [String] Empty

    • headers [Hash]:

      • Content-Type [String] - MIME type of object

See Also:



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

def head_bucket(bucket_name)
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  request({
    :expects    => 200,
    :bucket_name => bucket_name,
    :idempotent => true,
    :method     => 'HEAD',
  })
end

#head_object(bucket_name, object_name, options = {}) ⇒ Excon::Response

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) (defaults to: {}) —

    :

Options Hash (options):

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

  • (Excon::Response) —

    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:



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

def head_object(bucket_name, object_name, options={})
  unless bucket_name
    raise ArgumentError.new('bucket_name is required')
  end
  unless object_name
    raise ArgumentError.new('object_name is required')
  end
  if version_id = options.delete('versionId')
    query = {'versionId' => version_id}
  end
  headers = {}
  headers['If-Modified-Since'] = 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,
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => true,
    :method     => 'HEAD',
    :query      => query
  })
end

#initiate_multipart_upload(bucket_name, object_name, options = {}) ⇒ Excon::Response

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) (defaults to: {}) —

    :

Options Hash (options):

  • 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} (String) —

    Headers to be returned with object, note total size of request without body must be less than 8 KB.

Returns:

  • (Excon::Response) —

    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:



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

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

#list_multipart_uploads(bucket_name, options = {}) ⇒ Excon::Response

List multipart uploads for a bucket

Parameters:

  • bucket_name (String) —

    Name of bucket to list multipart uploads for

  • options (Hash) (defaults to: {}) —

    config arguments for list. Defaults to {}.

Options Hash (options):

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

  • (Excon::Response) —

    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:



38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/fog/aws/requests/storage/list_multipart_uploads.rb', line 38

def list_multipart_uploads(bucket_name, options = {})
  request({
    :expects  => 200,
    :headers  => {},
    :bucket_name => bucket_name,
    :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 = {}) ⇒ Excon::Response

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) (defaults to: {}) —

    config arguments for list. Defaults to {}.

Options Hash (options):

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

  • (Excon::Response) —

    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:



37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/fog/aws/requests/storage/list_parts.rb', line 37

def list_parts(bucket_name, object_name, upload_id, options = {})
  options['uploadId'] = upload_id
  request({
    :expects  => 200,
    :headers  => {},
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::Storage::AWS::ListParts.new,
    :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 (defaults to: {}) —

    Hash:

Options Hash (options):

  • acl (String) —

    access control list, in [‘private’, ‘public-read’, ‘public-read-write’, ‘authenticated-read’, ‘bucket-owner-read’, ‘bucket-owner-full-control’]

  • Cache-Control (String) —

    same as REST header

  • Content-Type (String) —

    same as REST header

  • Content-Disposition (String) —

    same as REST header

  • Content-Encoding (String) —

    same as REST header

  • Expires (Object) —

    same as REST header

  • key (Object) —

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

  • policy (Object) —

    security policy for upload

  • success_action_redirect (Object) —

    url to redirct to upon success

  • success_action_status (Object) —

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

  • x-amz-security (Object) —

    token devpay security token

  • x-amz-meta... (Object) —

    meta data tags

See Also:



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

def post_object_hidden_fields(options = {})
  options = options.dup
  if policy = options['policy']
    date = Fog::Time.now
    credential = "#{@aws_access_key_id}/#{@signer.credential_scope(date)}"
    extra_conditions = [
      {'x-amz-date' => date.to_iso8601_basic},
      {'x-amz-credential' => credential},
      {'x-amz-algorithm' => Fog::AWS::SignatureV4::ALGORITHM}
    ]

    extra_conditions << {'x-amz-security-token' => @aws_session_token } if @aws_session_token

    policy_with_auth_fields = policy.merge('conditions' => policy['conditions'] + extra_conditions)

    options['policy'] = Base64.encode64(Fog::JSON.encode(policy_with_auth_fields)).gsub("\n", "")
    options['X-Amz-Credential'] = credential
    options['X-Amz-Date'] = date.to_iso8601_basic
    options['X-Amz-Algorithm'] = Fog::AWS::SignatureV4::ALGORITHM
    if @aws_session_token
      options['X-Amz-Security-Token'] = @aws_session_token         
    end
    options['X-Amz-Signature'] = @signer.derived_hmac(date).sign(options['policy']).unpack('H*').first
  end
  options          
end

#post_object_restore(bucket_name, object_name, days = 100000) ⇒ Excon::Response

Restore an object from Glacier to its original S3 path

Parameters:

  • bucket_name (String) —

    Name of bucket containing object

  • object_name (String) —

    Name of object to restore

  • days (Hash) (defaults to: 100000) —

    a customizable set of options

Options Hash (days):

  • Number (Integer) —

    of days to restore object for. Defaults to 100000 (a very long time)

Returns:

  • (Excon::Response) —

    response:

    • status [Integer] 200 (OK) Object is previously restored

    • status [Integer] 202 (Accepted) Object is not previously restored

    • status [Integer] 409 (Conflict) Restore is already in progress

Raises:

  • (ArgumentError)

See Also:



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

def post_object_restore(bucket_name, object_name, days = 100000)
  raise ArgumentError.new('bucket_name is required') unless bucket_name
  raise ArgumentError.new('object_name is required') unless object_name

  data = '<RestoreRequest xmlns="http://s3.amazonaws.com/doc/2006-3-01"><Days>' + days.to_s + '</Days></RestoreRequest>'

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

  request({
    :headers  => headers,
    :bucket_name => bucket_name,
    :expects  => [200, 202, 409],
    :body     => data,
    :method   => 'POST',
    :query    => {'restore' => nil},
    :object_name  => object_name
  })
end

#put_bucket(bucket_name, options = {}) ⇒ Excon::Response

Create an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to create

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • config (Hash) —

    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:

  • (Excon::Response) —

    response:

    • status [Integer] 200

See Also:



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

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,
    :bucket_name => bucket_name,
    :method     => 'PUT'
  })
end

#put_bucket_acl(bucket_name, acl) ⇒ Object

Change access control list for an S3 bucket

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

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]

See Also:



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

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,
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'acl' => nil}
  })
end

#put_bucket_cors(bucket_name, cors) ⇒ Object

Sets the cors configuration for your bucket. If the configuration exists, Amazon S3 replaces it.

Parameters:

  • bucket_name (String) —

    name of bucket to modify

  • cors (Hash) —

    • CORSConfiguration [Array]:

      • ID [String]: A unique identifier for the rule.

      • AllowedMethod [String]: An HTTP method that you want to allow the origin to execute.

      • AllowedOrigin [String]: An origin that you want to allow cross-domain requests from.

      • AllowedHeader [String]: Specifies which headers are allowed in a pre-flight OPTIONS request via the Access-Control-Request-Headers header.

      • MaxAgeSeconds [String]: The time in seconds that your browser is to cache the preflight response for the specified resource.

      • ExposeHeader [String]: One or more headers in the response that you want customers to be able to access from their applications.

See Also:



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

def put_bucket_cors(bucket_name, cors)
  data = Fog::Storage::AWS.hash_to_cors(cors)

  headers = {}
  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,
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'cors' => nil}
  })
end

#put_bucket_lifecycle(bucket_name, lifecycle) ⇒ Object

Change lifecycle configuration for an S3 bucket

  • 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

      • Expiration [Hash] Container for the object expiration rule.

        • Days [Integer] lifetime, in days, of the objects that are subject to the rule

        • Date [Date] Indicates when the specific rule take effect. The date value must conform to the ISO 8601 format. The time is always midnight UTC.

      • Transition [Hash] Container for the transition rule that describes when objects transition to the Glacier storage class

        • Days [Integer] lifetime, in days, of the objects that are subject to the rule

        • Date [Date] Indicates when the specific rule take effect. The date value must conform to the ISO 8601 format. The time is always midnight UTC.

        • StorageClass [String] Indicates the Amazon S3 storage class to which you want the object to transition to.

Parameters:

  • bucket_name (String) —

    name of bucket to set lifecycle configuration for

See Also:



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

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'
          unless (rule['Expiration'] or rule['Transition'])
            Expiration { Days rule['Days'] }
          else
            if rule['Expiration']
              if rule['Expiration']['Days']
                Expiration { Days rule['Expiration']['Days'] }
              elsif rule['Expiration']['Date']
                Expiration { Date rule['Expiration']['Date'].is_a?(Time) ? rule['Expiration']['Date'].utc.iso8601 : Time.parse(rule['Expiration']['Date']).utc.iso8601 }
              end
            end
            if rule['Transition']
              Transition {
                if rule['Transition']['Days']
                  Days rule['Transition']['Days']
                elsif rule['Transition']['Date']
                  Date rule['Transition']['Date'].is_a?(Time) ? time.utc.iso8601 : Time.parse(time).utc.iso8601
                end
                StorageClass rule['Transition']['StorageClass'].nil? ? 'GLACIER' : rule['Transition']['StorageClass']
              }
            end
          end
        }
      end
    }
  end
  body = builder.to_xml
  body.gsub! /<([^<>]+)\/>/, '<\1></\1>'
  request({
            :body     => body,
            :expects  => 200,
            :headers  => {'Content-MD5' => Base64.encode64(Digest::MD5.digest(body)).chomp!,
              'Content-Type' => 'application/xml'},
            :bucket_name => bucket_name,
            :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) —

    :

    • LoggingEnabled [Hash]: logging options or {} to disable

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



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

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

    logging_status['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  => {},
    :bucket_name => bucket_name,
    :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:



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

def put_bucket_policy(bucket_name, policy)
  request({
    :body     => Fog::JSON.encode(policy),
    :expects  => 204,
    :headers  => {},
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'policy' => nil}
  })
end

#put_bucket_tagging(bucket_name, tags) ⇒ Object

Change tag set for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to modify

  • tags (Hash) —

    :

    • Key [String]: tag key

    • Value [String]: tag value

See Also:



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

def put_bucket_tagging(bucket_name, tags)
  tagging = tags.map do |k,v|
    "<Tag><Key>#{k}</Key><Value>#{v}</Value></Tag>"
  end.join("\n")
  data =
<<-DATA
<Tagging xmlns="http://doc.s3.amazonaws.com/2006-03-01" >
  <TagSet>
    #{tagging}
  </TagSet>
</Tagging>
DATA

  request({
    :body     => data,
    :expects  => 204,
    :headers  => {'Content-MD5' => Base64.encode64(Digest::MD5.digest(data)).chomp!, 'Content-Type' => 'application/xml'},
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'tagging' => 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:



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

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  => {},
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'versioning' => nil}
  })
end

#put_bucket_website(bucket_name, options, options_to_be_deprecated = {}) ⇒ Object

Change website configuration for an S3 bucket

Parameters:

  • bucket_name (String) —

    name of bucket to modify

  • options (Hash)

Options Hash (options):

  • RedirectAllRequestsTo (String) —

    Host name to redirect all requests to - if this is set, other options are ignored

  • IndexDocument (String) —

    suffix to append to requests for the bucket

  • ErrorDocument (String) —

    key to use for 4XX class errors

See Also:



15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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
 
# File 'lib/fog/aws/requests/storage/put_bucket_website.rb', line 15

def put_bucket_website(bucket_name, options, options_to_be_deprecated = {})
  options ||= {}

  # Method used to be called with the suffix as the second parameter. Warn user that this is not the case any more and move on
  if options.is_a?(String)
    Fog::Logger.deprecation("put_bucket_website with #{options.class} param is deprecated, use put_bucket_website('#{bucket_name}', :IndexDocument => '#{options}') instead [light_black](#{caller.first})[/]")
    options = { :IndexDocument => options }
  end

  # Parameter renamed from "key" to "ErrorDocument"
  if options_to_be_deprecated[:key]
    Fog::Logger.deprecation("put_bucket_website with three parameters is deprecated, use put_bucket_website('#{bucket_name}', :ErrorDocument => '#{options_to_be_deprecated[:key]}') instead [light_black](#{caller.first})[/]")
    options[:ErrorDocument] = options_to_be_deprecated[:key]
  end

  options.merge!(options_to_be_deprecated) { |key, o1, o2| o1 }

  data = "<WebsiteConfiguration xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">"

  if options[:RedirectAllRequestsTo]
    # Redirect precludes all other options
    data << <<-DATA
              <RedirectAllRequestsTo>
                <HostName>#{options[:RedirectAllRequestsTo]}</HostName>
              </RedirectAllRequestsTo>
            DATA
  else

    if options[:IndexDocument]
    data << <<-DATA
              <IndexDocument>
                <Suffix>#{options[:IndexDocument]}</Suffix>
              </IndexDocument>
            DATA
    end

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

  data << '</WebsiteConfiguration>'
  request({
    :body     => data,
    :expects  => 200,
    :headers  => {},
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'website' => nil}
  })
end

#put_object(bucket_name, object_name, data, options = {}) ⇒ Excon::Response

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) (defaults to: {})

Options Hash (options):

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

  • (Excon::Response) —

    response:

    • headers [Hash]:

      • ETag [String] etag of new object

See Also:



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

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,
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => true,
    :method     => 'PUT',
  })
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) (defaults to: {})

Options Hash (options):

  • versionId (String) —

    specify a particular version to retrieve

See Also:



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

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,
    :bucket_name => bucket_name,
    :object_name => object_name,
    :method   => 'PUT',
    :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:



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

def put_request_payment(bucket_name, payer)
  data =
<<-DATA
<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Payer>#{payer}</Payer>
</RequestPaymentConfiguration>
DATA
  request({
    :body     => data,
    :expects  => 200,
    :headers  => {},
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'requestPayment' => nil}
  })
end

#reload ⇒ Object 



445
446
447
 
# File 'lib/fog/aws/storage.rb', line 445

def reload
  @connection.reset if @connection
end

#sync_clock ⇒ Object

Sync clock against S3 to avoid skew errors



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

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 = {}) ⇒ Excon::Response

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) (defaults to: {})

Options Hash (options):

  • Content-MD5 (String) —

    Base64 encoded 128-bit MD5 digest of message

Returns:

  • (Excon::Response) —

    response

    • headers [Hash]:

      • ETag [String] etag of new object (will be needed to complete upload)

See Also:



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

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,
    :bucket_name => bucket_name,
    :object_name => object_name,
    :method     => 'PUT',
    :query      => {'uploadId' => upload_id, 'partNumber' => part_number}
  })
end