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) ⇒ Response
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 = {}) ⇒ Response
Deletes the object from its S3 bucket.
-
#etag ⇒ String
Returns the object’s ETag.
-
#head(options = {}) ⇒ Response
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.
-
#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.
-
#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.
537 538 539 540 541 542 543 544 545 |
# File 'lib/aws/s3/s3_object.rb', line 537 def acl acl = client.get_object_acl( :bucket_name => bucket.name, :key => key ).acl acl.extend ACLProxy acl.object = self acl end |
#acl=(acl) ⇒ Response
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.
557 558 559 560 561 562 |
# File 'lib/aws/s3/s3_object.rb', line 557 def acl=(acl) client.set_object_acl( :bucket_name => bucket.name, :key => key, :acl => acl) end |
#content_length ⇒ Integer
Returns Size of the object in bytes.
107 108 109 |
# File 'lib/aws/s3/s3_object.rb', line 107 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.
115 116 117 |
# File 'lib/aws/s3/s3_object.rb', line 115 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.
403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 |
# File 'lib/aws/s3/s3_object.rb', line 403 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[:version_id] = [:version_id] if [:version_id] copy_opts[:storage_class] = 'REDUCED_REDUNDANCY' if [:reduced_redundancy] 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.
458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 |
# File 'lib/aws/s3/s3_object.rb', line 458 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 = {}) ⇒ Response
Deletes the object from its S3 bucket.
126 127 128 129 130 |
# File 'lib/aws/s3/s3_object.rb', line 126 def delete = {} [:bucket_name] = bucket.name [:key] = key client.delete_object() 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.
102 103 104 |
# File 'lib/aws/s3/s3_object.rb', line 102 def etag head.etag end |
#head(options = {}) ⇒ Response
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)
90 91 92 93 |
# File 'lib/aws/s3/s3_object.rb', line 90 def head = {} client.head_object(.merge( :bucket_name => bucket.name, :key => key)) end |
#metadata(options = {}) ⇒ ObjectMetadata
Returns an instance of ObjectMetadata representing the metadata for this object.
136 137 138 139 |
# File 'lib/aws/s3/s3_object.rb', line 136 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.
357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 |
# File 'lib/aws/s3/s3_object.rb', line 357 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.
379 380 381 |
# File 'lib/aws/s3/s3_object.rb', line 379 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.
662 663 664 |
# File 'lib/aws/s3/s3_object.rb', line 662 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.
650 651 652 653 |
# File 'lib/aws/s3/s3_object.rb', line 650 def public_url( = {}) req = request_for_signing() build_uri([:secure] != false, req) end |
#read(options = {}, &blk) ⇒ Object
Fetches the object data from S3.
499 500 501 502 503 |
# File 'lib/aws/s3/s3_object.rb', line 499 def read( = {}, &blk) [:bucket_name] = bucket.name [:key] = key client.get_object().data 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.
631 632 633 634 635 636 637 638 639 640 641 |
# File 'lib/aws/s3/s3_object.rb', line 631 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
148 149 150 |
# File 'lib/aws/s3/s3_object.rb', line 148 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" })
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 |
# File 'lib/aws/s3/s3_object.rb', line 254 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 |