Class: Aws::S3::Object

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

Defined Under Namespace

Classes: Collection

Actions collapse

Associations collapse

Read-Only Attributes 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) 


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

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)
  @waiter_block_warned = false
end

Instance Method Details

#accept_ranges ⇒ String

Indicates that a range of bytes was specified.

Returns:

  • (String) 


53
54
55
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 53

def accept_ranges
  data[:accept_ranges]
end

#acl ⇒ ObjectAcl

Returns:



1259
1260
1261
1262
1263
1264
1265
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1259

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

#bucket ⇒ Bucket

Returns:



1268
1269
1270
1271
1272
1273
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1268

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

#bucket_name ⇒ String

Returns:

  • (String) 


34
35
36
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 34

def bucket_name
  @bucket_name
end

#cache_control ⇒ String

Specifies caching behavior along the request/reply chain.

Returns:

  • (String) 


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

def cache_control
  data[:cache_control]
end

#client ⇒ Client

Returns:



318
319
320
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 318

def client
  @client
end

#content_disposition ⇒ String

Specifies presentational information for the object.

Returns:

  • (String) 


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

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) 


142
143
144
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 142

def content_encoding
  data[:content_encoding]
end

#content_language ⇒ String

The language the content is in.

Returns:

  • (String) 


148
149
150
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 148

def content_language
  data[:content_language]
end

#content_length ⇒ Integer Also known as: size

Size of the body in bytes.

Returns:

  • (Integer) 


99
100
101
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 99

def content_length
  data[:content_length]
end

#content_type ⇒ String

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

Returns:

  • (String) 


154
155
156
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 154

def content_type
  data[:content_type]
end

#copy_from(source, options = {}) ⇒ Object

Copies another object to this 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('target-bucket')
object = bucket.object('target-key')

# source as String
object.copy_from('source-bucket/source-key')

# source as Hash
object.copy_from(bucket:'source-bucket', key:'source-key')

# source as Aws::S3::Object
object.copy_from(bucket.object('source-key'))

Managed copy of large objects


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

Parameters:

Options Hash (options):

  • :multipart_copy (Boolean) — default: false —

    When true, the object will be copied using the multipart APIs. This is necessary for objects larger than 5GB and can provide performance improvements on large objects. Amazon S3 does not accept multipart copies for objects smaller than 5MB.

  • :content_length (Integer) —

    Only used when :multipart_copy is true. Passing this options avoids a HEAD request to query the source object size.

  • :copy_source_client (S3::Client) —

    Only used when :multipart_copy is true and the source object is in a different region. You do not need to specify this option if you have provided :content_length.

  • :copy_source_region (String) —

    Only used when :multipart_copy is true and the source object is in a different region. You do not need to specify this option if you have provided a :source_client or a :content_length.

See Also:



662
663
664
665
666
667
668
669
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 662

def copy_from(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.copy_object(options)
  resp.data
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 'gems/aws-sdk-s3/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:



341
342
343
344
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 341

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.



349
350
351
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 349

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. Required to permanently delete a versioned object if versioning is configured with MFA delete enabled.

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :request_payer (String) —

    Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3 Developer Guide.

  • :bypass_governance_retention (Boolean) —

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

Returns:



701
702
703
704
705
706
707
708
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 701

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) 


47
48
49
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 47

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 (Integer) — default: 10 —

    Customize threads used in the multipart download.

  • version_id (String) —

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

Returns:

  • (Boolean) —

    Returns true when the file is downloaded without any errors.



362
363
364
365
366
367
368
369
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 362

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) 


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

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.



356
357
358
359
360
361
362
363
364
365
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 356

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) 


62
63
64
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 62

def expiration
  data[:expiration]
end

#expires ⇒ Time

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

Returns:

  • (Time) 


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

def expires
  data[:expires]
end

#expires_string ⇒ String

Returns:

  • (String) 


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

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, see http://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 (for example, 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 S3 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 that the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3 Developer Guide.

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



791
792
793
794
795
796
797
798
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 791

def get(options = {}, &block)
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.get_object(options, &block)
  resp.data
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, DEEP_ARCHIVE
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  ssekms_encryption_context: "SSEKMSEncryptionContext",
  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 Amazon S3 (for example, 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 (for example, 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 S3 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 that the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    Specifies the ID of the symmetric customer managed AWS KMS CMK 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. For information about configuring using any of the officially supported AWS SDKs and AWS CLI, see Specifying the Signature Version in Request Authentication in the Amazon S3 Developer Guide.

  • :ssekms_encryption_context (String) —

    Specifies the AWS KMS Encryption Context to use for object encryption. The value of this header is a base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.

  • :request_payer (String) —

    Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3 Developer Guide.

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



918
919
920
921
922
923
924
925
926
927
928
929
930
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 918

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) 


39
40
41
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 39

def key
  @key
end

#last_modified ⇒ Time

Last modified date of the object

Returns:

  • (Time) 


93
94
95
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 93

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) 


328
329
330
331
332
333
334
335
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 328

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


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

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) 


116
117
118
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 116

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:



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

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

#multipart_upload(id) ⇒ MultipartUpload

Parameters:

  • id (String)

Returns:



1277
1278
1279
1280
1281
1282
1283
1284
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1277

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

#object_lock_legal_hold_status ⇒ String

Specifies whether a legal hold is in effect for this object. This header is only returned if the requester has the s3:GetObjectLegalHold permission. This header is not returned if the specified version of this object has never had a legal hold applied. For more information about S3 Object Lock, see Object Lock.

Returns:

  • (String) 


311
312
313
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 311

def object_lock_legal_hold_status
  data[:object_lock_legal_hold_status]
end

#object_lock_mode ⇒ String

The Object Lock mode, if any, that's in effect for this object. This header is only returned if the requester has the s3:GetObjectRetention permission. For more information about S3 Object Lock, see Object Lock.

Returns:

  • (String) 


289
290
291
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 289

def object_lock_mode
  data[:object_lock_mode]
end

#object_lock_retain_until_date ⇒ Time

The date and time when the Object Lock retention period expires. This header is only returned if the requester has the s3:GetObjectRetention permission.

Returns:

  • (Time) 


297
298
299
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 297

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) 


276
277
278
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 276

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:



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

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).



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

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) 


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

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, DEEP_ARCHIVE
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  ssekms_encryption_context: "SSEKMSEncryptionContext",
  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. For more information, see Canned ACL.

  • :body (String, IO) —

    Object data.

  • :cache_control (String) —

    Can be used to specify caching behavior along the request/reply chain. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.

  • :content_disposition (String) —

    Specifies presentational information for the object. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1.

  • :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. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11.

  • :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. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13.

  • :content_md5 (String) —

    The base64-encoded 128-bit MD5 digest of the message (without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, we recommend using the Content-MD5 mechanism as an end-to-end integrity check. For more information about REST request authentication, see REST Authentication.

  • :content_type (String) —

    A standard MIME type describing the format of the contents. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17.

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

    The date and time at which the object is no longer cacheable. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21.

  • :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 Amazon S3 (for example, AES256, aws:kms).

  • :storage_class (String) —

    If you don't specify, Standard is the default storage class. Amazon S3 supports other storage classes.

  • :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. For information about object metadata, see Object Key and Metadata.

    In the following example, the request header sets the redirect to an object (anotherPage.html) in the same bucket:

    x-amz-website-redirect-location: /anotherPage.html

    In the following example, the request header sets the object redirect to another website:

    x-amz-website-redirect-location: http://www.example.com/

    For more information about website hosting in Amazon S3, see Hosting Websites on Amazon S3 and How to Configure Website Page Redirects.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (for example, 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 S3 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 that the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    If x-amz-server-side-encryption is present and has the value of aws:kms, this header specifies the ID of the AWS Key Management Service (AWS KMS) symmetrical customer managed customer master key (CMK) that was used for the object.

    If the value of x-amz-server-side-encryption is aws:kms, this header specifies the ID of the symmetric customer managed AWS KMS CMK that will be used for the object. If you specify x-amz-server-side-encryption:aws:kms, but do not provide x-amz-server-side-encryption-aws-kms-key-id, Amazon S3 uses the AWS managed CMK in AWS to protect the data.

  • :ssekms_encryption_context (String) —

    Specifies the AWS KMS Encryption Context to use for object encryption. The value of this header is a base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.

  • :request_payer (String) —

    Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3 Developer Guide.

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

    Specifies whether a legal hold will be applied to this object. For more information about S3 Object Lock, see Object Lock.

Returns:



1135
1136
1137
1138
1139
1140
1141
1142
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1135

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

#replication_status ⇒ String

Amazon S3 can return this header if your request involves a bucket that is either a source or destination in a replication rule.

In replication, you have a source bucket on which you configure replication and destination bucket where Amazon S3 stores object replicas. When you request an object (GetObject) or object metadata (HeadObject) from these buckets, Amazon S3 will return the x-amz-replication-status header in the response as follows:

  • If requesting an object from the source bucket — Amazon S3 will return the x-amz-replication-status header if the object in your request is eligible for replication.

    For example, suppose that in your replication configuration, you specify object prefix TaxDocs requesting Amazon S3 to replicate objects with key prefix TaxDocs. Any objects you upload with this key name prefix, for example TaxDocs/document1.pdf, are eligible for replication. For any object request with this key name prefix, Amazon S3 will return the x-amz-replication-status header with value PENDING, COMPLETED or FAILED indicating object replication status.

  • If requesting an object from the destination bucket — Amazon S3 will return the x-amz-replication-status header with value REPLICA if the object in your request is a replica that Amazon S3 created.

For more information, see Replication.

Returns:

  • (String) 


270
271
272
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 270

def replication_status
  data[:replication_status]
end

#request_charged ⇒ String

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

Returns:

  • (String) 


234
235
236
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 234

def request_charged
  data[:request_charged]
end

#restore ⇒ String

If the object is an archived object (an object whose storage class is GLACIER), the response includes this header if either the archive restoration is in progress (see RestoreObject or an archive copy is already restored.

If an archive copy is already restored, the header value indicates when Amazon S3 is scheduled to delete the object copy. For example:

x-amz-restore: ongoing-request="false", expiry-date="Fri, 23 Dec 2012 00:00:00 GMT"

If the object restoration is in progress, the header returns the value ongoing-request="true".

For more information about archiving objects, see Transitioning Objects: General Considerations.

Returns:

  • (String) 


87
88
89
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 87

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, DEEP_ARCHIVE
      },
    },
  },
  request_payer: "requester", # accepts requester
})

Parameters:

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

    ({})

Options Hash (options):

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :restore_request (Types::RestoreRequest) —

    Container for restore job parameters.

  • :request_payer (String) —

    Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3 Developer Guide.

Returns:



1247
1248
1249
1250
1251
1252
1253
1254
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1247

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

#server_side_encryption ⇒ String

If the object is stored using server-side encryption either with an AWS KMS customer master key (CMK) or an Amazon S3-managed encryption key, the response includes this header with the value of the server-side encryption algorithm used when storing this object in Amazon S3 (for example, AES256, aws:kms).

Returns:

  • (String) 


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

def server_side_encryption
  data[:server_side_encryption]
end

#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) 


197
198
199
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 197

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) 


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

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 (AWS KMS) symmetric customer managed customer master key (CMK) that was used for the object.

Returns:

  • (String) 


214
215
216
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 214

def ssekms_key_id
  data[:ssekms_key_id]
end

#storage_class ⇒ String

Provides storage class information of the object. Amazon S3 returns this header for all objects except for Standard storage class objects.

For more information, see Storage Classes.

Returns:

  • (String) 


227
228
229
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 227

def storage_class
  data[:storage_class]
end

#upload_file(source, options = {}) {|response| ... } ⇒ 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')

The response of the S3 upload API is yielded if a block given.

# API response will have etag value of the file
obj.upload_file('/path/to/file') do |response|
  etag = response.etag
end

Parameters:

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

    A file on the local file system that will be uploaded as this object. This can either be a String or Pathname to the file, an open File object, or an open Tempfile object. If you pass an open File or Tempfile object, then you are responsible for closing it after the upload completes. When using an open Tempfile, rewind it before uploading or else the object will be empty.

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

  • :thread_count (Integer) — default: 10 —

    The number of parallel multipart uploads. This option is not used if the file is smaller than :multipart_threshold.

Yields:

  • (response)

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.



318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 318

def upload_file(source, options = {})
  uploading_options = options.dup
  uploader = FileUploader.new(
    multipart_threshold: uploading_options.delete(:multipart_threshold),
    client: client
  )
  response = uploader.upload(
    source,
    uploading_options.merge(bucket: bucket_name, key: key)
  )
  yield response if block_given?
  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) — default: 10 —

    The number of parallel multipart uploads

  • :tempfile (Boolean) — default: false —

    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.

  • :part_size (Integer) — default: 5242880 —

    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.



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

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:



1288
1289
1290
1291
1292
1293
1294
1295
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1288

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) 


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

def version_id
  data[:version_id]
end

#wait_until(options = {}) {|resource| ... } ⇒ 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) do |instance|
  instance.state.name == 'running'
end

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

Yield Parameters:

  • resource (Resource) —

    to be used in the waiting condition.

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



485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 485

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 = {}, &block) ⇒ 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:



373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 373

def wait_until_exists(options = {}, &block)
  options, params = separate_params_and_options(options)
  waiter = Waiters::ObjectExists.new(options)
  yield_waiter_and_warn(waiter, &block) 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 = {}, &block) ⇒ 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:



392
393
394
395
396
397
398
399
400
401
402
403
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 392

def wait_until_not_exists(options = {}, &block)
  options, params = separate_params_and_options(options)
  waiter = Waiters::ObjectNotExists.new(options)
  yield_waiter_and_warn(waiter, &block) 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) 


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

def website_redirect_location
  data[:website_redirect_location]
end