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

Inherits:
Object
  • Object
show all
Includes:
CredentialFetcher::ConnectionMethods, DeleteObjectUrl, GetObjectHttpUrl, GetObjectHttpsUrl, GetObjectUrl, HeadObjectUrl, PostObjectHiddenFields, 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/head_object_url.rb,
lib/fog/aws/requests/storage/put_bucket_cors.rb,
lib/fog/aws/requests/storage/upload_part_copy.rb,
lib/fog/aws/requests/storage/delete_object_url.rb,
lib/fog/aws/requests/storage/get_bucket_policy.rb,
lib/fog/aws/requests/storage/put_bucket_policy.rb,
lib/fog/aws/requests/storage/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_tagging.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/put_object_tagging.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/get_bucket_notification.rb,
lib/fog/aws/requests/storage/put_bucket_notification.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

#disable_content_md5_validation, #max_copy_chunk_size, #max_put_chunk_size, #region

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PostObjectHiddenFields

#post_object_hidden_fields

Methods included from GetObjectHttpsUrl

#get_object_https_url

Methods included from GetObjectHttpUrl

#get_object_http_url

Methods included from DeleteObjectUrl

#delete_object_url

Methods included from HeadObjectUrl

#head_object_url

Methods included from PutObjectUrl

#put_object_url

Methods included from GetObjectUrl

#get_object_url

Methods included from CredentialFetcher::ConnectionMethods

#refresh_credentials_if_expired

Methods included from Utils

#cdn, #http_url, #https_url, #request_url, #require_mime_types, #signed_url, #url, #validate_chunk_size

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.



554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
 
# File 'lib/fog/aws/storage.rb', line 554

def initialize(options={})
  require_mime_types

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

  init_max_put_chunk_size!(options)
  init_max_copy_chunk_size!(options)

  @disable_content_md5_validation = options[:disable_content_md5_validation] || false

  @region = options[:region] || DEFAULT_REGION

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

  # GovCloud doesn't support S3 Transfer Acceleration https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-s3.html
  # S3 Transfer Acceleration doesn't support FIPS endpoints.  When both fog_aws_accelerate=true and AWS_USE_FIPS_ENDPOINT=true, don't use Accelerate.
  if @acceleration && (AWS_GOVCLOUD_REGIONS.include?(@region) || ENV['AWS_USE_FIPS_ENDPOINT'] == 'true')
    Fog::Logger.warning("fog: S3 Transfer Acceleration is not available in GovCloud regions or when AWS_USE_FIPS_ENDPOINT=true. Disabling acceleration.")
    @acceleration = false
  end

  @host = ACCELERATION_HOST if @acceleration
  setup_credentials(options)
end

Class Method Details

.conforming_to_us_ascii!(keys, hash) ⇒ 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)

Returns:

  • (Excon::Response) —

    response:

    • headers [Hash]:

      • ETag [String] etag of new object

See Also:



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

def self.conforming_to_us_ascii!(keys, hash)
  keys.each do |k|
    v = hash[k]
    if !v.encode(::Encoding::US_ASCII, :undef => :replace).eql?(v)
      raise Excon::Errors::BadRequest.new("invalid #{k} header: value must be us-ascii")
    end
  end
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::AWS::Storage::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, reproducible 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
41
 
# 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,
    :idempotent => true,
    :method   => 'PUT',
    :parser   => Fog::Parsers::AWS::Storage::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
63
64
65
66
67
68
69
 
# 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|
    object_version = version_ids.nil? ? nil : version_ids[object_name]
    if object_version
      object_version = object_version.is_a?(String) ? [object_version] : object_version
      object_version.each do |version_id|
        data << "<Object>"
        data << "<Key>#{CGI.escapeHTML(object_name)}</Key>"
        data << "<VersionId>#{CGI.escapeHTML(version_id)}</VersionId>"
        data << "</Object>"
      end
    else
      data << "<Object>"
      data << "<Key>#{CGI.escapeHTML(object_name)}</Key>"
      data << "</Object>"
    end
  end
  data << "</Delete>"

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

  request({
    :body       => data,
    :expects    => 200,
    :headers    => headers,
    :bucket_name => bucket_name,
    :method     => 'POST',
    :parser     => Fog::Parsers::AWS::Storage::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 occurrence 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]:

      • Delimiter [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::AWS::Storage::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::AWS::Storage::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::AWS::Storage::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::AWS::Storage::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::AWS::Storage::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::AWS::Storage::GetBucketLogging.new,
    :query      => {'logging' => nil}
  })
end

#get_bucket_notification(bucket_name) ⇒ Excon::Response

Get bucket notification configuration

Parameters:

  • bucket_name (String) —

    name of bucket to get notification configuration for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • Topics [Array] SNS topic configurations for the notification

        • ID [String] Unique identifier for the configuration

        • Topic [String] Amazon SNS topic ARN to which Amazon S3 will publish a message when it detects events of specified type

        • Event [String] Bucket event for which to send notifications

      • Queues [Array] SQS queue configurations for the notification

        • ID [String] Unique identifier for the configuration

        • Queue [String] Amazon SQS queue ARN to which Amazon S3 will publish a message when it detects events of specified type

        • Event [String] Bucket event for which to send notifications

      • CloudFunctions [Array] AWS Lambda notification configurations

        • ID [String] Unique identifier for the configuration

        • CloudFunction [String] Lambda cloud function ARN that Amazon S3 can invoke when it detects events of the specified type

        • InvocationRole [String] IAM role ARN that Amazon S3 can assume to invoke the specified cloud function on your behalf

        • Event [String] Bucket event for which to send notifications

See Also:



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

def get_bucket_notification(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::AWS::Storage::GetBucketNotification.new,
    :query      => {'notification' => 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 occurrence 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]:

      • Delimiter [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::AWS::Storage::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::AWS::Storage::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::AWS::Storage::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::AWS::Storage::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
63
64
 
# 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

  idempotent = true
  if block_given?
    params[:response_block] = Proc.new(&block)
    idempotent = false
  end

  request(params.merge!({
    :expects  => [ 200, 206 ],
    :bucket_name => bucket_name,
    :object_name => object_name,
    :idempotent => idempotent,
    :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::AWS::Storage::AccessControlList.new,
    :query      => query
  })
end

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

Get tags for an S3 object

Parameters:

  • bucket_name (String) —

    Name of bucket to read from

  • object_name (String) —

    Name of object to get tags for

Returns:

  • (Excon::Response) —

    response:

    • body [Hash]:

      • ObjectTagging [Hash]:

        • Key [String] - tag key

        • Value [String] - tag value

See Also:



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

def get_object_tagging(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',
    :parser => Fog::Parsers::AWS::Storage::GetObjectTagging.new,
    :query => {'tagging' => nil}
  })
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::AWS::Storage::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 || region_to_host(DEFAULT_REGION),
    :idempotent => true,
    :method   => 'GET',
    :parser   => Fog::Parsers::AWS::Storage::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::AWS::Storage::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::AWS::Storage::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 allowed 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::AWS::Storage::ListParts.new,
    :query    => options.merge!({'uploadId' => upload_id})
  })
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(OpenSSL::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::AWS::Storage.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(OpenSSL::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::AWS::Storage.hash_to_cors(cors)

  headers = {}
  headers['Content-MD5'] = Base64.encode64(OpenSSL::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

      • NoncurrentVersion]Expiration [Hash

        Container for the object expiration rule.

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

      • NoncurrentVersion]Transition [Hash

        Container for the transition rule that describes when objects transition

        to the Glacier storage class

        • Noncurrent]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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# 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'] or rule['NoncurrentVersionExpiration'] or rule['NoncurrentVersionTransition'])
            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['NoncurrentVersionExpiration']
              if rule['NoncurrentVersionExpiration']['NoncurrentDays']
                NoncurrentVersionExpiration { NoncurrentDays rule['NoncurrentVersionExpiration']['NoncurrentDays'] }
              elsif rule['NoncurrentVersionExpiration']['Date']
                NoncurrentVersionExpiration {
                  if Date rule['NoncurrentVersionExpiration']['Date'].is_a?(Time)
                    rule['NoncurrentVersionExpiration']['Date'].utc.iso8601
                  else
                    Time.parse(rule['NoncurrentVersionExpiration']['Date']).utc.iso8601
                  end
                }
              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
            if rule['NoncurrentVersionTransition']
              NoncurrentVersionTransition {
                if rule['NoncurrentVersionTransition']['NoncurrentDays']
                  NoncurrentDays rule['NoncurrentVersionTransition']['NoncurrentDays']
                elsif rule['NoncurrentVersionTransition']['Date']
                  Date rule['NoncurrentVersionTransition']['Date'].is_a?(Time) ? time.utc.iso8601 : Time.parse(time).utc.iso8601
                end
                StorageClass rule['NoncurrentVersionTransition']['StorageClass'].nil? ? 'GLACIER' : rule['NoncurrentVersionTransition']['StorageClass']
              }
            end
          end
        }
      end
    }
  end
  body = builder.to_xml
  body.gsub! /<([^<>]+)\/>/, '<\1></\1>'
  request({
            :body     => body,
            :expects  => 200,
            :headers  => {'Content-MD5' => Base64.encode64(OpenSSL::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_notification(bucket_name, notification) ⇒ Object

Change notification configuration for an S3 bucket

  • notifications [Hash]:

    • Topics [Array] SNS topic configurations for the notification

      • ID [String] Unique identifier for the configuration

      • Topic [String] Amazon SNS topic ARN to which Amazon S3 will publish a message when it detects events of specified type

      • Event [String] Bucket event for which to send notifications

    • Queues [Array] SQS queue configurations for the notification

      • ID [String] Unique identifier for the configuration

      • Queue [String] Amazon SQS queue ARN to which Amazon S3 will publish a message when it detects events of specified type

      • Event [String] Bucket event for which to send notifications

    • CloudFunctions [Array] AWS Lambda notification configurations

      • ID [String] Unique identifier for the configuration

      • CloudFunction [String] Lambda cloud function ARN that Amazon S3 can invoke when it detects events of the specified type

      • InvocationRole [String] IAM role ARN that Amazon S3 can assume to invoke the specified cloud function on your behalf

      • Event [String] Bucket event for which to send notifications

Parameters:

  • bucket_name (String) —

    name of bucket to set notification configuration for

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

def put_bucket_notification(bucket_name, notification)
  builder = Nokogiri::XML::Builder.new do
    NotificationConfiguration do
      notification.fetch('Topics', []).each do |topic|
        TopicConfiguration do
          Id    topic['Id']
          Topic topic['Topic']
          Event topic['Event']
        end
      end
      notification.fetch('Queues', []).each do |queue|
        QueueConfiguration do
          Id    queue['Id']
          Queue queue['Queue']
          Event queue['Event']
        end
      end
      notification.fetch('CloudFunctions', []).each do |func|
        CloudFunctionConfiguration do
          Id             func['Id']
          CloudFunction  func['CloudFunction']
          InvocationRole func['InvocationRole']
          Event          func['Event']
        end
      end
    end
  end
  body = builder.to_xml
  body.gsub!(/<([^<>]+)\/>/, '<\1></\1>')
  request({
    :body     => body,
    :expects  => 200,
    :headers  => {'Content-MD5' => Base64.encode64(OpenSSL::Digest::MD5.digest(body)).chomp!,
      'Content-Type' => 'application/xml'},
    :bucket_name => bucket_name,
    :method   => 'PUT',
    :query    => {'notification' => 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(OpenSSL::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 = {}) ⇒ Object 



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

def put_object(bucket_name, object_name, data, options = {})
  data = Fog::Storage.parse_data(data)
  headers = data[:headers].merge!(options)
  self.class.conforming_to_us_ascii! headers.keys.grep(/^x-amz-meta-/), headers

  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::AWS::Storage.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(OpenSSL::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_object_tagging(bucket_name, object_name, tags) ⇒ Object

Change tag set for an S3 object

Parameters:

  • bucket_name (String) —

    Name of bucket to modify object in

  • object_name (String) —

    Name of object to modify

  • tags (Hash) —

    :

    • Key [String]: tag key

    • Value [String]: tag value

See Also:



16
17
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/put_object_tagging.rb', line 16

def put_object_tagging(bucket_name, object_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  => 200,
    :headers  => {'Content-MD5' => Base64.encode64(OpenSSL::Digest::MD5.digest(data)).chomp!, 'Content-Type' => 'application/xml'},
    :bucket_name => bucket_name,
    :object_name => object_name,
    :method   => 'PUT',
    :query    => {'tagging' => nil}
  })
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 



598
599
600
 
# File 'lib/fog/aws/storage.rb', line 598

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
    Excon.get(sync_clock_url)
  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

#upload_part_copy(target_bucket_name, target_object_name, upload_id, part_number, options = {}) ⇒ Excon::Response

Upload a part for a multipart copy

Parameters:

  • target_bucket_name (String) —

    Name of bucket to create copy in

  • target_object_name (String) —

    Name for new copy of object

  • upload_id (String) —

    Id of upload to add part to

  • part_number (String) —

    Index of part in upload

  • 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-copy-source-range (Time) —

    Specifies the range of bytes to copy from the source object

Returns:

  • (Excon::Response) —

    • body [Hash]:

      • ETag [String] - etag of new object

      • LastModified [Time] - date object was last modified

See Also:



47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/fog/aws/requests/storage/upload_part_copy.rb', line 47

def upload_part_copy(target_bucket_name, target_object_name, upload_id, part_number, options = {})
  headers = options
  request({
    :expects    => 200,
    :idempotent => true,
    :headers    => headers,
    :bucket_name => target_bucket_name,
    :object_name => target_object_name,
    :method     => 'PUT',
    :query      => {'uploadId' => upload_id, 'partNumber' => part_number},
    :parser   => Fog::Parsers::AWS::Storage::UploadPartCopyObject.new,
  })
end