class Aws::S3::ObjectSummary

Public Class Methods

new(*args) click to toggle source

@overload def initialize(bucket_name, key, options = {})

@param [String] bucket_name
@param [String] key
@option options [Client] :client

@overload def initialize(options = {})

@option options [required, String] :bucket_name
@option options [required, String] :key
@option options [Client] :client
# File lib/aws-sdk-s3/object_summary.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

Public Instance Methods

acl() click to toggle source

@return [ObjectAcl]

# File lib/aws-sdk-s3/object_summary.rb, line 1201
def acl
  ObjectAcl.new(
    bucket_name: @bucket_name,
    object_key: @key,
    client: @client
  )
end
bucket() click to toggle source

@return [Bucket]

# File lib/aws-sdk-s3/object_summary.rb, line 1210
def bucket
  Bucket.new(
    name: @bucket_name,
    client: @client
  )
end
bucket_name() click to toggle source

@return [String]

# File lib/aws-sdk-s3/object_summary.rb, line 36
def bucket_name
  @bucket_name
end
client() click to toggle source

@return [Client]

# File lib/aws-sdk-s3/object_summary.rb, line 96
def client
  @client
end
content_length()
Alias for: size
copy_from(source, options = {}) click to toggle source

@param (see Object#copy_from) @options (see Object#copy_from) @return (see Object#copy_from) @see Object#copy_from

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 16
def copy_from(source, options = {})
  object.copy_from(source, options)
end
Also aliased as: copy_from
copy_to(target, options = {}) click to toggle source

@param (see Object#copy_to) @options (see Object#copy_to) @return (see Object#copy_to) @see Object#copy_to

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 24
def copy_to(target, options = {})
  object.copy_to(target, options)
end
data() click to toggle source

@raise [NotImplementedError] Raises when {#data_loaded?} is `false`. @return [Types::Object]

Returns the data for this {ObjectSummary}.
# File lib/aws-sdk-s3/object_summary.rb, line 111
def data
  load unless @data
  @data
end
data_loaded?() click to toggle source

@return [Boolean]

Returns `true` if this resource is loaded.  Accessing attributes or
{#data} on an unloaded resource will trigger a call to {#load}.
# File lib/aws-sdk-s3/object_summary.rb, line 119
def data_loaded?
  !!@data
end
delete(options = {}) click to toggle source

@example Request syntax with placeholder values

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

@param [Hash] options ({}) @option options [String] :mfa

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.

@option options [String] :version_id

VersionId used to reference a specific version of the object.

@option options [String] :request_payer

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][1]
in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

@option options [Boolean] :bypass_governance_retention

Indicates whether S3 Object Lock should bypass Governance-mode
restrictions to process this operation. To use this header, you must
have the `s3:PutBucketPublicAccessBlock` permission.

@option options [String] :expected_bucket_owner

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.

@return [Types::DeleteObjectOutput]

# File lib/aws-sdk-s3/object_summary.rb, line 559
def delete(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.delete_object(options)
  resp.data
end
download_file(destination, options = {}) click to toggle source

@param (see Object#download_file) @options (see Object#download_file) @return (see Object#download_file) @see Object#download_file

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 79
def download_file(destination, options = {})
  object.download_file(destination, options)
end
etag() click to toggle source

The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata. The ETag may or may not be an MD5 digest of the object data. Whether or not it is depends on how the object was created and how it is encrypted as described below:

  • Objects created by the PUT Object, POST Object, or Copy operation, or through the Amazon Web Services Management Console, and are encrypted by SSE-S3 or plaintext, have ETags that are an MD5 digest of their object data.

  • Objects created by the PUT Object, POST Object, or Copy operation, or through the Amazon Web Services Management Console, and are encrypted by SSE-C or SSE-KMS, have ETags that are not an MD5 digest of their object data.

  • If an object is created by either the Multipart Upload or Part Copy operation, the ETag is not an MD5 digest, regardless of the method of encryption.

@return [String]

# File lib/aws-sdk-s3/object_summary.rb, line 71
def etag
  data[:etag]
end
exists?(options = {}) click to toggle source

@param [Hash] options ({}) @return [Boolean]

Returns `true` if the ObjectSummary exists.
# File lib/aws-sdk-s3/object_summary.rb, line 126
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
get(options = {}, &block) click to toggle source

@example Request syntax with placeholder values

object_summary.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",
})

@param [Hash] options ({}) @option options [String] :if_match

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

@option options [Time,DateTime,Date,Integer,String] :if_modified_since

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

@option options [String] :if_none_match

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

@option options [Time,DateTime,Date,Integer,String] :if_unmodified_since

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

@option options [String] :range

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][1].

<note markdown="1"> Amazon S3 doesn't support retrieving multiple ranges of data per
`GET` request.

 </note>

[1]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35

@option options [String] :response_cache_control

Sets the `Cache-Control` header of the response.

@option options [String] :response_content_disposition

Sets the `Content-Disposition` header of the response

@option options [String] :response_content_encoding

Sets the `Content-Encoding` header of the response.

@option options [String] :response_content_language

Sets the `Content-Language` header of the response.

@option options [String] :response_content_type

Sets the `Content-Type` header of the response.

@option options [Time,DateTime,Date,Integer,String] :response_expires

Sets the `Expires` header of the response.

@option options [String] :version_id

VersionId used to reference a specific version of the object.

@option options [String] :sse_customer_algorithm

Specifies the algorithm to use to when decrypting the object (for
example, AES256).

@option options [String] :sse_customer_key

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.

@option options [String] :sse_customer_key_md5

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.

@option options [String] :request_payer

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][1]
in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

@option options [Integer] :part_number

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.

@option options [String] :expected_bucket_owner

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.

@return [Types::GetObjectOutput]

# File lib/aws-sdk-s3/object_summary.rb, line 663
def get(options = {}, &block)
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.get_object(options, &block)
  resp.data
end
identifiers() click to toggle source

@deprecated @api private

# File lib/aws-sdk-s3/object_summary.rb, line 1250
def identifiers
  {
    bucket_name: @bucket_name,
    key: @key
  }
end
initiate_multipart_upload(options = {}) click to toggle source

@example Request syntax with placeholder values

multipartupload = object_summary.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",
})

@param [Hash] options ({}) @option options [String] :acl

The canned ACL to apply to the object.

This action is not supported by Amazon S3 on Outposts.

@option options [String] :cache_control

Specifies caching behavior along the request/reply chain.

@option options [String] :content_disposition

Specifies presentational information for the object.

@option options [String] :content_encoding

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.

@option options [String] :content_language

The language the content is in.

@option options [String] :content_type

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

@option options [Time,DateTime,Date,Integer,String] :expires

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

@option options [String] :grant_full_control

Gives the grantee READ, READ\_ACP, and WRITE\_ACP permissions on the
object.

This action is not supported by Amazon S3 on Outposts.

@option options [String] :grant_read

Allows grantee to read the object data and its metadata.

This action is not supported by Amazon S3 on Outposts.

@option options [String] :grant_read_acp

Allows grantee to read the object ACL.

This action is not supported by Amazon S3 on Outposts.

@option options [String] :grant_write_acp

Allows grantee to write the ACL for the applicable object.

This action is not supported by Amazon S3 on Outposts.

@option options [Hash<String,String>] :metadata

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

@option options [String] :server_side_encryption

The server-side encryption algorithm used when storing this object in
Amazon S3 (for example, AES256, aws:kms).

@option options [String] :storage_class

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][1]
in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html

@option options [String] :website_redirect_location

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.

@option options [String] :sse_customer_algorithm

Specifies the algorithm to use to when encrypting the object (for
example, AES256).

@option options [String] :sse_customer_key

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.

@option options [String] :sse_customer_key_md5

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.

@option options [String] :ssekms_key_id

Specifies the ID of the symmetric customer managed Amazon Web Services
KMS CMK to use for object encryption. All GET and PUT requests for an
object protected by Amazon Web Services KMS will fail if not made via
SSL or using SigV4. For information about configuring using any of the
officially supported Amazon Web Services SDKs and Amazon Web Services
CLI, see [Specifying the Signature Version in Request
Authentication][1] in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version

@option options [String] :ssekms_encryption_context

Specifies the Amazon Web Services 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.

@option options [Boolean] :bucket_key_enabled

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.

@option options [String] :request_payer

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][1]
in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

@option options [String] :tagging

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

@option options [String] :object_lock_mode

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

@option options [Time,DateTime,Date,Integer,String] :object_lock_retain_until_date

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

@option options [String] :object_lock_legal_hold_status

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

@option options [String] :expected_bucket_owner

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.

@return [MultipartUpload]

# File lib/aws-sdk-s3/object_summary.rb, line 824
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() click to toggle source

@return [String]

# File lib/aws-sdk-s3/object_summary.rb, line 41
def key
  @key
end
last_modified() click to toggle source

Creation date of the object. @return [Time]

# File lib/aws-sdk-s3/object_summary.rb, line 47
def last_modified
  data[:last_modified]
end
load() click to toggle source

@raise [NotImplementedError] @api private

# File lib/aws-sdk-s3/object_summary.rb, line 102
def load
  msg = "#load is not implemented, data only available via enumeration"
  raise NotImplementedError, msg
end
Also aliased as: reload
move_to(target, options = {}) click to toggle source

@param (see Object#move_to) @options (see Object#move_to) @return (see Object#move_to) @see Object#move_to

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 32
def move_to(target, options = {})
  object.move_to(target, options)
end
multipart_upload(id) click to toggle source

@param [String] id @return [MultipartUpload]

# File lib/aws-sdk-s3/object_summary.rb, line 1219
def multipart_upload(id)
  MultipartUpload.new(
    bucket_name: @bucket_name,
    object_key: @key,
    id: id,
    client: @client
  )
end
object() click to toggle source

@return [Object]

# File lib/aws-sdk-s3/object_summary.rb, line 1229
def object
  Object.new(
    bucket_name: @bucket_name,
    key: @key,
    client: @client
  )
end
owner() click to toggle source

The owner of the object @return [Types::Owner]

# File lib/aws-sdk-s3/object_summary.rb, line 89
def owner
  data[:owner]
end
presigned_post(options = {}) click to toggle source

@param (see Object#presigned_post) @options (see Object#presigned_post) @return (see Object#presigned_post) @see Object#presigned_post

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 40
def presigned_post(options = {})
  object.presigned_post(options)
end
presigned_url(http_method, params = {}) click to toggle source

@param (see Object#presigned_url) @options (see Object#presigned_url) @return (see Object#presigned_url) @see Object#presigned_url

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 48
def presigned_url(http_method, params = {})
  object.presigned_url(http_method, params)
end
public_url(options = {}) click to toggle source

@param (see Object#public_url) @options (see Object#public_url) @return (see Object#public_url) @see Object#public_url

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 56
def public_url(options = {})
  object.public_url(options)
end
put(options = {}) click to toggle source

@example Request syntax with placeholder values

object_summary.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",
})

@param [Hash] options ({}) @option options [String] :acl

The canned ACL to apply to the object. For more information, see
[Canned ACL][1].

This action is not supported by Amazon S3 on Outposts.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#CannedACL

@option options [String, StringIO, File] :body

Object data.

@option options [String] :cache_control

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][1].

[1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9

@option options [String] :content_disposition

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

[1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1

@option options [String] :content_encoding

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][1].

[1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11

@option options [String] :content_language

The language the content is in.

@option options [Integer] :content_length

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][1].

[1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13

@option options [String] :content_md5

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][1].

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html

@option options [String] :content_type

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][1].

[1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17

@option options [Time,DateTime,Date,Integer,String] :expires

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][1].

[1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21

@option options [String] :grant_full_control

Gives the grantee READ, READ\_ACP, and WRITE\_ACP permissions on the
object.

This action is not supported by Amazon S3 on Outposts.

@option options [String] :grant_read

Allows grantee to read the object data and its metadata.

This action is not supported by Amazon S3 on Outposts.

@option options [String] :grant_read_acp

Allows grantee to read the object ACL.

This action is not supported by Amazon S3 on Outposts.

@option options [String] :grant_write_acp

Allows grantee to write the ACL for the applicable object.

This action is not supported by Amazon S3 on Outposts.

@option options [Hash<String,String>] :metadata

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

@option options [String] :server_side_encryption

The server-side encryption algorithm used when storing this object in
Amazon S3 (for example, AES256, aws:kms).

@option options [String] :storage_class

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][1]
in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html

@option options [String] :website_redirect_location

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][1].

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][2] and [How to Configure Website Page
Redirects][3].

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html
[2]: https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html
[3]: https://docs.aws.amazon.com/AmazonS3/latest/dev/how-to-page-redirect.html

@option options [String] :sse_customer_algorithm

Specifies the algorithm to use to when encrypting the object (for
example, AES256).

@option options [String] :sse_customer_key

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.

@option options [String] :sse_customer_key_md5

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.

@option options [String] :ssekms_key_id

If `x-amz-server-side-encryption` is present and has the value of
`aws:kms`, this header specifies the ID of the Amazon Web Services Key
Management Service (Amazon Web Services 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
Amazon Web Services managed CMK in Amazon Web Services 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.

@option options [String] :ssekms_encryption_context

Specifies the Amazon Web Services 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.

@option options [Boolean] :bucket_key_enabled

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.

@option options [String] :request_payer

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][1]
in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

@option options [String] :tagging

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

@option options [String] :object_lock_mode

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

@option options [Time,DateTime,Date,Integer,String] :object_lock_retain_until_date

The date and time when you want this object's Object Lock to expire.
Must be formatted as a timestamp parameter.

@option options [String] :object_lock_legal_hold_status

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

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock.html

@option options [String] :expected_bucket_owner

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.

@return [Types::PutObjectOutput]

# File lib/aws-sdk-s3/object_summary.rb, line 1072
def put(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.put_object(options)
  resp.data
end
reload()
Alias for: load
restore_object(options = {}) click to toggle source

@example Request syntax with placeholder values

object_summary.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",
})

@param [Hash] options ({}) @option options [String] :version_id

VersionId used to reference a specific version of the object.

@option options [Types::RestoreRequest] :restore_request

Container for restore job parameters.

@option options [String] :request_payer

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][1]
in the *Amazon S3 User Guide*.

[1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

@option options [String] :expected_bucket_owner

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.

@return [Types::RestoreObjectOutput]

# File lib/aws-sdk-s3/object_summary.rb, line 1189
def restore_object(options = {})
  options = options.merge(
    bucket: @bucket_name,
    key: @key
  )
  resp = @client.restore_object(options)
  resp.data
end
size() click to toggle source

Size in bytes of the object @return [Integer]

# File lib/aws-sdk-s3/object_summary.rb, line 77
def size
  data[:size]
end
Also aliased as: content_length
storage_class() click to toggle source

The class of storage used to store the object. @return [String]

# File lib/aws-sdk-s3/object_summary.rb, line 83
def storage_class
  data[:storage_class]
end
upload_file(source, options = {}) click to toggle source

@param (see Object#upload_file) @options (see Object#upload_file) @return (see Object#upload_file) @see Object#upload_file

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 64
def upload_file(source, options = {})
  object.upload_file(source, options)
end
upload_stream(options = {}, &block) click to toggle source

@options (see Object#upload_stream) @return (see Object#upload_stream) @see Object#upload_stream

# File lib/aws-sdk-s3/customizations/object_summary.rb, line 71
def upload_stream(options = {}, &block)
  object.upload_stream(options, &block)
end
version(id) click to toggle source

@param [String] id @return [ObjectVersion]

# File lib/aws-sdk-s3/object_summary.rb, line 1239
def version(id)
  ObjectVersion.new(
    bucket_name: @bucket_name,
    object_key: @key,
    id: id,
    client: @client
  )
end
wait_until(options = {}, &block) click to toggle source

@deprecated Use [Aws::S3::Client] wait_until instead

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

@note The waiting operation is performed on a copy. The original resource

remains unchanged.

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

@yieldparam [Resource] resource to be used in the waiting condition.

@raise [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.

@raise [Aws::Waiters::Errors::UnexpectedError] Raised when an error is

encountered while polling for a resource that is not expected.

@raise [NotImplementedError] Raised when the resource does not

@option options [Integer] :max_attempts (10) Maximum number of attempts @option options [Integer] :delay (10) Delay between each attempt in seconds @option options [Proc] :before_attempt (nil) Callback invoked before each attempt @option options [Proc] :before_wait (nil) Callback invoked before each wait @return [Resource] if the waiter was successful

# File lib/aws-sdk-s3/object_summary.rb, line 255
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) click to toggle source

@param [Hash] options ({}) @option options [Integer] :max_attempts (20) @option options [Float] :delay (5) @option options [Proc] :before_attempt @option options [Proc] :before_wait @return [ObjectSummary]

# File lib/aws-sdk-s3/object_summary.rb, line 143
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))
  ObjectSummary.new({
    bucket_name: @bucket_name,
    key: @key,
    client: @client
  })
end
wait_until_not_exists(options = {}, &block) click to toggle source

@param [Hash] options ({}) @option options [Integer] :max_attempts (20) @option options [Float] :delay (5) @option options [Proc] :before_attempt @option options [Proc] :before_wait @return [ObjectSummary]

# File lib/aws-sdk-s3/object_summary.rb, line 162
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))
  ObjectSummary.new({
    bucket_name: @bucket_name,
    key: @key,
    client: @client
  })
end

Private Instance Methods

extract_bucket_name(args, options) click to toggle source
# File lib/aws-sdk-s3/object_summary.rb, line 1260
def extract_bucket_name(args, options)
  value = args[0] || options.delete(:bucket_name)
  case value
  when String then value
  when nil then raise ArgumentError, "missing required option :bucket_name"
  else
    msg = "expected :bucket_name to be a String, got #{value.class}"
    raise ArgumentError, msg
  end
end
extract_key(args, options) click to toggle source
# File lib/aws-sdk-s3/object_summary.rb, line 1271
def extract_key(args, options)
  value = args[1] || options.delete(:key)
  case value
  when String then value
  when nil then raise ArgumentError, "missing required option :key"
  else
    msg = "expected :key to be a String, got #{value.class}"
    raise ArgumentError, msg
  end
end
separate_params_and_options(options) click to toggle source
# File lib/aws-sdk-s3/object_summary.rb, line 1292
def separate_params_and_options(options)
  opts = Set.new(
    [:client, :max_attempts, :delay, :before_attempt, :before_wait]
  )
  waiter_opts = {}
  waiter_params = {}
  options.each_pair do |key, value|
    if opts.include?(key)
      waiter_opts[key] = value
    else
      waiter_params[key] = value
    end
  end
  waiter_opts[:client] ||= @client
  [waiter_opts, waiter_params]
end
yield_waiter_and_warn(waiter) { |waiter| ... } click to toggle source
# File lib/aws-sdk-s3/object_summary.rb, line 1282
def yield_waiter_and_warn(waiter, &block)
  if !@waiter_block_warned
    msg = "pass options to configure the waiter; "\
          "yielding the waiter is deprecated"
    warn(msg)
    @waiter_block_warned = true
  end
  yield(waiter.waiter)
end