Class: Aws::S3::Object
- Inherits:
-
Object
- Object
- Aws::S3::Object
- Defined in:
- gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb,
gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb
Defined Under Namespace
Classes: Collection
Read-Only Attributes collapse
-
#accept_ranges ⇒ String
Indicates that a range of bytes was specified.
-
#archive_status ⇒ String
The archive state of the head object.
-
#bucket_key_enabled ⇒ Boolean
Indicates whether the object uses an S3 Bucket Key for server-side encryption with AWS KMS (SSE-KMS).
-
#bucket_name ⇒ String
-
#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
(also: #size)
Size of the body in bytes.
-
#content_type ⇒ String
A standard MIME type describing the format of the object data.
-
#delete_marker ⇒ Boolean
Specifies whether the object retrieved was (true) or was not (false) a Delete Marker.
-
#etag ⇒ String
An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL.
-
#expiration ⇒ String
If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header.
-
#expires ⇒ Time
The date and time at which the object is no longer cacheable.
-
#expires_string ⇒ String
-
#key ⇒ String
-
#last_modified ⇒ Time
Last modified date of the object.
-
#metadata ⇒ Hash<String,String>
A map of metadata to store with the object in S3.
-
#missing_meta ⇒ Integer
This is set to the number of metadata entries not returned in
x-amz-meta
headers. -
#object_lock_legal_hold_status ⇒ String
Specifies whether a legal hold is in effect for this object.
-
#object_lock_mode ⇒ String
The Object Lock mode, if any, that's in effect for this object.
-
#object_lock_retain_until_date ⇒ Time
The date and time when the Object Lock retention period expires.
-
#parts_count ⇒ Integer
The count of parts this object has.
-
#replication_status ⇒ String
Amazon S3 can return this header if your request involves a bucket that is either a source or a destination in a replication rule.
-
#request_charged ⇒ String
If present, indicates that the requester was successfully charged for the request.
-
#restore ⇒ String
If the object is an archived object (an object whose storage class is GLACIER), the response includes this header if either the archive restoration is in progress (see [RestoreObject][1] or an archive copy is already restored.
-
#server_side_encryption ⇒ String
If the object is stored using server-side encryption either with an AWS KMS customer master key (CMK) or an Amazon S3-managed encryption key, the response includes this header with the value of the server-side encryption algorithm used when storing this object in Amazon S3 (for example, AES256, aws:kms).
-
#sse_customer_algorithm ⇒ 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_md5 ⇒ 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_id ⇒ String
If present, specifies the ID of the AWS Key Management Service (AWS KMS) symmetric customer managed customer master key (CMK) that was used for the object.
-
#storage_class ⇒ String
Provides storage class information of the object.
-
#version_id ⇒ String
Version of the object.
-
#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.
Actions collapse
-
#copy_from(source, options = {}) ⇒ Object
Copies another object to this object.
-
#delete(options = {}) ⇒ Types::DeleteObjectOutput
-
#get(options = {}, &block) ⇒ Types::GetObjectOutput
-
#initiate_multipart_upload(options = {}) ⇒ MultipartUpload
-
#put(options = {}) ⇒ Types::PutObjectOutput
-
#restore_object(options = {}) ⇒ Types::RestoreObjectOutput
Associations collapse
-
#acl ⇒ ObjectAcl
-
#bucket ⇒ Bucket
-
#multipart_upload(id) ⇒ MultipartUpload
-
#version(id) ⇒ ObjectVersion
Instance Method Summary collapse
-
#client ⇒ Client
-
#copy_to(target, options = {}) ⇒ Object
Copies this object to another object.
-
#data ⇒ Types::HeadObjectOutput
Returns the data for this Object.
-
#data_loaded? ⇒ Boolean
Returns
true
if this resource is loaded. -
#download_file(destination, options = {}) ⇒ Boolean
Downloads a file in S3 to a path on disk.
-
#exists?(options = {}) ⇒ Boolean
Returns
true
if the Object exists. -
#initialize(*args) ⇒ Object
constructor
A new instance of Object.
- #load ⇒ self (also: #reload)
-
#move_to(target, options = {}) ⇒ void
Copies and deletes the current object.
-
#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.
-
#presigned_url(http_method, params = {}) ⇒ String
Generates a pre-signed URL for this object.
-
#public_url(options = {}) ⇒ String
Returns the public (un-signed) URL for this object.
-
#upload_file(source, options = {}) {|response| ... } ⇒ Boolean
Uploads a file from disk to the current object in S3.
-
#upload_stream(options = {}, &block) ⇒ Boolean
Uploads a stream in a streaming fashion to the current object in S3.
-
#wait_until(options = {}) {|resource| ... } ⇒ Resource
deprecated
Deprecated.
Use [Aws::S3::Client] #wait_until instead
-
#wait_until_exists(options = {}, &block) ⇒ Object
-
#wait_until_not_exists(options = {}, &block) ⇒ Object
Constructor Details
#initialize(bucket_name, key, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object
Returns a new instance of Object.
24 25 26 27 28 29 30 31 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 24 def initialize(*args) = Hash === args.last ? args.pop.dup : {} @bucket_name = extract_bucket_name(args, ) @key = extract_key(args, ) @data = .delete(:data) @client = .delete(:client) || Client.new() @waiter_block_warned = false end |
Instance Method Details
#accept_ranges ⇒ String
Indicates that a range of bytes was specified.
55 56 57 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 55 def accept_ranges data[:accept_ranges] end |
#acl ⇒ ObjectAcl
1454 1455 1456 1457 1458 1459 1460 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1454 def acl ObjectAcl.new( bucket_name: @bucket_name, object_key: @key, client: @client ) end |
#archive_status ⇒ String
The archive state of the head object.
96 97 98 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 96 def archive_status data[:archive_status] end |
#bucket ⇒ Bucket
1463 1464 1465 1466 1467 1468 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1463 def bucket Bucket.new( name: @bucket_name, client: @client ) end |
#bucket_key_enabled ⇒ Boolean
Indicates whether the object uses an S3 Bucket Key for server-side encryption with AWS KMS (SSE-KMS).
230 231 232 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 230 def bucket_key_enabled data[:bucket_key_enabled] end |
#bucket_name ⇒ String
36 37 38 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 36 def bucket_name @bucket_name end |
#cache_control ⇒ String
Specifies caching behavior along the request/reply chain.
137 138 139 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 137 def cache_control data[:cache_control] end |
#client ⇒ Client
344 345 346 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 344 def client @client end |
#content_disposition ⇒ String
Specifies presentational information for the object.
143 144 145 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 143 def content_disposition data[:content_disposition] end |
#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.
151 152 153 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 151 def content_encoding data[:content_encoding] end |
#content_language ⇒ String
The language the content is in.
157 158 159 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 157 def content_language data[:content_language] end |
#content_length ⇒ Integer Also known as: size
Size of the body in bytes.
108 109 110 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 108 def content_length data[:content_length] end |
#content_type ⇒ String
A standard MIME type describing the format of the object data.
163 164 165 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 163 def content_type data[:content_type] end |
#copy_from(source, options = {}) ⇒ Object
Copies another object to this object. Use multipart_copy: true
for large objects. This is required for objects that exceed 5GB.
768 769 770 771 772 773 774 775 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 768 def copy_from( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = @client.copy_object() resp.data end |
#copy_to(target, options = {}) ⇒ Object
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.
108 109 110 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 108 def copy_to(target, = {}) ObjectCopier.new(self, ).copy_to(target, ) end |
#data ⇒ Types::HeadObjectOutput
Returns the data for this Aws::S3::Object. Calls
Client#head_object if #data_loaded? is false
.
367 368 369 370 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 367 def data load unless @data @data end |
#data_loaded? ⇒ Boolean
375 376 377 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 375 def data_loaded? !!@data end |
#delete(options = {}) ⇒ Types::DeleteObjectOutput
812 813 814 815 816 817 818 819 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 812 def delete( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = @client.delete_object() resp.data end |
#delete_marker ⇒ Boolean
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.
49 50 51 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 49 def delete_marker data[:delete_marker] end |
#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')
380 381 382 383 384 385 386 387 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 380 def download_file(destination, = {}) downloader = FileDownloader.new(client: client) downloader.download( destination, .merge(bucket: bucket_name, key: key) ) true end |
#etag ⇒ String
An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL.
115 116 117 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 115 def etag data[:etag] end |
#exists?(options = {}) ⇒ Boolean
Returns true
if the Object exists.
382 383 384 385 386 387 388 389 390 391 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 382 def exists?( = {}) begin wait_until_exists(.merge(max_attempts: 1)) true rescue Aws::Waiters::Errors::UnexpectedError => e raise e.error rescue Aws::Waiters::Errors::WaiterFailed false end end |
#expiration ⇒ String
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.
64 65 66 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 64 def expiration data[:expiration] end |
#expires ⇒ Time
The date and time at which the object is no longer cacheable.
169 170 171 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 169 def expires data[:expires] end |
#expires_string ⇒ String
174 175 176 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 174 def expires_string data[:expires_string] end |
#get(options = {}, &block) ⇒ Types::GetObjectOutput
916 917 918 919 920 921 922 923 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 916 def get( = {}, &block) = .merge( bucket: @bucket_name, key: @key ) resp = @client.get_object(, &block) resp.data end |
#initiate_multipart_upload(options = {}) ⇒ MultipartUpload
1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1076 def initiate_multipart_upload( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = @client.create_multipart_upload() MultipartUpload.new( bucket_name: @bucket_name, object_key: @key, id: resp.data.upload_id, client: @client ) end |
#key ⇒ String
41 42 43 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 41 def key @key end |
#last_modified ⇒ Time
Last modified date of the object
102 103 104 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 102 def last_modified data[:last_modified] end |
#load ⇒ self Also known as: reload
Loads, or reloads #data for the current Aws::S3::Object.
Returns self
making it possible to chain methods.
object.reload.data
354 355 356 357 358 359 360 361 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 354 def load resp = @client.head_object( bucket: @bucket_name, key: @key ) @data = resp.data self end |
#metadata ⇒ Hash<String,String>
A map of metadata to store with the object in S3.
198 199 200 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 198 def data[:metadata] end |
#missing_meta ⇒ Integer
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.
125 126 127 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 125 def data[:missing_meta] end |
#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.
120 121 122 123 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 120 def move_to(target, = {}) copy_to(target, ) delete end |
#multipart_upload(id) ⇒ MultipartUpload
1472 1473 1474 1475 1476 1477 1478 1479 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1472 def multipart_upload(id) MultipartUpload.new( bucket_name: @bucket_name, object_key: @key, id: id, client: @client ) end |
#object_lock_legal_hold_status ⇒ String
Specifies whether a legal hold is in effect for this object. This
header is only returned if the requester has the
s3:GetObjectLegalHold
permission. This header is not returned if the
specified version of this object has never had a legal hold applied.
For more information about S3 Object Lock, see Object Lock.
337 338 339 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 337 def object_lock_legal_hold_status data[:object_lock_legal_hold_status] end |
#object_lock_mode ⇒ String
The Object Lock mode, if any, that's in effect for this object. This
header is only returned if the requester has the
s3:GetObjectRetention
permission. For more information about S3
Object Lock, see Object Lock.
315 316 317 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 315 def object_lock_mode data[:object_lock_mode] end |
#object_lock_retain_until_date ⇒ Time
The date and time when the Object Lock retention period expires. This
header is only returned if the requester has the
s3:GetObjectRetention
permission.
323 324 325 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 323 def object_lock_retain_until_date data[:object_lock_retain_until_date] end |
#parts_count ⇒ Integer
The count of parts this object has.
302 303 304 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 302 def parts_count data[:parts_count] end |
#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.
134 135 136 137 138 139 140 141 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 134 def presigned_post( = {}) PresignedPost.new( client.config.credentials, client.config.region, bucket_name, { key: key, url: bucket.url }.merge() ) end |
#presigned_url(http_method, params = {}) ⇒ String
Generates a pre-signed URL for this object.
191 192 193 194 195 196 197 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 191 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"
215 216 217 218 219 220 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 215 def public_url( = {}) url = URI.parse(bucket.url()) url.path += '/' unless url.path[-1] == '/' url.path += key.gsub(/[^\/]+/) { |s| Seahorse::Util.uri_escape(s) } url.to_s end |
#put(options = {}) ⇒ Types::PutObjectOutput
1325 1326 1327 1328 1329 1330 1331 1332 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1325 def put( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = @client.put_object() resp.data end |
#replication_status ⇒ String
Amazon S3 can return this header if your request involves a bucket that is either a source or a destination in a replication rule.
In replication, you have a source bucket on which you configure
replication and destination bucket or buckets where Amazon S3 stores
object replicas. When you request an object (GetObject
) or object
metadata (HeadObject
) from these buckets, Amazon S3 will return the
x-amz-replication-status
header in the response as follows:
If requesting an object from the source bucket — Amazon S3 will return the
x-amz-replication-status
header if the object in your request is eligible for replication.For example, suppose that in your replication configuration, you specify object prefix
TaxDocs
requesting Amazon S3 to replicate objects with key prefixTaxDocs
. Any objects you upload with this key name prefix, for exampleTaxDocs/document1.pdf
, are eligible for replication. For any object request with this key name prefix, Amazon S3 will return thex-amz-replication-status
header with value PENDING, COMPLETED or FAILED indicating object replication status.If requesting an object from a destination bucket — Amazon S3 will return the
x-amz-replication-status
header with value REPLICA if the object in your request is a replica that Amazon S3 created and there is no replica modification replication in progress.When replicating objects to multiple destination buckets the
x-amz-replication-status
header acts differently. The header of the source object will only return a value of COMPLETED when replication is successful to all destinations. The header will remain at value PENDING until replication has completed for all destinations. If one or more destinations fails replication the header will return FAILED.
For more information, see Replication.
296 297 298 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 296 def replication_status data[:replication_status] end |
#request_charged ⇒ String
If present, indicates that the requester was successfully charged for the request.
251 252 253 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 251 def request_charged data[:request_charged] end |
#restore ⇒ String
If the object is an archived object (an object whose storage class is GLACIER), the response includes this header if either the archive restoration is in progress (see RestoreObject or an archive copy is already restored.
If an archive copy is already restored, the header value indicates when Amazon S3 is scheduled to delete the object copy. For example:
x-amz-restore: ongoing-request="false", expiry-date="Fri, 23 Dec 2012
00:00:00 GMT"
If the object restoration is in progress, the header returns the value
ongoing-request="true"
.
For more information about archiving objects, see Transitioning Objects: General Considerations.
90 91 92 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 90 def restore data[:restore] end |
#restore_object(options = {}) ⇒ Types::RestoreObjectOutput
1442 1443 1444 1445 1446 1447 1448 1449 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1442 def restore_object( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = @client.restore_object() resp.data end |
#server_side_encryption ⇒ String
If the object is stored using server-side encryption either with an AWS KMS customer master key (CMK) or an Amazon S3-managed encryption key, the response includes this header with the value of the server-side encryption algorithm used when storing this object in Amazon S3 (for example, AES256, aws:kms).
192 193 194 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 192 def server_side_encryption data[:server_side_encryption] end |
#sse_customer_algorithm ⇒ String
If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
206 207 208 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 206 def sse_customer_algorithm data[:sse_customer_algorithm] end |
#sse_customer_key_md5 ⇒ 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.
215 216 217 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 215 def sse_customer_key_md5 data[:sse_customer_key_md5] end |
#ssekms_key_id ⇒ String
If present, specifies the ID of the AWS Key Management Service (AWS KMS) symmetric customer managed customer master key (CMK) that was used for the object.
223 224 225 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 223 def ssekms_key_id data[:ssekms_key_id] end |
#storage_class ⇒ String
Provides storage class information of the object. Amazon S3 returns this header for all objects except for S3 Standard storage class objects.
For more information, see Storage Classes.
244 245 246 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 244 def storage_class data[:storage_class] end |
#upload_file(source, options = {}) {|response| ... } ⇒ 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 or equal to :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')
The response of the S3 upload API is yielded if a block given.
# API response will have etag value of the file
obj.upload_file('/path/to/file') do |response|
etag = response.etag
end
You can provide a callback to monitor progress of the upload:
# bytes and totals are each an array with 1 entry per part
progress = Proc.new do |bytes, totals|
puts bytes.map.with_index { |b, i| "Part #{i+1}: #{b} / #{totals[i]}"}.join(' ') + "Total: #{100.0 * bytes.sum / totals.sum }%" }
end
obj.upload_file('/path/to/file')
336 337 338 339 340 341 342 343 344 345 346 347 348 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 336 def upload_file(source, = {}) = .dup uploader = FileUploader.new( multipart_threshold: .delete(:multipart_threshold), client: client ) response = uploader.upload( source, .merge(bucket: bucket_name, key: key) ) yield response if block_given? true end |
#upload_stream(options = {}, &block) ⇒ Boolean
Uploads a stream in a streaming fashion to the current object in S3.
Passed chunks automatically split into multipart upload parts and the parts are uploaded in parallel. This allows for streaming uploads that never touch the disk.
Note that this is known to have issues in JRuby until jruby-9.1.15.0, so avoid using this with older versions of JRuby.
265 266 267 268 269 270 271 272 273 274 275 276 277 278 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 265 def upload_stream( = {}, &block) = .dup uploader = MultipartStreamUploader.new( client: client, thread_count: .delete(:thread_count), tempfile: .delete(:tempfile), part_size: .delete(:part_size) ) uploader.upload( .merge(bucket: bucket_name, key: key), &block ) true end |
#version(id) ⇒ ObjectVersion
1483 1484 1485 1486 1487 1488 1489 1490 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1483 def version(id) ObjectVersion.new( bucket_name: @bucket_name, object_key: @key, id: id, client: @client ) end |
#version_id ⇒ String
Version of the object.
131 132 133 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 131 def version_id data[:version_id] end |
#wait_until(options = {}) {|resource| ... } ⇒ Resource
Use [Aws::S3::Client] #wait_until instead
The waiting operation is performed on a copy. The original resource remains unchanged.
Waiter polls an API operation until a resource enters a desired state.
Basic Usage
Waiter will polls until it is successful, it fails by entering a terminal state, or until a maximum number of attempts are made.
# polls in a loop until condition is true
resource.wait_until() {|resource| condition}
Example
instance.wait_until(max_attempts:10, delay:5) do |instance|
instance.state.name == 'running'
end
Configuration
You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. The waiting condition is set by passing a block to #wait_until:
# poll for ~25 seconds
resource.wait_until(max_attempts:5,delay:5) {|resource|...}
Callbacks
You can be notified before each polling attempt and before each
delay. If you throw :success
or :failure
from these callbacks,
it will terminate the waiter.
started_at = Time.now
# poll for 1 hour, instead of a number of attempts
proc = Proc.new do |attempts, response|
throw :failure if Time.now - started_at > 3600
end
# disable max attempts
instance.wait_until(before_wait:proc, max_attempts:nil) {...}
Handling Errors
When a waiter is successful, it returns the Resource. When a waiter fails, it raises an error.
begin
resource.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
# resource did not enter the desired state in time
end
attempts attempt in seconds invoked before each attempt invoked before each wait
511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 511 def wait_until( = {}, &block) self_copy = self.dup attempts = 0 [:max_attempts] = 10 unless .key?(:max_attempts) [:delay] ||= 10 [:poller] = Proc.new do attempts += 1 if block.call(self_copy) [:success, self_copy] else self_copy.reload unless attempts == [:max_attempts] :retry end end Aws::Waiters::Waiter.new().wait({}) end |
#wait_until_exists(options = {}, &block) ⇒ Object
399 400 401 402 403 404 405 406 407 408 409 410 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 399 def wait_until_exists( = {}, &block) , params = () waiter = Waiters::ObjectExists.new() yield_waiter_and_warn(waiter, &block) if block_given? waiter.wait(params.merge(bucket: @bucket_name, key: @key)) Object.new({ bucket_name: @bucket_name, key: @key, client: @client }) end |
#wait_until_not_exists(options = {}, &block) ⇒ Object
418 419 420 421 422 423 424 425 426 427 428 429 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 418 def wait_until_not_exists( = {}, &block) , params = () waiter = Waiters::ObjectNotExists.new() yield_waiter_and_warn(waiter, &block) if block_given? waiter.wait(params.merge(bucket: @bucket_name, key: @key)) Object.new({ bucket_name: @bucket_name, key: @key, client: @client }) end |
#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.
182 183 184 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 182 def website_redirect_location data[:website_redirect_location] end |