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 Key Management Service (KMS) keys (SSE-KMS).
-
#bucket_name ⇒ String
-
#cache_control ⇒ String
Specifies caching behavior along the request/reply chain.
-
#checksum_crc32 ⇒ String
The Base64 encoded, 32-bit
CRC32 checksum
of the object. -
#checksum_crc32c ⇒ String
The Base64 encoded, 32-bit
CRC32C
checksum of the object. -
#checksum_crc64nvme ⇒ String
The Base64 encoded, 64-bit
CRC64NVME
checksum of the object. -
#checksum_sha1 ⇒ String
The Base64 encoded, 160-bit
SHA1
digest of the object. -
#checksum_sha256 ⇒ String
The Base64 encoded, 256-bit
SHA256
digest of the object. -
#checksum_type ⇒ String
The checksum type, which determines how part-level checksums are combined to create an object-level checksum for multipart objects.
-
#content_disposition ⇒ String
Specifies presentational information for the object.
-
#content_encoding ⇒ String
Indicates 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_range ⇒ String
The portion of the object returned in the response for a
GET
request. -
#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 entity tag (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 [
PutBucketLifecycleConfiguration
][1]), 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
Date and time when the object was last modified.
-
#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
The server-side encryption algorithm used when you store this object in Amazon S3 (for example,
AES256
,aws:kms
,aws:kms:dsse
). -
#sse_customer_algorithm ⇒ String
If server-side encryption with a customer-provided encryption key was requested, the response will include this header to confirm the encryption algorithm that's 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 the round-trip message integrity verification of the customer-provided encryption key.
-
#ssekms_key_id ⇒ String
If present, indicates the ID of the KMS key that was used for object encryption.
-
#storage_class ⇒ String
Provides storage class information of the object.
-
#version_id ⇒ String
Version ID 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
-
#head(options = {}) ⇒ Types::HeadObjectOutput
-
#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_request(method, params = {}) ⇒ String, Hash
Allows you to create presigned URL requests for S3 operations.
-
#presigned_url(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.
59 60 61 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 59 def accept_ranges data[:accept_ranges] end |
#acl ⇒ ObjectAcl
3342 3343 3344 3345 3346 3347 3348 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 3342 def acl ObjectAcl.new( bucket_name: @bucket_name, object_key: @key, client: @client ) end |
#archive_status ⇒ String
The archive state of the head object.
121 122 123 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 121 def archive_status data[:archive_status] end |
#bucket ⇒ Bucket
3351 3352 3353 3354 3355 3356 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 3351 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 Key Management Service (KMS) keys (SSE-KMS).
373 374 375 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 373 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.
265 266 267 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 265 def cache_control data[:cache_control] end |
#checksum_crc32 ⇒ String
The Base64 encoded, 32-bit CRC32 checksum
of the object. This
checksum is only be present if the checksum was uploaded with the
object. When you use an API operation on an object that was uploaded
using multipart uploads, this value may not be a direct checksum value
of the full object. Instead, it's a calculation based on the checksum
values of each individual part. For more information about how
checksums are calculated with multipart uploads, see Checking object
integrity in the Amazon S3 User Guide.
150 151 152 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 150 def checksum_crc32 data[:checksum_crc32] end |
#checksum_crc32c ⇒ String
The Base64 encoded, 32-bit CRC32C
checksum of the object. This
checksum is only present if the checksum was uploaded with the object.
When you use an API operation on an object that was uploaded using
multipart uploads, this value may not be a direct checksum value of
the full object. Instead, it's a calculation based on the checksum
values of each individual part. For more information about how
checksums are calculated with multipart uploads, see Checking object
integrity in the Amazon S3 User Guide.
167 168 169 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 167 def checksum_crc32c data[:checksum_crc32c] end |
#checksum_crc64nvme ⇒ String
The Base64 encoded, 64-bit CRC64NVME
checksum of the object. For
more information, see Checking object integrity in the Amazon S3 User
Guide.
179 180 181 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 179 def checksum_crc64nvme data[:checksum_crc64nvme] end |
#checksum_sha1 ⇒ String
The Base64 encoded, 160-bit SHA1
digest of the object. This will
only be present if the object was uploaded with the object. When you
use the API operation on an object that was uploaded using multipart
uploads, this value may not be a direct checksum value of the full
object. Instead, it's a calculation based on the checksum values of
each individual part. For more information about how checksums are
calculated with multipart uploads, see Checking object integrity
in the Amazon S3 User Guide.
196 197 198 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 196 def checksum_sha1 data[:checksum_sha1] end |
#checksum_sha256 ⇒ String
The Base64 encoded, 256-bit SHA256
digest of the object. This will
only be present if the object was uploaded with the object. When you
use an API operation on an object that was uploaded using multipart
uploads, this value may not be a direct checksum value of the full
object. Instead, it's a calculation based on the checksum values of
each individual part. For more information about how checksums are
calculated with multipart uploads, see Checking object integrity
in the Amazon S3 User Guide.
213 214 215 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 213 def checksum_sha256 data[:checksum_sha256] end |
#checksum_type ⇒ String
The checksum type, which determines how part-level checksums are
combined to create an object-level checksum for multipart objects. You
can use this header response to verify that the checksum type that is
received is the same checksum type that was specified in
CreateMultipartUpload
request. For more information, see Checking
object integrity in the Amazon S3 User Guide.
228 229 230 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 228 def checksum_type data[:checksum_type] end |
#client ⇒ Client
514 515 516 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 514 def client @client end |
#content_disposition ⇒ String
Specifies presentational information for the object.
271 272 273 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 271 def content_disposition data[:content_disposition] end |
#content_encoding ⇒ String
Indicates 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.
279 280 281 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 279 def content_encoding data[:content_encoding] end |
#content_language ⇒ String
The language the content is in.
285 286 287 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 285 def content_language data[:content_language] end |
#content_length ⇒ Integer Also known as: size
Size of the body in bytes.
133 134 135 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 133 def content_length data[:content_length] end |
#content_range ⇒ String
The portion of the object returned in the response for a GET
request.
298 299 300 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 298 def content_range data[:content_range] end |
#content_type ⇒ String
A standard MIME type describing the format of the object data.
291 292 293 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 291 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.
1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1427 def copy_from( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.copy_object() end 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.
121 122 123 124 125 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 121 def copy_to(target, = {}) Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do ObjectCopier.new(self, ).copy_to(target, ) end end |
#data ⇒ Types::HeadObjectOutput
Returns the data for this Aws::S3::Object. Calls
Client#head_object if #data_loaded? is false
.
539 540 541 542 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 539 def data load unless @data @data end |
#data_loaded? ⇒ Boolean
547 548 549 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 547 def data_loaded? !!@data end |
#delete(options = {}) ⇒ Types::DeleteObjectOutput
1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1536 def delete( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.delete_object() end 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.
53 54 55 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 53 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')
You can provide a callback to monitor progress of the download:
# bytes and part_sizes are each an array with 1 entry per part
# part_sizes may not be known until the first bytes are retrieved
progress = Proc.new do |bytes, part_sizes, file_size|
puts bytes.map.with_index { |b, i| "Part #{i+1}: #{b} / #{part_sizes[i]}"}.join(' ') + "Total: #{100.0 * bytes.sum / file_size}%" }
end
obj.download_file('/path/to/file', progress_callback: progress)
552 553 554 555 556 557 558 559 560 561 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 552 def download_file(destination, = {}) downloader = FileDownloader.new(client: client) Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do downloader.download( destination, .merge(bucket: bucket_name, key: key) ) end true end |
#etag ⇒ String
An entity tag (ETag) is an opaque identifier assigned by a web server to a specific version of a resource found at a URL.
235 236 237 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 235 def etag data[:etag] end |
#exists?(options = {}) ⇒ Boolean
Returns true
if the Object exists.
554 555 556 557 558 559 560 561 562 563 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 554 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
PutBucketLifecycleConfiguration
), 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.
NotImplemented
" in all responses
for directory buckets.
79 80 81 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 79 def expiration data[:expiration] end |
#expires ⇒ Time
The date and time at which the object is no longer cacheable.
304 305 306 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 304 def expires data[:expires] end |
#expires_string ⇒ String
309 310 311 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 309 def expires_string data[:expires_string] end |
#get(options = {}, &block) ⇒ Types::GetObjectOutput
1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 1792 def get( = {}, &block) = .merge( bucket: @bucket_name, key: @key ) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.get_object(, &block) end resp.data end |
#head(options = {}) ⇒ Types::HeadObjectOutput
3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 3328 def head( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.head_object() end resp.data end |
#initiate_multipart_upload(options = {}) ⇒ MultipartUpload
2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 2367 def initiate_multipart_upload( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.create_multipart_upload() end 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
Date and time when the object was last modified.
127 128 129 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 127 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
524 525 526 527 528 529 530 531 532 533 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 524 def load resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.head_object( bucket: @bucket_name, key: @key ) end @data = resp.data self end |
#metadata ⇒ Hash<String,String>
A map of metadata to store with the object in S3.
334 335 336 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 334 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.
249 250 251 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 249 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.
135 136 137 138 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 135 def move_to(target, = {}) copy_to(target, ) delete end |
#multipart_upload(id) ⇒ MultipartUpload
3360 3361 3362 3363 3364 3365 3366 3367 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 3360 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.
507 508 509 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 507 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.
477 478 479 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 477 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.
489 490 491 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 489 def object_lock_retain_until_date data[:object_lock_retain_until_date] end |
#parts_count ⇒ Integer
The count of parts this object has. This value is only returned if you
specify partNumber
in your request and the object was uploaded as a
multipart upload.
460 461 462 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 460 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.
149 150 151 152 153 154 155 156 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 149 def presigned_post( = {}) PresignedPost.new( client.config.credentials, client.config.region, bucket_name, { key: key, url: bucket.url }.merge() ) end |
#presigned_request(method, params = {}) ⇒ String, Hash
Allows you to create presigned URL requests for S3 operations. This method returns a tuple containing the URL and the signed X-amz-* headers to be used with the presigned url.
293 294 295 296 297 298 299 300 301 302 303 304 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 293 def presigned_request(method, params = {}) presigner = Presigner.new(client: client) if %w(delete head get put).include?(method.to_s) method = "#{method}_object".to_sym end presigner.presigned_request( method.downcase, params.merge(bucket: bucket_name, key: key) ) end |
#presigned_url(method, params = {}) ⇒ String
Generates a pre-signed URL for this object.
220 221 222 223 224 225 226 227 228 229 230 231 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 220 def presigned_url(method, params = {}) presigner = Presigner.new(client: client) if %w(delete head get put).include?(method.to_s) method = "#{method}_object".to_sym end presigner.presigned_url( method.downcase, 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. Uses https unless secure: false is set. If the bucket name contains dots (.) then you will need to set secure: false.
s3.bucket('my-bucket.com').object('key')
.public_url(virtual_host: true)
#=> "https://my-bucket.com/key"
328 329 330 331 332 333 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 328 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
2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 2988 def put( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.put_object() end 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.
452 453 454 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 452 def replication_status data[:replication_status] end |
#request_charged ⇒ String
If present, indicates that the requester was successfully charged for the request.
403 404 405 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 403 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, 21 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.
111 112 113 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 111 def restore data[:restore] end |
#restore_object(options = {}) ⇒ Types::RestoreObjectOutput
3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 3129 def restore_object( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.restore_object() end resp.data end |
#server_side_encryption ⇒ String
The server-side encryption algorithm used when you store this object
in Amazon S3 (for example, AES256
, aws:kms
, aws:kms:dsse
).
328 329 330 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 328 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 to confirm the encryption algorithm that's used.
346 347 348 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 346 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 the round-trip message integrity verification of the customer-provided encryption key.
359 360 361 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 359 def sse_customer_key_md5 data[:sse_customer_key_md5] end |
#ssekms_key_id ⇒ String
If present, indicates the ID of the KMS key that was used for object encryption.
366 367 368 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 366 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.
392 393 394 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 392 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', progress_callback: progress)
470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 470 def upload_file(source, = {}) = .dup uploader = FileUploader.new( multipart_threshold: .delete(:multipart_threshold), client: client ) response = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do uploader.upload( source, .merge(bucket: bucket_name, key: key) ) end 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.
385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/object.rb', line 385 def upload_stream( = {}, &block) = .dup uploader = MultipartStreamUploader.new( client: client, thread_count: .delete(:thread_count), tempfile: .delete(:tempfile), part_size: .delete(:part_size) ) Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do uploader.upload( .merge(bucket: bucket_name, key: key), &block ) end true end |
#version(id) ⇒ ObjectVersion
3371 3372 3373 3374 3375 3376 3377 3378 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 3371 def version(id) ObjectVersion.new( bucket_name: @bucket_name, object_key: @key, id: id, client: @client ) end |
#version_id ⇒ String
Version ID of the object.
259 260 261 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 259 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
687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 687 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::Plugins::UserAgent.metric('RESOURCE_MODEL') do Aws::Waiters::Waiter.new().wait({}) end end |
#wait_until_exists(options = {}, &block) ⇒ Object
571 572 573 574 575 576 577 578 579 580 581 582 583 584 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 571 def wait_until_exists( = {}, &block) , params = () waiter = Waiters::ObjectExists.new() yield_waiter_and_warn(waiter, &block) if block_given? Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do waiter.wait(params.merge(bucket: @bucket_name, key: @key)) end Object.new({ bucket_name: @bucket_name, key: @key, client: @client }) end |
#wait_until_not_exists(options = {}, &block) ⇒ Object
592 593 594 595 596 597 598 599 600 601 602 603 604 605 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 592 def wait_until_not_exists( = {}, &block) , params = () waiter = Waiters::ObjectNotExists.new() yield_waiter_and_warn(waiter, &block) if block_given? Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do waiter.wait(params.merge(bucket: @bucket_name, key: @key)) end 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.
321 322 323 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/object.rb', line 321 def website_redirect_location data[:website_redirect_location] end |