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

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) 


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

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) 


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

def accept_ranges
  data[:accept_ranges]
end

#acl ⇒ ObjectAcl

Returns:



1349
1350
1351
1352
1353
1354
1355
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1349

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

#bucket ⇒ Bucket

Returns:



1358
1359
1360
1361
1362
1363
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1358

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

#bucket_name ⇒ String

Returns:

  • (String) 


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

def bucket_name
  @bucket_name
end

#cache_control ⇒ String

Specifies caching behavior along the request/reply chain.

Returns:

  • (String) 


131
132
133
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 131

def cache_control
  data[:cache_control]
end

#client ⇒ Client

Returns:



322
323
324
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 322

def client
  @client
end

#content_disposition ⇒ String

Specifies presentational information for the object.

Returns:

  • (String) 


137
138
139
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 137

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) 


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

def content_encoding
  data[:content_encoding]
end

#content_language ⇒ String

The language the content is in.

Returns:

  • (String) 


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

def content_language
  data[:content_language]
end

#content_length ⇒ Integer Also known as: size

Size of the body in bytes.

Returns:

  • (Integer) 


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

def content_length
  data[:content_length]
end

#content_type ⇒ String

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

Returns:

  • (String) 


157
158
159
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 157

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. Raises an ArgumentError if this option is provided when :multipart_copy is false or not set.

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



718
719
720
721
722
723
724
725
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 718

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"


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

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:



345
346
347
348
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 345

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.



353
354
355
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 353

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,
  expected_bucket_owner: "AccountId",
})

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.

  • :expected_bucket_owner (String) —

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

Returns:



762
763
764
765
766
767
768
769
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 762

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) 


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

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.



379
380
381
382
383
384
385
386
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 379

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) 


109
110
111
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 109

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.



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

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) 


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

def expiration
  data[:expiration]
end

#expires ⇒ Time

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

Returns:

  • (Time) 


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

def expires
  data[:expires]
end

#expires_string ⇒ String

Returns:

  • (String) 


168
169
170
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 168

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,
  expected_bucket_owner: "AccountId",
})

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 https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

    Amazon S3 doesn't support retrieving multiple ranges of data per GET request.

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

  • :expected_bucket_owner (String) —

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

Returns:



866
867
868
869
870
871
872
873
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 866

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, OUTPOSTS
  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
  expected_bucket_owner: "AccountId",
})

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.

  • :expected_bucket_owner (String) —

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

Returns:



998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 998

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) 


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

def key
  @key
end

#last_modified ⇒ Time

Last modified date of the object

Returns:

  • (Time) 


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

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) 


332
333
334
335
336
337
338
339
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 332

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


192
193
194
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 192

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) 


119
120
121
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 119

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:



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

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

#multipart_upload(id) ⇒ MultipartUpload

Parameters:

  • id (String)

Returns:



1367
1368
1369
1370
1371
1372
1373
1374
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1367

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) 


315
316
317
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 315

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) 


293
294
295
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 293

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) 


301
302
303
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 301

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) 


280
281
282
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 280

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:



134
135
136
137
138
139
140
141
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 134

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



191
192
193
194
195
196
197
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 191

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) 


215
216
217
218
219
220
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 215

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, OUTPOSTS
  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
  expected_bucket_owner: "AccountId",
})

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, StringIO, File) —

    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, S3 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.

  • :expected_bucket_owner (String) —

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

Returns:



1220
1221
1222
1223
1224
1225
1226
1227
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1220

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) 


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

def replication_status
  data[:replication_status]
end

#request_charged ⇒ String

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

Returns:

  • (String) 


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

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) 


90
91
92
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 90

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

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.

  • :expected_bucket_owner (String) —

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

Returns:



1337
1338
1339
1340
1341
1342
1343
1344
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1337

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) 


186
187
188
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 186

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) 


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

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) 


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

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) 


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

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 S3 Standard storage class objects.

For more information, see Storage Classes.

Returns:

  • (String) 


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

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

You can provide a callback to monitor progress of the upload:

# bytes and totals are each an array with 1 entry per part
progress = Proc.new do |bytes, totals|
  puts bytes.map.with_index { |b, i| "Part #{i+1}: #{b} / #{totals[i]}"}.join(' ') + "Total: #{100.0 * bytes.sum / totals.sum }%" }
end
obj.upload_file('/path/to/file')

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.

  • :progress_callback (Proc) —

    A Proc that will be called when each chunk of the upload is sent. It will be invoked with [bytes_read], [total_sizes]

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.



335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 335

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.



265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 265

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:



1378
1379
1380
1381
1382
1383
1384
1385
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1378

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) 


125
126
127
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 125

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



489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 489

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:



377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 377

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:



396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 396

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) 


176
177
178
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 176

def website_redirect_location
  data[:website_redirect_location]
end