Class: Aws::S3::Object

Inherits:
Object
  • Object
show all
Extended by:
Deprecations
Defined in:
lib/aws-sdk-s3/customizations/object.rb,
lib/aws-sdk-s3/object.rb

Defined Under Namespace

Classes: Collection

Read-Only Attributes collapse

Actions collapse

Associations collapse

Instance Method Summary collapse

Constructor Details

#initialize(bucket_name, key, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object

Returns a new instance of Object.

Overloads:

  • #initialize(bucket_name, key, options = {}) ⇒ Object

    Parameters:

    • bucket_name (String)
    • key (String)

    Options Hash (options):

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

    • :bucket_name (required, String)
    • :key (required, String)
    • :client (Client) 


21
22
23
24
25
26
27
 
# File 'lib/aws-sdk-s3/object.rb', line 21

def initialize(*args)
  options = Hash === args.last ? args.pop.dup : {}
  @bucket_name = extract_bucket_name(args, options)
  @key = extract_key(args, options)
  @data = options.delete(:data)
  @client = options.delete(:client) || Client.new(options)
end

Instance Method Details

#accept_ranges ⇒ String

Returns:

  • (String) 


50
51
52
 
# File 'lib/aws-sdk-s3/object.rb', line 50

def accept_ranges
  data[:accept_ranges]
end

#acl ⇒ ObjectAcl

Returns:



1042
1043
1044
1045
1046
1047
1048
 
# File 'lib/aws-sdk-s3/object.rb', line 1042

def acl
  ObjectAcl.new(
    bucket_name: @bucket_name,
    object_key: @key,
    client: @client
  )
end

#bucket ⇒ Bucket

Returns:



1051
1052
1053
1054
1055
1056
 
# File 'lib/aws-sdk-s3/object.rb', line 1051

def bucket
  Bucket.new(
    name: @bucket_name,
    client: @client
  )
end

#bucket_name ⇒ String

Returns:

  • (String) 


32
33
34
 
# File 'lib/aws-sdk-s3/object.rb', line 32

def bucket_name
  @bucket_name
end

#cache_control ⇒ String

Specifies caching behavior along the request/reply chain.

Returns:

  • (String) 


107
108
109
 
# File 'lib/aws-sdk-s3/object.rb', line 107

def cache_control
  data[:cache_control]
end

#client ⇒ Client

Returns:



237
238
239
 
# File 'lib/aws-sdk-s3/object.rb', line 237

def client
  @client
end

#content_disposition ⇒ String

Specifies presentational information for the object.

Returns:

  • (String) 


113
114
115
 
# File 'lib/aws-sdk-s3/object.rb', line 113

def content_disposition
  data[:content_disposition]
end

#content_encoding ⇒ String

Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

Returns:

  • (String) 


121
122
123
 
# File 'lib/aws-sdk-s3/object.rb', line 121

def content_encoding
  data[:content_encoding]
end

#content_language ⇒ String

The language the content is in.

Returns:

  • (String) 


127
128
129
 
# File 'lib/aws-sdk-s3/object.rb', line 127

def content_language
  data[:content_language]
end

#content_length ⇒ Integer

Size of the body in bytes.

Returns:

  • (Integer) 


78
79
80
 
# File 'lib/aws-sdk-s3/object.rb', line 78

def content_length
  data[:content_length]
end

#content_type ⇒ String

A standard MIME type describing the format of the object data.

Returns:

  • (String) 


133
134
135
 
# File 'lib/aws-sdk-s3/object.rb', line 133

def content_type
  data[:content_type]
end

#copy_from(options = {}) ⇒ Types::CopyObjectOutput

Examples:

Request syntax with placeholder values


object.copy_from({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
  cache_control: "CacheControl",
  content_disposition: "ContentDisposition",
  content_encoding: "ContentEncoding",
  content_language: "ContentLanguage",
  content_type: "ContentType",
  copy_source: "CopySource", # required
  copy_source_if_match: "CopySourceIfMatch",
  copy_source_if_modified_since: Time.now,
  copy_source_if_none_match: "CopySourceIfNoneMatch",
  copy_source_if_unmodified_since: Time.now,
  expires: Time.now,
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write_acp: "GrantWriteACP",
  metadata: {
    "MetadataKey" => "MetadataValue",
  },
  metadata_directive: "COPY", # accepts COPY, REPLACE
  tagging_directive: "COPY", # accepts COPY, REPLACE
  server_side_encryption: "AES256", # accepts AES256, aws:kms
  storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  copy_source_sse_customer_algorithm: "CopySourceSSECustomerAlgorithm",
  copy_source_sse_customer_key: "CopySourceSSECustomerKey",
  copy_source_sse_customer_key_md5: "CopySourceSSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
  object_lock_mode: "GOVERNANCE", # accepts GOVERNANCE, COMPLIANCE
  object_lock_retain_until_date: Time.now,
  object_lock_legal_hold_status: "ON", # accepts ON, OFF
})

Parameters:

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

    ({})

Options Hash (options):

  • :acl (String) —

    The canned ACL to apply to the object.

  • :cache_control (String) —

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String) —

    Specifies presentational information for the object.

  • :content_encoding (String) —

    Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

  • :content_language (String) —

    The language the content is in.

  • :content_type (String) —

    A standard MIME type describing the format of the object data.

  • :copy_source (required, String) —

    The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.

  • :copy_source_if_match (String) —

    Copies the object if its entity tag (ETag) matches the specified tag.

  • :copy_source_if_modified_since (Time, DateTime, Date, Integer, String) —

    Copies the object if it has been modified since the specified time.

  • :copy_source_if_none_match (String) —

    Copies the object if its entity tag (ETag) is different than the specified ETag.

  • :copy_source_if_unmodified_since (Time, DateTime, Date, Integer, String) —

    Copies the object if it hasn’t been modified since the specified time.

  • :expires (Time, DateTime, Date, Integer, String) —

    The date and time at which the object is no longer cacheable.

  • :grant_full_control (String) —

    Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>) —

    A map of metadata to store with the object in S3.

  • :metadata_directive (String) —

    Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.

  • :tagging_directive (String) —

    Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request.

  • :server_side_encryption (String) —

    The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

  • :storage_class (String) —

    The type of storage to use for the object. Defaults to ‘STANDARD’.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version

  • :copy_source_sse_customer_algorithm (String) —

    Specifies the algorithm to use when decrypting the source object (e.g., AES256).

  • :copy_source_sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.

  • :copy_source_sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :tagging (String) —

    The tag-set for the object destination object this value must be used in conjunction with the TaggingDirective. The tag-set must be encoded as URL Query parameters

  • :object_lock_mode (String) —

    The Object Lock mode that you want to apply to the copied object.

  • :object_lock_retain_until_date (Time, DateTime, Date, Integer, String) —

    The date and time when you want the copied object’s Object Lock to expire.

  • :object_lock_legal_hold_status (String) —

    Specifies whether you want to apply a Legal Hold to the copied object.

Returns:



61
62
63
64
65
66
67
68
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 61

def copy_from(source, options = {})
  if Hash === source && source[:copy_source]
    # for backwards compatibility
    @client.copy_object(source.merge(bucket: bucket_name, key: key))
  else
    ObjectCopier.new(self, options).copy_from(source, options)
  end
end

#copy_to(target, options = {}) ⇒ Object

Note:

If you need to copy to a bucket in a different region, use #copy_from.

Copies this object to another object. Use ‘multipart_copy: true` for large objects. This is required for objects that exceed 5GB.

Examples:

Basic object copy


bucket = Aws::S3::Bucket.new('source-bucket')
object = bucket.object('source-key')

# target as String
object.copy_to('target-bucket/target-key')

# target as Hash
object.copy_to(bucket: 'target-bucket', key: 'target-key')

# target as Aws::S3::Object
object.copy_to(bucket.object('target-key'))

Managed copy of large objects


# uses multipart upload APIs to copy object
object.copy_to('src-bucket/src-key', multipart_copy: true)

Parameters:

  • target (S3::Object, String, Hash) —

    Where to copy the object data to. ‘target` must be one of the following:

    • Aws::S3::Object

    • Hash - with ‘:bucket` and `:key`

    • String - formatted like ‘“target-bucket-name/target-key”`



102
103
104
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 102

def copy_to(target, options = {})
  ObjectCopier.new(self, options).copy_to(target, options)
end

#data ⇒ Types::HeadObjectOutput

Returns the data for this Aws::S3::Object. Calls Client#head_object if #data_loaded? is ‘false`.

Returns:



260
261
262
263
 
# File 'lib/aws-sdk-s3/object.rb', line 260

def data
  load unless @data
  @data
end

#data_loaded? ⇒ Boolean

Returns ‘true` if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.

Returns:

  • (Boolean) —

    Returns ‘true` if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.



268
269
270
 
# File 'lib/aws-sdk-s3/object.rb', line 268

def data_loaded?
  !!@data
end

#delete(options = {}) ⇒ Types::DeleteObjectOutput

Examples:

Request syntax with placeholder values


object.delete({
  mfa: "MFA",
  version_id: "ObjectVersionId",
  request_payer: "requester", # accepts requester
  bypass_governance_retention: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :mfa (String) —

    The concatenation of the authentication device’s serial number, a space, and the value that is displayed on your authentication device.

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :bypass_governance_retention (Boolean) —

    Indicates whether S3 Object Lock should bypass Governance-mode restrictions to process this operation.

Returns:



598
599
600
601
602
603
604
605
 
# File 'lib/aws-sdk-s3/object.rb', line 598

def delete(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.delete_object(options)
  resp.data
end

#delete_marker ⇒ Boolean

Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.

Returns:

  • (Boolean) 


45
46
47
 
# File 'lib/aws-sdk-s3/object.rb', line 45

def delete_marker
  data[:delete_marker]
end

#download_file(destination, options = {}) ⇒ Boolean

Downloads a file in S3 to a path on disk.

# small files (< 5MB) are downloaded in a single API call
obj.download_file('/path/to/file')

Files larger than 5MB are downloaded using multipart method

# large files are split into parts
# and the parts are downloaded in parallel
obj.download_file('/path/to/very_large_file')

Parameters:

  • destination (String) —

    Where to download the file to

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

    a customizable set of options

Options Hash (options):

  • mode (String) —

    ‘auto`, `single_request`, `get_range` `single_request` mode forces only 1 GET request is made in download, `get_range` mode allows `chunk_size` parameter to configured in customizing each range size in multipart_download, By default, `auto` mode is enabled, which performs multipart_download

  • chunk_size (String) —

    required in get_range mode

  • thread_count (String) —

    Customize threads used in multipart download, if not provided, 10 is default value

  • version_id (String) —

    The object version id used to retrieve the object, to know more about object versioning, see: docs.aws.amazon.com/AmazonS3/latest/dev/ObjectVersioning.html

Returns:

  • (Boolean) —

    Returns ‘true` when the file is downloaded without any errors.



342
343
344
345
346
347
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 342

def download_file(destination, options = {})
  downloader = FileDownloader.new(client: client)
  downloader.download(
    destination, options.merge(bucket: bucket_name, key: key))
  true
end

#etag ⇒ String

An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL

Returns:

  • (String) 


85
86
87
 
# File 'lib/aws-sdk-s3/object.rb', line 85

def etag
  data[:etag]
end

#exists?(options = {}) ⇒ Boolean

Returns ‘true` if the Object exists.

Parameters:

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

    ({})

Returns:

  • (Boolean) —

    Returns ‘true` if the Object exists.



275
276
277
278
279
280
281
282
283
284
 
# File 'lib/aws-sdk-s3/object.rb', line 275

def exists?(options = {})
  begin
    wait_until_exists(options.merge(max_attempts: 1))
    true
  rescue Aws::Waiters::Errors::UnexpectedError => e
    raise e.error
  rescue Aws::Waiters::Errors::WaiterFailed
    false
  end
end

#expiration ⇒ String

If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.

Returns:

  • (String) 


59
60
61
 
# File 'lib/aws-sdk-s3/object.rb', line 59

def expiration
  data[:expiration]
end

#expires ⇒ Time

The date and time at which the object is no longer cacheable.

Returns:

  • (Time) 


139
140
141
 
# File 'lib/aws-sdk-s3/object.rb', line 139

def expires
  data[:expires]
end

#expires_string ⇒ String

Returns:

  • (String) 


144
145
146
 
# File 'lib/aws-sdk-s3/object.rb', line 144

def expires_string
  data[:expires_string]
end

#get(options = {}, &block) ⇒ Types::GetObjectOutput

Examples:

Request syntax with placeholder values


object.get({
  if_match: "IfMatch",
  if_modified_since: Time.now,
  if_none_match: "IfNoneMatch",
  if_unmodified_since: Time.now,
  range: "Range",
  response_cache_control: "ResponseCacheControl",
  response_content_disposition: "ResponseContentDisposition",
  response_content_encoding: "ResponseContentEncoding",
  response_content_language: "ResponseContentLanguage",
  response_content_type: "ResponseContentType",
  response_expires: Time.now,
  version_id: "ObjectVersionId",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
  part_number: 1,
})

Parameters:

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

    ({})

Options Hash (options):

  • :if_match (String) —

    Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).

  • :if_modified_since (Time, DateTime, Date, Integer, String) —

    Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).

  • :if_none_match (String) —

    Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).

  • :if_unmodified_since (Time, DateTime, Date, Integer, String) —

    Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).

  • :range (String) —

    Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

  • :response_cache_control (String) —

    Sets the Cache-Control header of the response.

  • :response_content_disposition (String) —

    Sets the Content-Disposition header of the response

  • :response_content_encoding (String) —

    Sets the Content-Encoding header of the response.

  • :response_content_language (String) —

    Sets the Content-Language header of the response.

  • :response_content_type (String) —

    Sets the Content-Type header of the response.

  • :response_expires (Time, DateTime, Date, Integer, String) —

    Sets the Expires header of the response.

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :part_number (Integer) —

    Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a ‘ranged’ GET request for the part specified. Useful for downloading just a part of an object.

Returns:



684
685
686
687
688
689
690
691
 
# File 'lib/aws-sdk-s3/object.rb', line 684

def get(options = {}, &block)
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.get_object(options, &block)
  resp.data
end

#identifiers ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated. 


1082
1083
1084
1085
1086
1087
 
# File 'lib/aws-sdk-s3/object.rb', line 1082

def identifiers
  {
    bucket_name: @bucket_name,
    key: @key
  }
end

#initiate_multipart_upload(options = {}) ⇒ MultipartUpload

Examples:

Request syntax with placeholder values


multipartupload = object.initiate_multipart_upload({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
  cache_control: "CacheControl",
  content_disposition: "ContentDisposition",
  content_encoding: "ContentEncoding",
  content_language: "ContentLanguage",
  content_type: "ContentType",
  expires: Time.now,
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write_acp: "GrantWriteACP",
  metadata: {
    "MetadataKey" => "MetadataValue",
  },
  server_side_encryption: "AES256", # accepts AES256, aws:kms
  storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
  object_lock_mode: "GOVERNANCE", # accepts GOVERNANCE, COMPLIANCE
  object_lock_retain_until_date: Time.now,
  object_lock_legal_hold_status: "ON", # accepts ON, OFF
})

Parameters:

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

    ({})

Options Hash (options):

  • :acl (String) —

    The canned ACL to apply to the object.

  • :cache_control (String) —

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String) —

    Specifies presentational information for the object.

  • :content_encoding (String) —

    Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

  • :content_language (String) —

    The language the content is in.

  • :content_type (String) —

    A standard MIME type describing the format of the object data.

  • :expires (Time, DateTime, Date, Integer, String) —

    The date and time at which the object is no longer cacheable.

  • :grant_full_control (String) —

    Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>) —

    A map of metadata to store with the object in S3.

  • :server_side_encryption (String) —

    The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

  • :storage_class (String) —

    The type of storage to use for the object. Defaults to ‘STANDARD’.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :tagging (String) —

    The tag-set for the object. The tag-set must be encoded as URL Query parameters

  • :object_lock_mode (String) —

    Specifies the Object Lock mode that you want to apply to the uploaded object.

  • :object_lock_retain_until_date (Time, DateTime, Date, Integer, String) —

    Specifies the date and time when you want the Object Lock to expire.

  • :object_lock_legal_hold_status (String) —

    Specifies whether you want to apply a Legal Hold to the uploaded object.

Returns:



797
798
799
800
801
802
803
804
805
806
807
808
809
 
# File 'lib/aws-sdk-s3/object.rb', line 797

def initiate_multipart_upload(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.create_multipart_upload(options)
  MultipartUpload.new(
    bucket_name: @bucket_name,
    object_key: @key,
    id: resp.data.upload_id,
    client: @client
  )
end

#key ⇒ String

Returns:

  • (String) 


37
38
39
 
# File 'lib/aws-sdk-s3/object.rb', line 37

def key
  @key
end

#last_modified ⇒ Time

Last modified date of the object

Returns:

  • (Time) 


72
73
74
 
# File 'lib/aws-sdk-s3/object.rb', line 72

def last_modified
  data[:last_modified]
end

#load ⇒ self Also known as: reload

Loads, or reloads #data for the current Aws::S3::Object. Returns ‘self` making it possible to chain methods.

object.reload.data

Returns:

  • (self) 


247
248
249
250
251
252
253
254
 
# File 'lib/aws-sdk-s3/object.rb', line 247

def load
  resp = @client.head_object(
    bucket: @bucket_name,
    key: @key
  )
  @data = resp.data
  self
end

#metadata ⇒ Hash<String,String>

A map of metadata to store with the object in S3.

Returns:

  • (Hash<String,String>) 


165
166
167
 
# File 'lib/aws-sdk-s3/object.rb', line 165

def metadata
  data[:metadata]
end

#missing_meta ⇒ Integer

This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.

Returns:

  • (Integer) 


95
96
97
 
# File 'lib/aws-sdk-s3/object.rb', line 95

def missing_meta
  data[:missing_meta]
end

#move_to(target, options = {}) ⇒ void

This method returns an undefined value.

Copies and deletes the current object. The object will only be deleted if the copy operation succeeds.

Parameters:

  • target (S3::Object, String, Hash) —

    Where to copy the object data to. ‘target` must be one of the following:

    • Aws::S3::Object

    • Hash - with ‘:bucket` and `:key`

    • String - formatted like ‘“target-bucket-name/target-key”`

See Also:



113
114
115
116
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 113

def move_to(target, options = {})
  copy_to(target, options)
  delete
end

#multipart_upload(id) ⇒ MultipartUpload

Parameters:

  • id (String)

Returns:



1060
1061
1062
1063
1064
1065
1066
1067
 
# File 'lib/aws-sdk-s3/object.rb', line 1060

def multipart_upload(id)
  MultipartUpload.new(
    bucket_name: @bucket_name,
    object_key: @key,
    id: id,
    client: @client
  )
end

#object_lock_legal_hold_status ⇒ String

The Legal Hold status for the specified object.

Returns:

  • (String) 


230
231
232
 
# File 'lib/aws-sdk-s3/object.rb', line 230

def object_lock_legal_hold_status
  data[:object_lock_legal_hold_status]
end

#object_lock_mode ⇒ String

The Object Lock mode currently in place for this object.

Returns:

  • (String) 


218
219
220
 
# File 'lib/aws-sdk-s3/object.rb', line 218

def object_lock_mode
  data[:object_lock_mode]
end

#object_lock_retain_until_date ⇒ Time

The date and time when this object’s Object Lock will expire.

Returns:

  • (Time) 


224
225
226
 
# File 'lib/aws-sdk-s3/object.rb', line 224

def object_lock_retain_until_date
  data[:object_lock_retain_until_date]
end

#parts_count ⇒ Integer

The count of parts this object has.

Returns:

  • (Integer) 


212
213
214
 
# File 'lib/aws-sdk-s3/object.rb', line 212

def parts_count
  data[:parts_count]
end

#presigned_post(options = {}) ⇒ PresignedPost

Creates a PresignedPost that makes it easy to upload a file from a web browser direct to Amazon S3 using an HTML post form with a file field.

See the PresignedPost documentation for more information.

Parameters:

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

    a customizable set of options

Options Hash (options):

Returns:

See Also:



127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 127

def presigned_post(options = {})
  PresignedPost.new(
    client.config.credentials,
    client.config.region,
    bucket_name,
    {
      key: key,
      url: bucket.url,
    }.merge(options)
  )
end

#presigned_url(http_method, params = {}) ⇒ String

Generates a pre-signed URL for this object.

Examples:

Pre-signed GET URL, valid for one hour


obj.presigned_url(:get, expires_in: 3600)
#=> "https://bucket-name.s3.amazonaws.com/object-key?..."

Pre-signed PUT with a canned ACL


# the object uploaded using this URL will be publicly accessible
obj.presigned_url(:put, acl: 'public-read')
#=> "https://bucket-name.s3.amazonaws.com/object-key?..."

Parameters:

  • http_method (Symbol) —

    The HTTP method to generate a presigned URL for. Valid values are ‘:get`, `:put`, `:head`, and `:delete`.

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

    Additional request parameters to use when generating the pre-signed URL. See the related documentation in Client for accepted params.

    | HTTP Method | Client Method | |—————|————————| | ‘:get` | Client#get_object | | `:put` | Client#put_object | | `:head` | Client#head_object | | `:delete` | Client#delete_object |

Options Hash (params):

  • :virtual_host (Boolean) — default: false —

    When ‘true` the presigned URL will use the bucket name as a virtual host.

    bucket = Aws::S3::Bucket.new('my.bucket.com')
bucket.object('key').presigned_url(virtual_host: true)
#=> "http://my.bucket.com/key?..."
  • :expires_in (Integer) — default: 900 —

    Number of seconds before the pre-signed URL expires. This may not exceed one week (604800 seconds). Note that the pre-signed URL is also only valid as long as credentials used to sign it are. For example, when using IAM roles, temporary tokens generated for signing also have a default expiration which will affect the effective expiration of the pre-signed URL.

Returns:

  • (String)

Raises:

  • (ArgumentError) —

    Raised if ‘:expires_in` exceeds one week (604800 seconds).



187
188
189
190
191
192
193
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 187

def presigned_url(http_method, params = {})
  presigner = Presigner.new(client: client)
  presigner.presigned_url("#{http_method.downcase}_object", params.merge(
    bucket: bucket_name,
    key: key,
  ))
end

#public_url(options = {}) ⇒ String

Returns the public (un-signed) URL for this object.

s3.bucket('bucket-name').object('obj-key').public_url
#=> "https://bucket-name.s3.amazonaws.com/obj-key"

To use virtual hosted bucket url (disables https):

s3.bucket('my.bucket.com').object('key').public_url(virtual_host: true)
#=> "http://my.bucket.com/key"

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :virtual_host (Boolean) — default: false —

    When ‘true`, the bucket name will be used as the host name. This is useful when you have a CNAME configured for the bucket.

Returns:

  • (String) 


210
211
212
213
214
215
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 210

def public_url(options = {})
  url = URI.parse(bucket.url(options))
  url.path += '/' unless url.path[-1] == '/'
  url.path += key.gsub(/[^\/]+/) { |s| Seahorse::Util.uri_escape(s) }
  url.to_s
end

#put(options = {}) ⇒ Types::PutObjectOutput

Examples:

Request syntax with placeholder values


object.put({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
  body: source_file,
  cache_control: "CacheControl",
  content_disposition: "ContentDisposition",
  content_encoding: "ContentEncoding",
  content_language: "ContentLanguage",
  content_length: 1,
  content_md5: "ContentMD5",
  content_type: "ContentType",
  expires: Time.now,
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write_acp: "GrantWriteACP",
  metadata: {
    "MetadataKey" => "MetadataValue",
  },
  server_side_encryption: "AES256", # accepts AES256, aws:kms
  storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
  object_lock_mode: "GOVERNANCE", # accepts GOVERNANCE, COMPLIANCE
  object_lock_retain_until_date: Time.now,
  object_lock_legal_hold_status: "ON", # accepts ON, OFF
})

Parameters:

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

    ({})

Options Hash (options):

  • :acl (String) —

    The canned ACL to apply to the object.

  • :body (String, IO) —

    Object data.

  • :cache_control (String) —

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String) —

    Specifies presentational information for the object.

  • :content_encoding (String) —

    Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

  • :content_language (String) —

    The language the content is in.

  • :content_length (Integer) —

    Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.

  • :content_md5 (String) —

    The base64-encoded 128-bit MD5 digest of the part data.

  • :content_type (String) —

    A standard MIME type describing the format of the object data.

  • :expires (Time, DateTime, Date, Integer, String) —

    The date and time at which the object is no longer cacheable.

  • :grant_full_control (String) —

    Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>) —

    A map of metadata to store with the object in S3.

  • :server_side_encryption (String) —

    The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

  • :storage_class (String) —

    The type of storage to use for the object. Defaults to ‘STANDARD’.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :tagging (String) —

    The tag-set for the object. The tag-set must be encoded as URL Query parameters. (For example, “Key1=Value1”)

  • :object_lock_mode (String) —

    The Object Lock mode that you want to apply to this object.

  • :object_lock_retain_until_date (Time, DateTime, Date, Integer, String) —

    The date and time when you want this object’s Object Lock to expire.

  • :object_lock_legal_hold_status (String) —

    The Legal Hold status that you want to apply to the specified object.

Returns:



923
924
925
926
927
928
929
930
 
# File 'lib/aws-sdk-s3/object.rb', line 923

def put(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.put_object(options)
  resp.data
end

#replication_status ⇒ String

Returns:

  • (String) 


206
207
208
 
# File 'lib/aws-sdk-s3/object.rb', line 206

def replication_status
  data[:replication_status]
end

#request_charged ⇒ String

If present, indicates that the requester was successfully charged for the request.

Returns:

  • (String) 


201
202
203
 
# File 'lib/aws-sdk-s3/object.rb', line 201

def request_charged
  data[:request_charged]
end

#restore ⇒ String

Provides information about object restoration operation and expiration time of the restored object copy.

Returns:

  • (String) 


66
67
68
 
# File 'lib/aws-sdk-s3/object.rb', line 66

def restore
  data[:restore]
end

#restore_object(options = {}) ⇒ Types::RestoreObjectOutput

Examples:

Request syntax with placeholder values


object.restore_object({
  version_id: "ObjectVersionId",
  restore_request: {
    days: 1,
    glacier_job_parameters: {
      tier: "Standard", # required, accepts Standard, Bulk, Expedited
    },
    type: "SELECT", # accepts SELECT
    tier: "Standard", # accepts Standard, Bulk, Expedited
    description: "Description",
    select_parameters: {
      input_serialization: { # required
        csv: {
          file_header_info: "USE", # accepts USE, IGNORE, NONE
          comments: "Comments",
          quote_escape_character: "QuoteEscapeCharacter",
          record_delimiter: "RecordDelimiter",
          field_delimiter: "FieldDelimiter",
          quote_character: "QuoteCharacter",
          allow_quoted_record_delimiter: false,
        },
        compression_type: "NONE", # accepts NONE, GZIP, BZIP2
        json: {
          type: "DOCUMENT", # accepts DOCUMENT, LINES
        },
        parquet: {
        },
      },
      expression_type: "SQL", # required, accepts SQL
      expression: "Expression", # required
      output_serialization: { # required
        csv: {
          quote_fields: "ALWAYS", # accepts ALWAYS, ASNEEDED
          quote_escape_character: "QuoteEscapeCharacter",
          record_delimiter: "RecordDelimiter",
          field_delimiter: "FieldDelimiter",
          quote_character: "QuoteCharacter",
        },
        json: {
          record_delimiter: "RecordDelimiter",
        },
      },
    },
    output_location: {
      s3: {
        bucket_name: "BucketName", # required
        prefix: "LocationPrefix", # required
        encryption: {
          encryption_type: "AES256", # required, accepts AES256, aws:kms
          kms_key_id: "SSEKMSKeyId",
          kms_context: "KMSContext",
        },
        canned_acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
        access_control_list: [
          {
            grantee: {
              display_name: "DisplayName",
              email_address: "EmailAddress",
              id: "ID",
              type: "CanonicalUser", # required, accepts CanonicalUser, AmazonCustomerByEmail, Group
              uri: "URI",
            },
            permission: "FULL_CONTROL", # accepts FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP
          },
        ],
        tagging: {
          tag_set: [ # required
            {
              key: "ObjectKey", # required
              value: "Value", # required
            },
          ],
        },
        user_metadata: [
          {
            name: "MetadataKey",
            value: "MetadataValue",
          },
        ],
        storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER
      },
    },
  },
  request_payer: "requester", # accepts requester
})

Parameters:

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

    ({})

Options Hash (options):

Returns:



1030
1031
1032
1033
1034
1035
1036
1037
 
# File 'lib/aws-sdk-s3/object.rb', line 1030

def restore_object(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.restore_object(options)
  resp.data
end

#server_side_encryption ⇒ String

The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

Returns:

  • (String) 


159
160
161
 
# File 'lib/aws-sdk-s3/object.rb', line 159

def server_side_encryption
  data[:server_side_encryption]
end

#size ⇒ Object 



5
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 5

alias size content_length

#sse_customer_algorithm ⇒ String

If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.

Returns:

  • (String) 


173
174
175
 
# File 'lib/aws-sdk-s3/object.rb', line 173

def sse_customer_algorithm
  data[:sse_customer_algorithm]
end

#sse_customer_key_md5 ⇒ String

If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.

Returns:

  • (String) 


182
183
184
 
# File 'lib/aws-sdk-s3/object.rb', line 182

def sse_customer_key_md5
  data[:sse_customer_key_md5]
end

#ssekms_key_id ⇒ String

If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.

Returns:

  • (String) 


189
190
191
 
# File 'lib/aws-sdk-s3/object.rb', line 189

def ssekms_key_id
  data[:ssekms_key_id]
end

#storage_class ⇒ String

Returns:

  • (String) 


194
195
196
 
# File 'lib/aws-sdk-s3/object.rb', line 194

def storage_class
  data[:storage_class]
end

#upload_file(source, options = {}) ⇒ Boolean

Uploads a file from disk to the current object in S3.

# small files are uploaded in a single API call
obj.upload_file('/path/to/file')

Files larger than ‘:multipart_threshold` are uploaded using the Amazon S3 multipart upload APIs.

# large files are automatically split into parts
# and the parts are uploaded in parallel
obj.upload_file('/path/to/very_large_file')

Parameters:

  • source (String, Pathname, File, Tempfile) —

    A file or path to a file on the local file system that should be uploaded to this object. If you pass an open file object, then it is your responsibility to close the file object once the upload completes.

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

    a customizable set of options

Options Hash (options):

  • :multipart_threshold (Integer) — default: 15728640 —

    Files larger than ‘:multipart_threshold` are uploaded using the S3 multipart APIs. Default threshold is 15MB.

Returns:

  • (Boolean) —

    Returns ‘true` when the object is uploaded without any errors.

Raises:

  • (MultipartUploadError) —

    If an object is being uploaded in parts, and the upload can not be completed, then the upload is aborted and this error is raised. The raised error has a ‘#errors` method that returns the failures that caused the upload to be aborted.



303
304
305
306
307
308
309
310
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 303

def upload_file(source, options = {})
  uploading_options = options.dup
  uploader = FileUploader.new(
    multipart_threshold: uploading_options.delete(:multipart_threshold),
    client: client)
  uploader.upload(source, uploading_options.merge(bucket: bucket_name, key: key))
  true
end

#upload_stream(options = {}, &block) ⇒ Boolean

Uploads a stream in a streaming fashion to the current object in S3.

   # Passed chunks automatically split into multipart upload parts
   # and the parts are uploaded in parallel. This allows for streaming uploads
   # that never touch the disk.

Note that this is known to have issues in JRuby until jruby-9.1.15.0, so avoid using this with older versions of JRuby.

Examples:

Streaming chunks of data

obj.upload_stream do |write_stream|
  10.times { write_stream << 'foo' }
end

Streaming chunks of data

obj.upload_stream do |write_stream|
  IO.copy_stream(IO.popen('ls'), write_stream)
end

Streaming chunks of data

obj.upload_stream do |write_stream|
  IO.copy_stream(STDIN, write_stream)
end

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :thread_count (Integer) —

    The number of parallel multipart uploads Default ‘:thread_count` is `10`.

  • :tempfile (Boolean) —

    Normally read data is stored in memory when building the parts in order to complete the underlying multipart upload. By passing ‘:tempfile => true` data read will be temporarily stored on disk reducing the memory footprint vastly. Default `:tempfile` is `false`.

  • :part_size (Integer) —

    Define how big each part size but the last should be. Default ‘:part_size` is `5 * 1024 * 1024`.

Returns:

  • (Boolean) —

    Returns ‘true` when the object is uploaded without any errors.

Raises:

  • (MultipartUploadError) —

    If an object is being uploaded in parts, and the upload can not be completed, then the upload is aborted and this error is raised. The raised error has a ‘#errors` method that returns the failures that caused the upload to be aborted.



261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/aws-sdk-s3/customizations/object.rb', line 261

def upload_stream(options = {}, &block)
  uploading_options = options.dup
  uploader = MultipartStreamUploader.new(
    client: client,
    thread_count: uploading_options.delete(:thread_count),
    tempfile: uploading_options.delete(:tempfile),
    part_size: uploading_options.delete(:part_size),
  )
  uploader.upload(uploading_options.merge(bucket: bucket_name, key: key), &block)
  true
end

#version(id) ⇒ ObjectVersion

Parameters:

  • id (String)

Returns:



1071
1072
1073
1074
1075
1076
1077
1078
 
# File 'lib/aws-sdk-s3/object.rb', line 1071

def version(id)
  ObjectVersion.new(
    bucket_name: @bucket_name,
    object_key: @key,
    id: id,
    client: @client
  )
end

#version_id ⇒ String

Version of the object.

Returns:

  • (String) 


101
102
103
 
# File 'lib/aws-sdk-s3/object.rb', line 101

def version_id
  data[:version_id]
end

#wait_until(options = {}, &block) ⇒ Resource

Deprecated.

Use [Aws::S3::Client] #wait_until instead

Note:

The waiting operation is performed on a copy. The original resource remains unchanged

Waiter polls an API operation until a resource enters a desired state.

## Basic Usage

Waiter will polls until it is successful, it fails by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop until condition is true
resource.wait_until(options) {|resource| condition}

## Example

instance.wait_until(max_attempts:10, delay:5) {|instance| instance.state.name == 'running' }

## Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. The waiting condition is set by passing a block to #wait_until:

# poll for ~25 seconds
resource.wait_until(max_attempts:5,delay:5) {|resource|...}

## Callbacks

You can be notified before each polling attempt and before each delay. If you throw ‘:success` or `:failure` from these callbacks, it will terminate the waiter.

started_at = Time.now
# poll for 1 hour, instead of a number of attempts
proc = Proc.new do |attempts, response|
  throw :failure if Time.now - started_at > 3600
end

  # disable max attempts
instance.wait_until(before_wait:proc, max_attempts:nil) {...}

## Handling Errors

When a waiter is successful, it returns the Resource. When a waiter fails, it raises an error.

begin
  resource.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

attempts attempt in seconds invoked before each attempt invoked before each wait

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :max_attempts (Integer) — default: 10 —

    Maximum number of

  • :delay (Integer) — default: 10 —

    Delay between each

  • :before_attempt (Proc) — default: nil —

    Callback

  • :before_wait (Proc) — default: nil —

    Callback

Returns:

  • (Resource) —

    if the waiter was successful

Raises:

  • (Aws::Waiters::Errors::FailureStateError) —

    Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

    yet successful.

  • (Aws::Waiters::Errors::UnexpectedError) —

    Raised when an error is encountered while polling for a resource that is not expected.

  • (NotImplementedError) —

    Raised when the resource does not



402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/aws-sdk-s3/object.rb', line 402

def wait_until(options = {}, &block)
  self_copy = self.dup
  attempts = 0
  options[:max_attempts] = 10 unless options.key?(:max_attempts)
  options[:delay] ||= 10
  options[:poller] = Proc.new do
    attempts += 1
    if block.call(self_copy)
      [:success, self_copy]
    else
      self_copy.reload unless attempts == options[:max_attempts]
      :retry
    end
  end
  Aws::Waiters::Waiter.new(options).wait({})
end

#wait_until_exists(options = {}) ⇒ Object

Parameters:

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

    ({})

Options Hash (options):

  • :max_attempts (Integer) — default: 20
  • :delay (Float) — default: 5
  • :before_attempt (Proc)
  • :before_wait (Proc)

Returns:



292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/aws-sdk-s3/object.rb', line 292

def wait_until_exists(options = {})
  options, params = separate_params_and_options(options)
  waiter = Waiters::ObjectExists.new(options)
  yield_waiter_and_warn(waiter, &Proc.new) if block_given?
  waiter.wait(params.merge(bucket: @bucket_name,
    key: @key))
  Object.new({
    bucket_name: @bucket_name,
    key: @key,
    client: @client
  })
end

#wait_until_not_exists(options = {}) ⇒ Object

Parameters:

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

    ({})

Options Hash (options):

  • :max_attempts (Integer) — default: 20
  • :delay (Float) — default: 5
  • :before_attempt (Proc)
  • :before_wait (Proc)

Returns:



311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/aws-sdk-s3/object.rb', line 311

def wait_until_not_exists(options = {})
  options, params = separate_params_and_options(options)
  waiter = Waiters::ObjectNotExists.new(options)
  yield_waiter_and_warn(waiter, &Proc.new) if block_given?
  waiter.wait(params.merge(bucket: @bucket_name,
    key: @key))
  Object.new({
    bucket_name: @bucket_name,
    key: @key,
    client: @client
  })
end

#website_redirect_location ⇒ String

If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

Returns:

  • (String) 


152
153
154
 
# File 'lib/aws-sdk-s3/object.rb', line 152

def website_redirect_location
  data[:website_redirect_location]
end