You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Class: Aws::S3::Object

Inherits:
Resources::Resource show all
Defined in:
aws-sdk-resources/lib/aws-sdk-resources/services/s3/object.rb

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #load, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

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

Overloads:

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

    Parameters:

    • bucket_name (String)
    • key (String)

    Options Hash (options):

    • :client (Client)

      When `:client is not given, the options hash is used to construct a new Client object.

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

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

      When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#accept_rangesString (readonly)

Returns:

  • (String)

#bucket_nameString (readonly)

Returns:

  • (String)

#cache_controlString (readonly)

Specifies caching behavior along the request/reply chain.

Returns:

  • (String)

    Specifies caching behavior along the request/reply chain.

#content_dispositionString (readonly)

Specifies presentational information for the object.

Returns:

  • (String)

    Specifies presentational information for the object.

#content_encodingString (readonly)

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)

    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_languageString (readonly)

The language the content is in.

Returns:

  • (String)

    The language the content is in.

#content_lengthInteger (readonly) Also known as: size

Size of the body in bytes.

Returns:

  • (Integer)

    Size of the body in bytes.

#content_typeString (readonly)

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

Returns:

  • (String)

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

#delete_markerBoolean (readonly)

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)

    Specifies whether the object retrieved was (true) or was not (false) a Delete Marker.

#etagString (readonly)

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

Returns:

  • (String)

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

#expirationString (readonly)

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)

    If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header.

#expiresTime (readonly)

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

Returns:

  • (Time)

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

#expires_stringString (readonly)

Returns:

  • (String)

#keyString (readonly)

Returns:

  • (String)

#last_modifiedTime (readonly)

Last modified date of the object

Returns:

  • (Time)

    Last modified date of the object.

#metadataHash<String,String> (readonly)

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

Returns:

  • (Hash<String,String>)

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

#missing_metaInteger (readonly)

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)

    This is set to the number of metadata entries not returned in x-amz-meta headers.

#parts_countInteger (readonly)

The count of parts this object has.

Returns:

  • (Integer)

    The count of parts this object has.

#replication_statusString (readonly)

Possible values:

  • COMPLETE
  • PENDING
  • FAILED
  • REPLICA

Returns:

  • (String)

#request_chargedString (readonly)

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

Possible values:

  • requester

Returns:

  • (String)

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

#restoreString (readonly)

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

Returns:

  • (String)

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

#server_side_encryptionString (readonly)

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

Possible values:

  • AES256
  • aws:kms

Returns:

  • (String)

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

#sse_customer_algorithmString (readonly)

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)

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

#sse_customer_key_md5String (readonly)

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)

    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.

#ssekms_key_idString (readonly)

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

Returns:

  • (String)

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

#storage_classString (readonly)

Possible values:

  • STANDARD
  • REDUCED_REDUNDANCY
  • STANDARD_IA

Returns:

  • (String)

#version_idString (readonly)

Version of the object.

Returns:

  • (String)

    Version of the object.

#website_redirect_locationString (readonly)

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)

    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.

Instance Method Details

#aclObjectAcl

Returns:

#bucketBucket

Returns:

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

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)

Request syntax example with placeholder values


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

Parameters:

Options Hash (options):

  • :multipart_copy (Boolean) — default: false

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

  • :content_length (Integer)

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

  • :copy_source_client (S3::Client)

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

  • :copy_source_region (String)

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

  • :acl (String)

    The canned ACL to apply to the object.

  • :cache_control (String)

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String)

    Specifies presentational information for the object.

  • :content_encoding (String)

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

  • :content_language (String)

    The language the content is in.

  • :content_type (String)

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

  • :copy_source (required, String)

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

  • :copy_source_if_match (String)

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

  • :copy_source_if_modified_since (Time)

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

  • :copy_source_if_none_match (String)

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

  • :copy_source_if_unmodified_since (Time)

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

  • :expires (Time)

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

  • :grant_full_control (String)

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

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>)

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

  • :metadata_directive (String)

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

  • :tagging_directive (String)

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

  • :server_side_encryption (String)

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

  • :storage_class (String)

    The type of storage to use for the object. Defaults to \'STANDARD\'.

  • :website_redirect_location (String)

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

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :ssekms_key_id (String)

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

  • :copy_source_sse_customer_algorithm (String)

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

  • :copy_source_sse_customer_key (String)

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

  • :copy_source_sse_customer_key_md5 (String)

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

  • :request_payer (String)

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

  • :tagging (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

  • :multipart_copy (Boolean) — default: false

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

  • :content_length (Integer)

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

  • :copy_source_client (S3::Client)

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

  • :copy_source_region (String)

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

  • :acl (String)

    The canned ACL to apply to the object.

  • :cache_control (String)

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String)

    Specifies presentational information for the object.

  • :content_encoding (String)

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

  • :content_language (String)

    The language the content is in.

  • :content_type (String)

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

  • :copy_source_if_match (String)

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

  • :copy_source_if_modified_since (Time)

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

  • :copy_source_if_none_match (String)

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

  • :copy_source_if_unmodified_since (Time)

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

  • :expires (Time)

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

  • :grant_full_control (String)

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

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>)

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

  • :metadata_directive (String)

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

  • :tagging_directive (String)

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

  • :server_side_encryption (String)

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

  • :storage_class (String)

    The type of storage to use for the object. Defaults to \'STANDARD\'.

  • :website_redirect_location (String)

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

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :ssekms_key_id (String)

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

  • :copy_source_sse_customer_algorithm (String)

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

  • :copy_source_sse_customer_key (String)

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

  • :copy_source_sse_customer_key_md5 (String)

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

  • :request_payer (String)

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

  • :tagging (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:



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

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

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

Note:

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

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

Examples:

Basic object copy


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

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

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

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

Managed copy of large objects


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

Parameters:

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

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

    • Aws::S3::Object
    • Hash - with :bucket and :key
    • String - formatted like "target-bucket-name/target-key"

Options Hash (options):

  • :multipart_copy (Boolean) — default: false

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

  • :content_length (Integer)

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

  • :copy_source_client (S3::Client)

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

  • :copy_source_region (String)

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

  • :acl (String)

    The canned ACL to apply to the object.

  • :cache_control (String)

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String)

    Specifies presentational information for the object.

  • :content_encoding (String)

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

  • :content_language (String)

    The language the content is in.

  • :content_type (String)

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

  • :copy_source_if_match (String)

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

  • :copy_source_if_modified_since (Time)

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

  • :copy_source_if_none_match (String)

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

  • :copy_source_if_unmodified_since (Time)

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

  • :expires (Time)

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

  • :grant_full_control (String)

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

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>)

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

  • :metadata_directive (String)

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

  • :tagging_directive (String)

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

  • :server_side_encryption (String)

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

  • :storage_class (String)

    The type of storage to use for the object. Defaults to \'STANDARD\'.

  • :website_redirect_location (String)

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

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :ssekms_key_id (String)

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

  • :copy_source_sse_customer_algorithm (String)

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

  • :copy_source_sse_customer_key (String)

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

  • :copy_source_sse_customer_key_md5 (String)

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

  • :request_payer (String)

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

  • :tagging (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.



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

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

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

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. If there isn't a null version, Amazon S3 does not remove any objects.

Examples:

Request syntax example with placeholder values


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

Options Hash (options):

  • :mfa (String)

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

  • :version_id (String)

    VersionId used to reference a specific version of the object.

  • :request_payer (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

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

Downloads a file in S3 to a path on disk.

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

Files larger than 5MB are downloaded using multipart method

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

Parameters:

  • destination (String)

    Where to download the file to

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

    a customizable set of options

Options Hash (options):

  • mode (String)

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

  • chunk_size (String)

    required in get_range mode

  • thread_count (String)

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

Returns:

  • (Boolean)

    Returns true when the file is downloaded without any errors.



282
283
284
285
286
287
# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/object.rb', line 282

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

#exists?Boolean

Returns true if this Object exists. Returns false otherwise.

Returns:

  • (Boolean)

    Returns true if this Object exists. Returns false otherwise.

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

Retrieves objects from Amazon S3.

Examples:

Request syntax example with placeholder values


object.get({
  response_target: "/path/to/file", # where to write response data, file path, or IO object
  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,
  use_accelerate_endpoint: false,
})

Options Hash (options):

  • :response_target (IO, String)

    Specifies where to stream response data. You can provide the path where a file will be created on disk, or you can provide an IO object. If omitted, the response data will be loaded into memory and written to a StringIO object.

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

    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)

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

  • :range (String)

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

  • :response_cache_control (String)

    Sets the Cache-Control header of the response.

  • :response_content_disposition (String)

    Sets the Content-Disposition header of the response

  • :response_content_encoding (String)

    Sets the Content-Encoding header of the response.

  • :response_content_language (String)

    Sets the Content-Language header of the response.

  • :response_content_type (String)

    Sets the Content-Type header of the response.

  • :response_expires (Time)

    Sets the Expires header of the response.

  • :version_id (String)

    VersionId used to reference a specific version of the object.

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :request_payer (String)

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

  • :part_number (Integer)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

#initiate_multipart_upload(options = {}) ⇒ MultipartUpload

Examples:

Request syntax example with placeholder values


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
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
  use_accelerate_endpoint: false,
})

Basic usage

multipartupload = object.initiate_multipart_upload(options)
multipartupload.id
#=> "multipartupload-id"

Options Hash (options):

  • :acl (String)

    The canned ACL to apply to the object.

  • :cache_control (String)

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String)

    Specifies presentational information for the object.

  • :content_encoding (String)

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

  • :content_language (String)

    The language the content is in.

  • :content_type (String)

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

  • :expires (Time)

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

  • :grant_full_control (String)

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

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>)

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

  • :server_side_encryption (String)

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

  • :storage_class (String)

    The type of storage to use for the object. Defaults to \'STANDARD\'.

  • :website_redirect_location (String)

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

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :ssekms_key_id (String)

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

  • :request_payer (String)

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

  • :tagging (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

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

Options Hash (options):

  • :multipart_copy (Boolean) — default: false

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

  • :content_length (Integer)

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

  • :copy_source_client (S3::Client)

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

  • :copy_source_region (String)

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

  • :acl (String)

    The canned ACL to apply to the object.

  • :cache_control (String)

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String)

    Specifies presentational information for the object.

  • :content_encoding (String)

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

  • :content_language (String)

    The language the content is in.

  • :content_type (String)

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

  • :copy_source_if_match (String)

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

  • :copy_source_if_modified_since (Time)

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

  • :copy_source_if_none_match (String)

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

  • :copy_source_if_unmodified_since (Time)

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

  • :expires (Time)

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

  • :grant_full_control (String)

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

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>)

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

  • :metadata_directive (String)

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

  • :tagging_directive (String)

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

  • :server_side_encryption (String)

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

  • :storage_class (String)

    The type of storage to use for the object. Defaults to \'STANDARD\'.

  • :website_redirect_location (String)

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

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :ssekms_key_id (String)

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

  • :copy_source_sse_customer_algorithm (String)

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

  • :copy_source_sse_customer_key (String)

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

  • :copy_source_sse_customer_key_md5 (String)

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

  • :request_payer (String)

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

  • :tagging (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

See Also:



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

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

#multipart_upload(id) ⇒ MultipartUpload

Parameters:

Returns:

See Also:

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

Options Hash (options):

Returns:

See Also:



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

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

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

Generates a pre-signed URL for this object.

Examples:

Pre-signed GET URL, valid for one hour


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

Pre-signed PUT with a canned ACL


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

Parameters:

  • http_method (Symbol)

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

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

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

    HTTP Method Client Method
    :get Client#get_object
    :put Client#put_object
    :head Client#head_object
    :delete Client#delete_object

Options Hash (params):

  • :virtual_host (Boolean) — default: false

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

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

  • :expires_in (Integer) — default: 900

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

Returns:

  • (String)

Raises:

  • (ArgumentError)

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



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

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

#public_url(options = {}) ⇒ String

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

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

To use virtual hosted bucket url (disables https):

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

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :virtual_host (Boolean) — default: false

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

Returns:

  • (String)


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

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

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

Adds an object to a bucket.

Examples:

Request syntax example 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, # file/IO object, or string data
  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
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
  use_accelerate_endpoint: false,
})

Options Hash (options):

  • :acl (String)

    The canned ACL to apply to the object.

  • :body (IO, String)

    Object data.

  • :cache_control (String)

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String)

    Specifies presentational information for the object.

  • :content_encoding (String)

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

  • :content_language (String)

    The language the content is in.

  • :content_length (Integer)

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

  • :content_md5 (String)

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

  • :content_type (String)

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

  • :expires (Time)

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

  • :grant_full_control (String)

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

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash<String,String>)

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

  • :server_side_encryption (String)

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

  • :storage_class (String)

    The type of storage to use for the object. Defaults to \'STANDARD\'.

  • :website_redirect_location (String)

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

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :ssekms_key_id (String)

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

  • :request_payer (String)

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

  • :tagging (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

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

Restores an archived copy of an object back into Amazon S3

Examples:

Request syntax example 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",
        },
      },
      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",
        },
      },
    },
    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
      },
    },
  },
  request_payer: "requester", # accepts requester
  use_accelerate_endpoint: false,
})

Options Hash (options):

Returns:

See Also:

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

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

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

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

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

Parameters:

  • source (String, Pathname, File, Tempfile)

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

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

    a customizable set of options

Options Hash (options):

  • :multipart_threshold (Integer) — default: 15728640

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

  • :acl (String)

    The canned ACL to apply to the object.

  • :cache_control (String)

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String)

    Specifies presentational information for the object.

  • :content_encoding (String)

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

  • :content_language (String)

    The language the content is in.

  • :content_type (String)

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

  • :expires (Time)

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

  • :grant_full_control (String)

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

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

  • :metadata (Hash)

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

  • :server_side_encryption (String)

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

  • :storage_class (String)

    The type of storage to use for the object. Defaults to \'STANDARD\'.

  • :website_redirect_location (String)

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

  • :sse_customer_algorithm (String)

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

  • :sse_customer_key (String)

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

  • :sse_customer_key_md5 (String)

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

  • :ssekms_key_id (String)

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

  • :request_payer (String)

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

  • :tagging (String)

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

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

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.



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

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

#version(id) ⇒ ObjectVersion

Parameters:

Returns:

#wait_until_exists {|waiter| ... } ⇒ Object

Waits until this Object is exists. This method waits by polling Client#head_object until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 5
#max_attempts 20

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

object.wait_until_exists

Yield Parameters:

Returns:

  • (Object)

    Returns a copy of this Object that is not loaded.

Raises:

See Also:

#wait_until_not_exists {|waiter| ... } ⇒ Object

Waits until this Object is not_exists. This method waits by polling Client#head_object until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 5
#max_attempts 20

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

object.wait_until_not_exists

Yield Parameters:

Returns:

  • (Object)

    Returns a copy of this Object that is not loaded.

Raises:

See Also: