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:



1539
1540
1541
1542
1543
1544
1545
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1539

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

#archive_status ⇒ String

The archive state of the head object.

Returns:

  • (String) 


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

def archive_status
  data[:archive_status]
end

#bucket ⇒ Bucket

Returns:



1548
1549
1550
1551
1552
1553
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1548

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

#bucket_key_enabled ⇒ Boolean

Indicates whether the object uses an S3 Bucket Key for server-side encryption with AWS KMS (SSE-KMS).

Returns:

  • (Boolean) 


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

def bucket_key_enabled
  data[:bucket_key_enabled]
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) 


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

def cache_control
  data[:cache_control]
end

#client ⇒ Client

Returns:



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

def client
  @client
end

#content_disposition ⇒ String

Specifies presentational information for the object.

Returns:

  • (String) 


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

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) 


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

def content_encoding
  data[:content_encoding]
end

#content_language ⇒ String

The language the content is in.

Returns:

  • (String) 


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

def content_language
  data[:content_language]
end

#content_length ⇒ Integer Also known as: size

Size of the body in bytes.

Returns:

  • (Integer) 


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

def content_length
  data[:content_length]
end

#content_type ⇒ String

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

Returns:

  • (String) 


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

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:



768
769
770
771
772
773
774
775
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 768

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:



367
368
369
370
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 367

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.



375
376
377
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 375

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



812
813
814
815
816
817
818
819
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 812

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.



405
406
407
408
409
410
411
412
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 405

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) 


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

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.



382
383
384
385
386
387
388
389
390
391
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 382

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) 


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

def expires
  data[:expires]
end

#expires_string ⇒ String

Returns:

  • (String) 


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

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 decrypting the object (for example, AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 used to encrypt the data. This value is used to decrypt the object when recovering it and must match the one used when storing the data. 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 User 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:



916
917
918
919
920
921
922
923
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 916

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

#head(options = {}) ⇒ Types::HeadObjectOutput

Examples:

Request syntax with placeholder values


object.head({
  if_match: "IfMatch",
  if_modified_since: Time.now,
  if_none_match: "IfNoneMatch",
  if_unmodified_since: Time.now,
  range: "Range",
  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 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

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

  • :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 User 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' HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this 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:



1527
1528
1529
1530
1531
1532
1533
1534
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1527

def head(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.head_object(options)
  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",
  bucket_key_enabled: false,
  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.

    This action is not supported by Amazon S3 on Outposts.

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

    This action is not supported by Amazon S3 on Outposts.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

    This action is not supported by Amazon S3 on Outposts.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

    This action is not supported by Amazon S3 on Outposts.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

    This action is not supported by Amazon S3 on Outposts.

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

    By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects. The STANDARD storage class provides high durability and high availability. Depending on performance needs, you can specify a different Storage Class. Amazon S3 on Outposts only uses the OUTPOSTS Storage Class. For more information, see Storage Classes in the Amazon S3 User Guide.

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

  • :bucket_key_enabled (Boolean) —

    Specifies whether Amazon S3 should use an S3 Bucket Key for object encryption with server-side encryption using AWS KMS (SSE-KMS). Setting this header to true causes Amazon S3 to use an S3 Bucket Key for object encryption with SSE-KMS.

    Specifying this header with an object action doesn’t affect bucket-level settings for S3 Bucket Key.

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



1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1076

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

Creation date of the object.

Returns:

  • (Time) 


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

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) 


354
355
356
357
358
359
360
361
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 354

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


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

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) 


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

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:



1557
1558
1559
1560
1561
1562
1563
1564
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1557

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) 


337
338
339
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 337

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) 


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

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) 


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

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) 


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

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(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?..."

Pre-signed UploadPart PUT


# the object uploaded using this URL will be publicly accessible
obj.presigned_url(:upload_part, part_number: 1, upload_id: 'uploadIdToken')
#=> "https://bucket-name.s3.amazonaws.com/object-key?..."

Parameters:

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



205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 205

def presigned_url(method, params = {})
  presigner = Presigner.new(client: client)

  if %w(delete head get put).include?(method.to_s)
    method = "#{method}_object".to_sym
  end

  presigner.presigned_url(
    method.downcase,
    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. Uses https unless secure: false is set. If the bucket name contains dots (.) then you will need to set secure: false.

s3.bucket('my-bucket.com').object('key')
  .public_url(virtual_host: true)
#=> "https://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.

  • :secure (Boolean) — default: true —

    When false, http will be used with virtual_host. This is required when the bucket name has a dot (.) in it.

Returns:

  • (String) 


240
241
242
243
244
245
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 240

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",
  bucket_key_enabled: false,
  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.

    This action is not supported by Amazon S3 on Outposts.

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

    This action is not supported by Amazon S3 on Outposts.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

    This action is not supported by Amazon S3 on Outposts.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

    This action is not supported by Amazon S3 on Outposts.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

    This action is not supported by Amazon S3 on Outposts.

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

    By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects. The STANDARD storage class provides high durability and high availability. Depending on performance needs, you can specify a different Storage Class. Amazon S3 on Outposts only uses the OUTPOSTS Storage Class. For more information, see Storage Classes in the Amazon S3 User Guide.

  • :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 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. If the KMS key does not exist in the same account issuing the command, you must use the full ARN and not just the ID.

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

  • :bucket_key_enabled (Boolean) —

    Specifies whether Amazon S3 should use an S3 Bucket Key for object encryption with server-side encryption using AWS KMS (SSE-KMS). Setting this header to true causes Amazon S3 to use an S3 Bucket Key for object encryption with SSE-KMS.

    Specifying this header with a PUT action doesn’t affect bucket-level settings for S3 Bucket Key.

  • :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 User 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. Must be formatted as a timestamp parameter.

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



1324
1325
1326
1327
1328
1329
1330
1331
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1324

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 a destination in a replication rule.

In replication, you have a source bucket on which you configure replication and destination bucket or buckets 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 a 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 and there is no replica modification replication in progress.

  • When replicating objects to multiple destination buckets the x-amz-replication-status header acts differently. The header of the source object will only return a value of COMPLETED when replication is successful to all destinations. The header will remain at value PENDING until replication has completed for all destinations. If one or more destinations fails replication the header will return FAILED.

For more information, see Replication.

Returns:

  • (String) 


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

def replication_status
  data[:replication_status]
end

#request_charged ⇒ String

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

Returns:

  • (String) 


251
252
253
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 251

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, 21 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 User 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:



1441
1442
1443
1444
1445
1446
1447
1448
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1441

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) 


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

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) 


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

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) 


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

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) 


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

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) 


244
245
246
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 244

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 or equal to :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 or equal to :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.



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

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.



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

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:



1568
1569
1570
1571
1572
1573
1574
1575
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1568

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) 


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

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



511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 511

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:



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

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:



418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 418

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) 


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

def website_redirect_location
  data[:website_redirect_location]
end