Class AWS::S3::S3Object
In: lib/aws/s3/s3_object.rb
Parent: Object

Represents an object in S3 identified by a key.

  object = bucket.objects["key-to-my-object"]
  object.key #=> 'key-to-my-object'

See {ObjectCollection} for more information on finding objects.

Writing and Reading S3Objects

  obj = bucket.objects["my-text-object"]

  obj.write("MY TEXT")
  obj.read
  #=> "MY TEXT"

  obj.write(File.new("README.txt"))
  obj.read
  # should equal File.read("README.txt")

Methods

Included Modules

Core::Model DataOptions

Classes and Modules

Module AWS::S3::S3Object::ACLProxy

Constants

REQUEST_PARAMETERS = Request.query_parameters.map do |p| p.tr("-","_").to_sym   @private

Attributes

bucket  [R]  @return [Bucket] The bucket this object is in.
key  [R]  @return [String] The objects unique key

Public Class methods

@param [Bucket] bucket The bucket this object belongs to. @param [String] key The object‘s key.

Public Instance methods

@return [Boolean] Returns true if the other object belongs to the

  same bucket and has the same key.

Returns the object‘s access control list. This will be an instance of AccessControlList, plus an additional change method:

 object.acl.change do |acl|
   # remove any grants to someone other than the bucket owner
   owner_id = object.bucket.owner.id
   acl.grants.reject! do |g|
     g.grantee.canonical_user_id != owner_id
   end
 end

Note that changing the ACL is not an atomic operation; it fetches the current ACL, yields it to the block, and then sets it again. Therefore, it‘s possible that you may overwrite a concurrent update to the ACL using this method.

@return [AccessControlList]

Sets the object‘s access control list. acl can be:

  • An XML policy as a string (which is passed to S3 uninterpreted)
  • An AccessControlList object
  • Any object that responds to to_xml
  • Any Hash that is acceptable as an argument to AccessControlList#initialize.

@param (see Bucket#acl=) @return [nil]

@return [Integer] Size of the object in bytes.

@note S3 does not compute content-type. It reports the content-type

  as was reported during the file upload.

@return [String] Returns the content type as reported by S3,

  defaults to an empty string when not provided during upload.

Copies data from one S3 object to another.

S3 handles the copy so the clients does not need to fetch the data and upload it again. You can also change the storage class and metadata of the object when copying.

@note This operation does not copy the ACL, storage class

  (standard vs. reduced redundancy) or server side encryption
  setting from the source object.  If you don't specify any of
  these options when copying, the object will have the default
  values as described below.

@param [Mixed] source

@param [Hash] options

@option options [String] :bucket_name The name of the bucket

  the source object can be found in.  Defaults to the current
  object's bucket.

@option options [Bucket] :bucket The bucket the source object

  can be found in.  Defaults to the current object's bucket.

@option options [Hash] :metadata A hash of metadata to save

  with the copied object.  Each name, value pair must conform
  to US-ASCII.  When blank, the sources metadata is copied.

@option options [String] :content_type The content type of

  the copied object.  Defaults to the source object's content
  type.

@option options [Boolean] :reduced_redundancy (false) If true the

  object is stored with reduced redundancy in S3 for a lower cost.

@option options [String] :version_id (nil) Causes the copy to

  read a specific version of the source object.

@option options [Symbol] :acl (private) A canned access

  control policy.  Valid values are:

  * +:private+
  * +:public_read+
  * +:public_read_write+
  * +:authenticated_read+
  * +:bucket_owner_read+
  * +:bucket_owner_full_control+

@option options [Symbol] :server_side_encryption (nil) If this

  option is set, the object will be stored using server side
  encryption.  The only valid value is +:aes256+, which
  specifies that the object should be stored using the AES
  encryption algorithm with 256 bit keys.  By default, this
  option uses the value of the +:s3_server_side_encryption+
  option in the current configuration; for more information,
  see {AWS.config}.

@option options :cache_control [String] Can be used to specify

  caching behavior.  See
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9

@return [nil]

Copies data from the current object to another object in S3.

S3 handles the copy so the client does not need to fetch the data and upload it again. You can also change the storage class and metadata of the object when copying.

@note This operation does not copy the ACL, storage class

  (standard vs. reduced redundancy) or server side encryption
  setting from this object to the new object.  If you don't
  specify any of these options when copying, the new object
  will have the default values as described below.

@param [S3Object,String] target An S3Object, or a string key of

  and object to copy to.

@param [Hash] options

@option options [String] :bucket_name The name of the bucket

  the object should be copied into.  Defaults to the current object's
  bucket.

@option options [Bucket] :bucket The bucket the target object

  should be copied into. Defaults to the current object's bucket.

@option options [Hash] :metadata A hash of metadata to save

  with the copied object.  Each name, value pair must conform
  to US-ASCII.  When blank, the sources metadata is copied.

@option options [Boolean] :reduced_redundancy (false) If true

  the object is stored with reduced redundancy in S3 for a
  lower cost.

@option options [Symbol] :acl (private) A canned access

  control policy.  Valid values are:

  * +:private+
  * +:public_read+
  * +:public_read_write+
  * +:authenticated_read+
  * +:bucket_owner_read+
  * +:bucket_owner_full_control+

@option options [Symbol] :server_side_encryption (nil) If this

  option is set, the object will be stored using server side
  encryption.  The only valid value is +:aes256+, which
  specifies that the object should be stored using the AES
  encryption algorithm with 256 bit keys.  By default, this
  option uses the value of the +:s3_server_side_encryption+
  option in the current configuration; for more information,
  see {AWS.config}.

@return [S3Object] Returns the copy (target) object.

Deletes the object from its S3 bucket.

@param [Hash] options @option [String] :version_id (nil) If present the specified version

  of this object will be deleted.  Only works for buckets that have
  had versioning enabled.

@return [nil]

eql?(other)

Alias for #==

Returns the object‘s ETag.

Generally the ETAG is the MD5 of the object. If the object was uploaded using multipart upload then this is the MD5 all of the upload-part-md5s.

@return [String] Returns the object‘s ETag

@return [DateTime,nil]

@return [String,nil]

Performs a HEAD request against this object and returns an object with useful information about the object, including:

@param [Hash] options @option options [String] :version_id Which version of this object

  to make a HEAD request against.

@return A head object response with metatadata,

  content_length, content_type, etag and server_side_encryption.

@private

Returns the object‘s last modified time.

@return [Time] Returns the object‘s last modified time.

@option [String] :version_id (nil) If present the metadata object

  will be for the specified version.

@return [ObjectMetadata] Returns an instance of ObjectMetadata

  representing the metadata for this object.

Moves an object to a new key.

This works by copying the object to a new key and then deleting the old object. This function returns the new object once this is done.

  bucket = s3.buckets['old-bucket']
  old_obj = bucket.objects['old-key']

  # renaming an object returns a new object
  new_obj = old_obj.move_to('new-key')

  old_obj.key     #=> 'old-key'
  old_obj.exists? #=> false

  new_obj.key     #=> 'new-key'
  new_obj.exists? #=> true

If you need to move an object to a different bucket, pass +:bucket+ or +:bucket_name+.

  obj = s3.buckets['old-bucket'].objects['old-key]
  obj.move_to('new-key', :bucket_name => 'new_bucket')

If the copy succeeds, but the then the delete fails, an error will be raised.

@param [String] target The key to move this object to.

@param [Hash] options

@option (see copy_to)

@return [S3Object] Returns a new object with the new key.

Performs a multipart upload. Use this if you have specific needs for how the upload is split into parts, or if you want to have more control over how the failure of an individual part upload is handled. Otherwise, {write} is much simpler to use.

@example Uploading an object in two parts

  bucket.objects.myobject.multipart_upload do |upload|
    upload.add_part("a" * 5242880)
    upload.add_part("b" * 2097152)
  end

@example Uploading parts out of order

  bucket.objects.myobject.multipart_upload do |upload|
    upload.add_part("b" * 2097152, :part_number => 2)
    upload.add_part("a" * 5242880, :part_number => 1)
  end

@example Aborting an upload after parts have been added

  bucket.objects.myobject.multipart_upload do |upload|
    upload.add_part("b" * 2097152, :part_number => 2)
    upload.abort
  end

@example Starting an upload and completing it later by ID

  upload = bucket.objects.myobject.multipart_upload
  upload.add_part("a" * 5242880)
  upload.add_part("b" * 2097152)
  id = upload.id

  # later or in a different process
  upload = bucket.objects.myobject.multipart_uploads[id]
  upload.complete(:remote_parts)

@yieldparam [MultipartUpload] upload A handle to the upload.

  {MultipartUpload#close} is called in an +ensure+ clause so
  that the upload will always be either completed or
  aborted.

@param [Hash] options Options for the upload.

@option options [Hash] :metadata A hash of metadata to be

  included with the object.  These will be sent to S3 as
  headers prefixed with +x-amz-meta+.  Each name, value pair
  must conform to US-ASCII.

@option options [Symbol] :acl (private) A canned access

  control policy.  Valid values are:

  * +:private+
  * +:public_read+
  * +:public_read_write+
  * +:authenticated_read+
  * +:bucket_owner_read+
  * +:bucket_owner_full_control+

@option options [Boolean] :reduced_redundancy (false) If true,

  Reduced Redundancy Storage will be enabled for the uploaded
  object.

@option options :cache_control [String] Can be used to specify

  caching behavior.  See
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9

@option options :content_disposition [String] Specifies

  presentational information for the object.  See
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec19.5.1

@option options :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.
  See
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11

@option options :content_type A standard MIME type

  describing the format of the object data.

@option options [Symbol] :server_side_encryption (nil) If this

  option is set, the object will be stored using server side
  encryption.  The only valid value is +:aes256+, which
  specifies that the object should be stored using the AES
  encryption algorithm with 256 bit keys.  By default, this
  option uses the value of the +:s3_server_side_encryption+
  option in the current configuration; for more information,
  see {AWS.config}.

@return [S3Object, ObjectVersion] If the bucket has versioning

  enabled, returns the {ObjectVersion} representing the
  version that was uploaded.  If versioning is disabled,
  returns self.

@example Abort any in-progress uploads for the object:

 object.multipart_uploads.each(&:abort)

@return [ObjectUploadCollection] Returns an object representing the

  collection of uploads that are in progress for this object.

Fetches the object data from S3.

@example Reading data as a string

  object.write('some data')
  object.read
  #=> 'some data'

@param [Hash] options @option options [String] :version_id Reads data from a

  specific version of this object.

@option options [Time] :if_unmodified_since If specified, the

  method will raise
  <tt>AWS::S3::Errors::PreconditionFailed</tt> unless the
  object has not been modified since the given time.

@option options [Time] :if_modified_since If specified, the

  method will raise <tt>AWS::S3::Errors::NotModified</tt> if
  the object has not been modified since the given time.

@option options [String] :if_match If specified, the method

  will raise <tt>AWS::S3::Errors::PreconditionFailed</tt>
  unless the object ETag matches the provided value.

@option options [String] :if_none_match If specified, the

  method will raise <tt>AWS::S3::Errors::NotModified</tt> if
  the object ETag matches the provided value.

@option options [Range] :range A byte range to read data from

rename_to(target, options = {})

Alias for move_to

@return [Symbol, nil] Returns the algorithm used to encrypt

  the object on the server side, or +nil+ if SSE was not used
  when storing the object.

@return [true, false] Returns true if the object was stored

  using server side encryption.

Returns a colletion representing all the object versions for this object.

  bucket.versioning_enabled? # => true
  version = bucket.objects["mykey"].versions.latest

@return [ObjectVersionCollection]

Writes data to the object in S3. This method will attempt to intelligently choose between uploading in one request and using {multipart_upload}.

Unless versioning is enabled, any data currently in S3 at {key} will be replaced.

You can pass +:data+ or +:file+ as the first argument or as options. Example usage:

  obj = s3.buckets.mybucket.objects.mykey
  obj.write("HELLO")
  obj.write(:data => "HELLO")
  obj.write(Pathname.new("myfile"))
  obj.write(:file => "myfile")

  # writes zero-length data
  obj.write(:metadata => { "avg-rating" => "5 stars" })

@overload write(options = {}) @overload write(data, options = {})

@param data The data to upload (see the +:data+

  option).

@param options [Hash] Additional upload options.

@option options :data The data to upload. Valid values include:

  * A string

  * A Pathname object

  * Any object responding to +read+ and +eof?+; the object
    must support the following access methods:
      read                     # all at once
      read(length) until eof?  # in chunks

    If you specify data this way, you must also include the
    +:content_length+ option.

@option options [String] :file Can be specified instead of +:data+;

  its value specifies the path of a file to upload.

@option options [Boolean] :single_request If this option is

  true, the method will always generate exactly one request
  to S3 regardless of how much data is being uploaded.

@option options [Integer] :content_length If provided, this

  option must match the total number of bytes written to S3
  during the operation.  This option is required if +:data+
  is an IO-like object without a +size+ method.

@option options [Integer] :multipart_threshold Specifies the

  maximum size in bytes of a single-request upload.  If the
  data being uploaded is larger than this threshold, it will
  be uploaded using {#multipart_upload}.

@option options [Integer] :multipart_min_part_size The

  minimum size of a part if a multi-part upload is used.  S3
  will reject non-final parts smaller than 5MB, and the
  default for this option is 5MB.

@option options [Hash] :metadata A hash of metadata to be

  included with the object.  These will be sent to S3 as
  headers prefixed with +x-amz-meta+.  Each name, value pair
  must conform to US-ASCII.

@option options [Symbol] :acl (private) A canned access

  control policy.  Valid values are:

  * +:private+
  * +:public_read+
  * +:public_read_write+
  * +:authenticated_read+
  * +:bucket_owner_read+
  * +:bucket_owner_full_control+

@option options [Symbol] :storage_class Controls whether

  Reduced Redundancy Storage is enabled for the object.
  Valid values are +:standard+ (the default) or
  +:reduced_redundancy+.

@option options :cache_control [String] Can be used to specify

  caching behavior.  See
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9

@option options :content_disposition [String] Specifies

  presentational information for the object.  See
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec19.5.1

@option options :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.
  See
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11

@option options :content_type A standard MIME type

  describing the format of the object data.

@option options [Symbol] :server_side_encryption (nil) If this

  option is set, the object will be stored using server side
  encryption.  The only valid value is +:aes256+, which
  specifies that the object should be stored using the AES
  encryption algorithm with 256 bit keys.  By default, this
  option uses the value of the +:s3_server_side_encryption+
  option in the current configuration; for more information,
  see {AWS.config}.

@return [S3Object, ObjectVersion] If the bucket has versioning

  enabled, returns the {ObjectVersion} representing the
  version that was uploaded.  If versioning is disabled,
  returns self.

[Validate]