Class: AWS::S3::S3Object
- Inherits:
-
Object
- Object
- AWS::S3::S3Object
- Includes:
- DataOptions
- Defined in:
- lib/aws/s3/s3_object.rb
Overview
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")
Instance Attribute Summary collapse
-
#bucket ⇒ Bucket
readonly
The bucket this object is in.
-
#key ⇒ String
readonly
The objects unique key.
Instance Method Summary collapse
-
#==(other) ⇒ Boolean
(also: #eql?)
Returns true if the other object belongs to the same bucket and has the same key.
-
#acl ⇒ AccessControlList
Returns the object’s access control list.
-
#acl=(acl) ⇒ nil
Sets the object’s access control list.
-
#content_length ⇒ Integer
Size of the object in bytes.
-
#content_type ⇒ String
Returns the content type as reported by S3, defaults to an empty string when not provided during upload.
-
#copy_from(source, options = {}) ⇒ nil
Copies data from one S3 object to another.
-
#copy_to(target, options = {}) ⇒ nil
Copies data from the current object to another object in S3.
-
#delete(options = {}) ⇒ nil
Deletes the object from its S3 bucket.
-
#etag ⇒ String
Returns the object’s ETag.
- #exists? ⇒ Boolean
-
#head(options = {}) ⇒ Object
Performs a HEAD request against this object and returns an object with useful information about the object, including:.
-
#initialize(bucket, key, opts = {}) ⇒ S3Object
constructor
A new instance of S3Object.
-
#last_modified ⇒ Time
Returns the object’s last modified time.
-
#metadata(options = {}) ⇒ ObjectMetadata
Returns an instance of ObjectMetadata representing the metadata for this object.
-
#multipart_upload(options = {}) {|upload| ... } ⇒ S3Object, ObjectVersion
Performs a multipart upload.
-
#multipart_uploads ⇒ ObjectUploadCollection
Returns an object representing the collection of uploads that are in progress for this object.
-
#presigned_post(options = {}) ⇒ PresignedPost
Generates fields for a presigned POST to this object.
-
#public_url(options = {}) ⇒ URI::HTTP, URI::HTTPS
Generates a public (not authenticated) URL for the object.
-
#read(options = {}, &blk) ⇒ Object
Fetches the object data from S3.
-
#reduced_redundancy=(value) ⇒ true, false
Changes the storage class of the object to enable or disable Reduced Redundancy Storage (RRS).
-
#url_for(method, options = {}) ⇒ URI::HTTP, URI::HTTPS
Generates a presigned URL for an operation on this object.
-
#versions ⇒ ObjectVersionCollection
Returns a colletion representing all the object versions for this object.
-
#write(options_or_data = nil, options = nil) ⇒ S3Object, ObjectVersion
Writes data to the object in S3.
Constructor Details
#initialize(bucket, key, opts = {}) ⇒ S3Object
Returns a new instance of S3Object.
52 53 54 55 56 |
# File 'lib/aws/s3/s3_object.rb', line 52 def initialize(bucket, key, opts = {}) super @key = key @bucket = bucket end |
Instance Attribute Details
#bucket ⇒ Bucket (readonly)
Returns The bucket this object is in.
62 63 64 |
# File 'lib/aws/s3/s3_object.rb', line 62 def bucket @bucket end |
#key ⇒ String (readonly)
Returns The objects unique key.
59 60 61 |
# File 'lib/aws/s3/s3_object.rb', line 59 def key @key end |
Instance Method Details
#==(other) ⇒ Boolean Also known as: eql?
Returns true if the other object belongs to the same bucket and has the same key.
71 72 73 |
# File 'lib/aws/s3/s3_object.rb', line 71 def ==(other) other.kind_of?(S3Object) and other.bucket == bucket and other.key == key end |
#acl ⇒ AccessControlList
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.
597 598 599 600 601 602 603 604 605 |
# File 'lib/aws/s3/s3_object.rb', line 597 def acl acl = client.get_object_acl( :bucket_name => bucket.name, :key => key ).acl acl.extend ACLProxy acl.object = self acl end |
#acl=(acl) ⇒ nil
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.
616 617 618 619 620 621 622 |
# File 'lib/aws/s3/s3_object.rb', line 616 def acl=(acl) client.set_object_acl( :bucket_name => bucket.name, :key => key, :acl => acl) nil end |
#content_length ⇒ Integer
Returns Size of the object in bytes.
122 123 124 |
# File 'lib/aws/s3/s3_object.rb', line 122 def content_length head.content_length end |
#content_type ⇒ String
S3 does not compute content-type. It reports the content-type as was reported during the file upload.
Returns the content type as reported by S3, defaults to an empty string when not provided during upload.
130 131 132 |
# File 'lib/aws/s3/s3_object.rb', line 130 def content_type head.content_type end |
#copy_from(source, options = {}) ⇒ 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.
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 |
# File 'lib/aws/s3/s3_object.rb', line 441 def copy_from source, = {} copy_opts = { :bucket_name => bucket.name, :key => key } copy_opts[:copy_source] = case source when S3Object "#{source.bucket.name}/#{source.key}" when ObjectVersion copy_opts[:version_id] = source.version_id "#{source.object.bucket.name}/#{source.object.key}" else case when [:bucket] then "#{[:bucket].name}/#{source}" when [:bucket_name] then "#{[:bucket_name]}/#{source}" else "#{self.bucket.name}/#{source}" end end if [:metadata] copy_opts[:metadata] = [:metadata] copy_opts[:metadata_directive] = 'REPLACE' else copy_opts[:metadata_directive] = 'COPY' end copy_opts[:acl] = [:acl] if [:acl] copy_opts[:version_id] = [:version_id] if [:version_id] if [:reduced_redundancy] copy_opts[:storage_class] = 'REDUCED_REDUNDANCY' else copy_opts[:storage_class] = 'STANDARD' end client.copy_object(copy_opts) nil end |
#copy_to(target, options = {}) ⇒ 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.
508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 |
# File 'lib/aws/s3/s3_object.rb', line 508 def copy_to target, = {} unless target.is_a?(S3Object) bucket = case when [:bucket] then [:bucket] when [:bucket_name] Bucket.new([:bucket_name], :config => config) else self.bucket end target = S3Object.new(bucket, target) end copy_opts = .dup copy_opts.delete(:bucket) copy_opts.delete(:bucket_name) target.copy_from(self, copy_opts) end |
#delete(options = {}) ⇒ nil
Deletes the object from its S3 bucket.
141 142 143 144 145 146 |
# File 'lib/aws/s3/s3_object.rb', line 141 def delete = {} [:bucket_name] = bucket.name [:key] = key client.delete_object() nil end |
#etag ⇒ String
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.
110 111 112 |
# File 'lib/aws/s3/s3_object.rb', line 110 def etag head.etag end |
#exists? ⇒ Boolean
77 78 79 80 81 82 83 |
# File 'lib/aws/s3/s3_object.rb', line 77 def exists? head rescue Errors::NoSuchKey => e false else true end |
#head(options = {}) ⇒ Object
Performs a HEAD request against this object and returns an object with useful information about the object, including:
-
metadata (hash of user-supplied key-value pairs)
-
content_length (integer, number of bytes)
-
content_type (as sent to S3 when uploading the object)
-
etag (typically the object’s MD5)
98 99 100 101 |
# File 'lib/aws/s3/s3_object.rb', line 98 def head = {} client.head_object(.merge( :bucket_name => bucket.name, :key => key)) end |
#last_modified ⇒ Time
Returns the object’s last modified time.
117 118 119 |
# File 'lib/aws/s3/s3_object.rb', line 117 def last_modified head.last_modified end |
#metadata(options = {}) ⇒ ObjectMetadata
Returns an instance of ObjectMetadata representing the metadata for this object.
152 153 154 155 |
# File 'lib/aws/s3/s3_object.rb', line 152 def = {} [:config] = config ObjectMetadata.new(self, ) end |
#multipart_upload(options = {}) {|upload| ... } ⇒ S3Object, ObjectVersion
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.
377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 |
# File 'lib/aws/s3/s3_object.rb', line 377 def multipart_upload( = {}) upload = multipart_uploads.create() if block_given? result = nil begin yield(upload) ensure result = upload.close end result else upload end end |
#multipart_uploads ⇒ ObjectUploadCollection
Returns an object representing the collection of uploads that are in progress for this object.
399 400 401 |
# File 'lib/aws/s3/s3_object.rb', line 399 def multipart_uploads ObjectUploadCollection.new(self) end |
#presigned_post(options = {}) ⇒ PresignedPost
Generates fields for a presigned POST to this object. This method adds a constraint that the key must match the key of this object. All options are sent to the PresignedPost constructor.
722 723 724 |
# File 'lib/aws/s3/s3_object.rb', line 722 def presigned_post( = {}) PresignedPost.new(bucket, .merge(:key => key)) end |
#public_url(options = {}) ⇒ URI::HTTP, URI::HTTPS
Generates a public (not authenticated) URL for the object.
710 711 712 713 |
# File 'lib/aws/s3/s3_object.rb', line 710 def public_url( = {}) req = request_for_signing() build_uri([:secure] != false, req) end |
#read(options = {}, &blk) ⇒ Object
Fetches the object data from S3.
559 560 561 562 563 |
# File 'lib/aws/s3/s3_object.rb', line 559 def read( = {}, &blk) [:bucket_name] = bucket.name [:key] = key client.get_object().data end |
#reduced_redundancy=(value) ⇒ true, false
Changing the storage class of an object incurs a COPY operation.
Changes the storage class of the object to enable or disable Reduced Redundancy Storage (RRS).
738 739 740 741 |
# File 'lib/aws/s3/s3_object.rb', line 738 def reduced_redundancy= value copy_from(key, :reduced_redundancy => value) value end |
#url_for(method, options = {}) ⇒ URI::HTTP, URI::HTTPS
Generates a presigned URL for an operation on this object. This URL can be used by a regular HTTP client to perform the desired operation without credentials and without changing the permissions of the object.
691 692 693 694 695 696 697 698 699 700 701 |
# File 'lib/aws/s3/s3_object.rb', line 691 def url_for(method, = {}) req = request_for_signing() method = http_method(method) expires = ([:expires]) req.add_param("AWSAccessKeyId", config.signer.access_key_id) req.add_param("Signature", signature(method, expires, req)) req.add_param("Expires", expires) build_uri([:secure] != false, req) end |
#versions ⇒ ObjectVersionCollection
Returns a colletion representing all the object versions for this object.
bucket.versioning_enabled? # => true
version = bucket.objects["mykey"].versions.latest
164 165 166 |
# File 'lib/aws/s3/s3_object.rb', line 164 def versions ObjectVersionCollection.new(self) end |
#write(options = {}) ⇒ S3Object, ObjectVersion #write(data, options = {}) ⇒ S3Object, ObjectVersion
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" })
272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 |
# File 'lib/aws/s3/s3_object.rb', line 272 def write( = nil, = nil) (, ) = (, ) if use_multipart?(, ) .delete(:multipart_threshold) multipart_upload() do |upload| each_part(, ) do |part| upload.add_part(part) end end else opts = { :bucket_name => bucket.name, :key => key } resp = client.put_object(opts.merge().merge()) if resp.version_id ObjectVersion.new(self, resp.version_id) else self end end end |