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.
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")
REQUEST_PARAMETERS | = | Request.query_parameters.map do |p| p.tr("-","_").to_sym | @private |
bucket | [R] | @return [Bucket] The bucket this object is in. |
key | [R] | @return [String] The objects unique key |
@param [Bucket] bucket The bucket this object belongs to. @param [String] key The object‘s 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:
@param (see Bucket#acl=) @return [nil]
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.
@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 [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+
@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.
@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.
@return (see copy_from)
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]
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
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 and etag.
@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.
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.
@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
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.
@return [S3Object, ObjectVersion] If the bucket has versioning
enabled, returns the {ObjectVersion} representing the version that was uploaded. If versioning is disabled, returns self.