Class: Aws::S3::Object
- Inherits:
-
Object
- Object
- Aws::S3::Object
- Extended by:
- Deprecations
- Defined in:
- lib/aws-sdk-s3/customizations/object.rb,
lib/aws-sdk-s3/object.rb
Defined Under Namespace
Classes: Collection
Read-Only Attributes collapse
-
#accept_ranges ⇒ String
Indicates that a range of bytes was specified.
- #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
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 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 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(options = {}) ⇒ Types::CopyObjectOutput
- #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
- #identifiers ⇒ Object deprecated private Deprecated.
- #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.
- #size ⇒ 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.
22 23 24 25 26 27 28 29 |
# File 'lib/aws-sdk-s3/object.rb', line 22 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.
53 54 55 |
# File 'lib/aws-sdk-s3/object.rb', line 53 def accept_ranges data[:accept_ranges] end |
#acl ⇒ ObjectAcl
1259 1260 1261 1262 1263 1264 1265 |
# File 'lib/aws-sdk-s3/object.rb', line 1259 def acl ObjectAcl.new( bucket_name: @bucket_name, object_key: @key, client: @client ) end |
#bucket ⇒ Bucket
1268 1269 1270 1271 1272 1273 |
# File 'lib/aws-sdk-s3/object.rb', line 1268 def bucket Bucket.new( name: @bucket_name, client: @client ) end |
#bucket_name ⇒ String
34 35 36 |
# File 'lib/aws-sdk-s3/object.rb', line 34 def bucket_name @bucket_name end |
#cache_control ⇒ String
Specifies caching behavior along the request/reply chain.
128 129 130 |
# File 'lib/aws-sdk-s3/object.rb', line 128 def cache_control data[:cache_control] end |
#content_disposition ⇒ String
Specifies presentational information for the object.
134 135 136 |
# File 'lib/aws-sdk-s3/object.rb', line 134 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.
142 143 144 |
# File 'lib/aws-sdk-s3/object.rb', line 142 def content_encoding data[:content_encoding] end |
#content_language ⇒ String
The language the content is in.
148 149 150 |
# File 'lib/aws-sdk-s3/object.rb', line 148 def content_language data[:content_language] end |
#content_length ⇒ Integer
Size of the body in bytes.
99 100 101 |
# File 'lib/aws-sdk-s3/object.rb', line 99 def content_length data[:content_length] end |
#content_type ⇒ String
A standard MIME type describing the format of the object data.
154 155 156 |
# File 'lib/aws-sdk-s3/object.rb', line 154 def content_type data[:content_type] end |
#copy_from(options = {}) ⇒ Types::CopyObjectOutput
62 63 64 65 66 67 68 69 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 62 def copy_from(source, = {}) if Hash === source && source[:copy_source] # for backwards compatibility @client.copy_object(source.merge(bucket: bucket_name, key: key)) else ObjectCopier.new(self, ).copy_from(source, ) end 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.
103 104 105 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 103 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`.
341 342 343 344 |
# File 'lib/aws-sdk-s3/object.rb', line 341 def data load unless @data @data end |
#data_loaded? ⇒ Boolean
349 350 351 |
# File 'lib/aws-sdk-s3/object.rb', line 349 def data_loaded? !!@data end |
#delete(options = {}) ⇒ Types::DeleteObjectOutput
701 702 703 704 705 706 707 708 |
# File 'lib/aws-sdk-s3/object.rb', line 701 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.
47 48 49 |
# File 'lib/aws-sdk-s3/object.rb', line 47 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')
363 364 365 366 367 368 369 370 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 363 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.
106 107 108 |
# File 'lib/aws-sdk-s3/object.rb', line 106 def etag data[:etag] end |
#exists?(options = {}) ⇒ Boolean
Returns ‘true` if the Object exists.
356 357 358 359 360 361 362 363 364 365 |
# File 'lib/aws-sdk-s3/object.rb', line 356 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.
62 63 64 |
# File 'lib/aws-sdk-s3/object.rb', line 62 def expiration data[:expiration] end |
#expires ⇒ Time
The date and time at which the object is no longer cacheable.
160 161 162 |
# File 'lib/aws-sdk-s3/object.rb', line 160 def expires data[:expires] end |
#expires_string ⇒ String
165 166 167 |
# File 'lib/aws-sdk-s3/object.rb', line 165 def expires_string data[:expires_string] end |
#get(options = {}, &block) ⇒ Types::GetObjectOutput
791 792 793 794 795 796 797 798 |
# File 'lib/aws-sdk-s3/object.rb', line 791 def get( = {}, &block) = .merge( bucket: @bucket_name, key: @key ) resp = @client.get_object(, &block) resp.data end |
#identifiers ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
1299 1300 1301 1302 1303 1304 |
# File 'lib/aws-sdk-s3/object.rb', line 1299 def identifiers { bucket_name: @bucket_name, key: @key } end |
#initiate_multipart_upload(options = {}) ⇒ MultipartUpload
918 919 920 921 922 923 924 925 926 927 928 929 930 |
# File 'lib/aws-sdk-s3/object.rb', line 918 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
39 40 41 |
# File 'lib/aws-sdk-s3/object.rb', line 39 def key @key end |
#last_modified ⇒ Time
Last modified date of the object
93 94 95 |
# File 'lib/aws-sdk-s3/object.rb', line 93 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
328 329 330 331 332 333 334 335 |
# File 'lib/aws-sdk-s3/object.rb', line 328 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.
189 190 191 |
# File 'lib/aws-sdk-s3/object.rb', line 189 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.
116 117 118 |
# File 'lib/aws-sdk-s3/object.rb', line 116 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.
115 116 117 118 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 115 def move_to(target, = {}) copy_to(target, ) delete end |
#multipart_upload(id) ⇒ MultipartUpload
1277 1278 1279 1280 1281 1282 1283 1284 |
# File 'lib/aws-sdk-s3/object.rb', line 1277 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].
[1]: docs.aws.amazon.com/AmazonS3/latest/dev/object-lock.html
311 312 313 |
# File 'lib/aws-sdk-s3/object.rb', line 311 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].
[1]: docs.aws.amazon.com/AmazonS3/latest/dev/object-lock.html
289 290 291 |
# File 'lib/aws-sdk-s3/object.rb', line 289 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.
297 298 299 |
# File 'lib/aws-sdk-s3/object.rb', line 297 def object_lock_retain_until_date data[:object_lock_retain_until_date] end |
#parts_count ⇒ Integer
The count of parts this object has.
276 277 278 |
# File 'lib/aws-sdk-s3/object.rb', line 276 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.
129 130 131 132 133 134 135 136 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 129 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.
186 187 188 189 190 191 192 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 186 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"
210 211 212 213 214 215 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 210 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
1135 1136 1137 1138 1139 1140 1141 1142 |
# File 'lib/aws-sdk-s3/object.rb', line 1135 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 destination in a replication rule.
In replication, you have a source bucket on which you configure replication and destination bucket 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 prefix `TaxDocs`. Any objects you upload with this key name prefix, for example `TaxDocs/document1.pdf`, are eligible for replication. For any object request with this key name prefix, Amazon S3 will return the `x-amz-replication-status` header with value PENDING, COMPLETED or FAILED indicating object replication status.
-
If requesting an object from the 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.
For more information, see [Replication].
[1]: docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html
270 271 272 |
# File 'lib/aws-sdk-s3/object.rb', line 270 def replication_status data[:replication_status] end |
#request_charged ⇒ String
If present, indicates that the requester was successfully charged for the request.
234 235 236 |
# File 'lib/aws-sdk-s3/object.rb', line 234 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].
87 88 89 |
# File 'lib/aws-sdk-s3/object.rb', line 87 def restore data[:restore] end |
#restore_object(options = {}) ⇒ Types::RestoreObjectOutput
1247 1248 1249 1250 1251 1252 1253 1254 |
# File 'lib/aws-sdk-s3/object.rb', line 1247 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).
183 184 185 |
# File 'lib/aws-sdk-s3/object.rb', line 183 def server_side_encryption data[:server_side_encryption] end |
#size ⇒ Object
4 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 4 alias size content_length |
#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.
197 198 199 |
# File 'lib/aws-sdk-s3/object.rb', line 197 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.
206 207 208 |
# File 'lib/aws-sdk-s3/object.rb', line 206 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.
214 215 216 |
# File 'lib/aws-sdk-s3/object.rb', line 214 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 Standard storage class objects.
For more information, see [Storage Classes].
[1]: docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html
227 228 229 |
# File 'lib/aws-sdk-s3/object.rb', line 227 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 ‘: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
319 320 321 322 323 324 325 326 327 328 329 330 331 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 319 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.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 260 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
1288 1289 1290 1291 1292 1293 1294 1295 |
# File 'lib/aws-sdk-s3/object.rb', line 1288 def version(id) ObjectVersion.new( bucket_name: @bucket_name, object_key: @key, id: id, client: @client ) end |
#version_id ⇒ String
Version of the object.
122 123 124 |
# File 'lib/aws-sdk-s3/object.rb', line 122 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
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 |
# File 'lib/aws-sdk-s3/object.rb', line 485 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
373 374 375 376 377 378 379 380 381 382 383 384 |
# File 'lib/aws-sdk-s3/object.rb', line 373 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
392 393 394 395 396 397 398 399 400 401 402 403 |
# File 'lib/aws-sdk-s3/object.rb', line 392 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.
173 174 175 |
# File 'lib/aws-sdk-s3/object.rb', line 173 def website_redirect_location data[:website_redirect_location] end |