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
- #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.
-
#parts_count ⇒ Integer
The count of parts this object has.
- #replication_status ⇒ String
-
#request_charged ⇒ String
If present, indicates that the requester was successfully charged for the request.
-
#restore ⇒ String
Provides information about object restoration operation and expiration time of the restored object copy.
-
#server_side_encryption ⇒ String
The Server-side encryption algorithm used when storing this object in S3 (e.g., 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 (KMS) master encryption key that was used for the object.
- #storage_class ⇒ String
-
#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 = {}) ⇒ Boolean
Uploads a file from disk to the current object in S3.
-
#wait_until(options = {}, &block) ⇒ Resource
deprecated
Deprecated.
Use [Aws::S3::Client] #wait_until instead
- #wait_until_exists(options = {}) ⇒ Object
- #wait_until_not_exists(options = {}) ⇒ Object
Constructor Details
#initialize(bucket_name, key, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object
Returns a new instance of Object.
21 22 23 24 25 26 27 |
# File 'lib/aws-sdk-s3/object.rb', line 21 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() end |
Instance Method Details
#accept_ranges ⇒ String
50 51 52 |
# File 'lib/aws-sdk-s3/object.rb', line 50 def accept_ranges data[:accept_ranges] end |
#acl ⇒ ObjectAcl
987 988 989 990 991 992 993 |
# File 'lib/aws-sdk-s3/object.rb', line 987 def acl ObjectAcl.new( bucket_name: @bucket_name, object_key: @key, client: @client ) end |
#bucket ⇒ Bucket
996 997 998 999 1000 1001 |
# File 'lib/aws-sdk-s3/object.rb', line 996 def bucket Bucket.new( name: @bucket_name, client: @client ) end |
#bucket_name ⇒ String
32 33 34 |
# File 'lib/aws-sdk-s3/object.rb', line 32 def bucket_name @bucket_name end |
#cache_control ⇒ String
Specifies caching behavior along the request/reply chain.
107 108 109 |
# File 'lib/aws-sdk-s3/object.rb', line 107 def cache_control data[:cache_control] end |
#content_disposition ⇒ String
Specifies presentational information for the object.
113 114 115 |
# File 'lib/aws-sdk-s3/object.rb', line 113 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.
121 122 123 |
# File 'lib/aws-sdk-s3/object.rb', line 121 def content_encoding data[:content_encoding] end |
#content_language ⇒ String
The language the content is in.
127 128 129 |
# File 'lib/aws-sdk-s3/object.rb', line 127 def content_language data[:content_language] end |
#content_length ⇒ Integer
Size of the body in bytes.
78 79 80 |
# File 'lib/aws-sdk-s3/object.rb', line 78 def content_length data[:content_length] end |
#content_type ⇒ String
A standard MIME type describing the format of the object data.
133 134 135 |
# File 'lib/aws-sdk-s3/object.rb', line 133 def content_type data[:content_type] end |
#copy_from(options = {}) ⇒ Types::CopyObjectOutput
61 62 63 64 65 66 67 68 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 61 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.
102 103 104 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 102 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`.
242 243 244 245 |
# File 'lib/aws-sdk-s3/object.rb', line 242 def data load unless @data @data end |
#data_loaded? ⇒ Boolean
250 251 252 |
# File 'lib/aws-sdk-s3/object.rb', line 250 def data_loaded? !!@data end |
#delete(options = {}) ⇒ Types::DeleteObjectOutput
566 567 568 569 570 571 572 573 |
# File 'lib/aws-sdk-s3/object.rb', line 566 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.
45 46 47 |
# File 'lib/aws-sdk-s3/object.rb', line 45 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')
282 283 284 285 286 287 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 282 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
85 86 87 |
# File 'lib/aws-sdk-s3/object.rb', line 85 def etag data[:etag] end |
#exists?(options = {}) ⇒ Boolean
Returns ‘true` if the Object exists.
257 258 259 260 261 262 263 264 265 266 |
# File 'lib/aws-sdk-s3/object.rb', line 257 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.
59 60 61 |
# File 'lib/aws-sdk-s3/object.rb', line 59 def expiration data[:expiration] end |
#expires ⇒ Time
The date and time at which the object is no longer cacheable.
139 140 141 |
# File 'lib/aws-sdk-s3/object.rb', line 139 def expires data[:expires] end |
#expires_string ⇒ String
144 145 146 |
# File 'lib/aws-sdk-s3/object.rb', line 144 def expires_string data[:expires_string] end |
#get(options = {}, &block) ⇒ Types::GetObjectOutput
652 653 654 655 656 657 658 659 |
# File 'lib/aws-sdk-s3/object.rb', line 652 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.
1027 1028 1029 1030 1031 1032 |
# File 'lib/aws-sdk-s3/object.rb', line 1027 def identifiers { bucket_name: @bucket_name, key: @key } end |
#initiate_multipart_upload(options = {}) ⇒ MultipartUpload
754 755 756 757 758 759 760 761 762 763 764 765 766 |
# File 'lib/aws-sdk-s3/object.rb', line 754 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
37 38 39 |
# File 'lib/aws-sdk-s3/object.rb', line 37 def key @key end |
#last_modified ⇒ Time
Last modified date of the object
72 73 74 |
# File 'lib/aws-sdk-s3/object.rb', line 72 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
229 230 231 232 233 234 235 236 |
# File 'lib/aws-sdk-s3/object.rb', line 229 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.
165 166 167 |
# File 'lib/aws-sdk-s3/object.rb', line 165 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.
95 96 97 |
# File 'lib/aws-sdk-s3/object.rb', line 95 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.
113 114 115 116 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 113 def move_to(target, = {}) copy_to(target, ) delete end |
#multipart_upload(id) ⇒ MultipartUpload
1005 1006 1007 1008 1009 1010 1011 1012 |
# File 'lib/aws-sdk-s3/object.rb', line 1005 def multipart_upload(id) MultipartUpload.new( bucket_name: @bucket_name, object_key: @key, id: id, client: @client ) end |
#parts_count ⇒ Integer
The count of parts this object has.
212 213 214 |
# File 'lib/aws-sdk-s3/object.rb', line 212 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.
127 128 129 130 131 132 133 134 135 136 137 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 127 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.
187 188 189 190 191 192 193 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 187 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
871 872 873 874 875 876 877 878 |
# File 'lib/aws-sdk-s3/object.rb', line 871 def put( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = @client.put_object() resp.data end |
#replication_status ⇒ String
206 207 208 |
# File 'lib/aws-sdk-s3/object.rb', line 206 def replication_status data[:replication_status] end |
#request_charged ⇒ String
If present, indicates that the requester was successfully charged for the request.
201 202 203 |
# File 'lib/aws-sdk-s3/object.rb', line 201 def request_charged data[:request_charged] end |
#restore ⇒ String
Provides information about object restoration operation and expiration time of the restored object copy.
66 67 68 |
# File 'lib/aws-sdk-s3/object.rb', line 66 def restore data[:restore] end |
#restore_object(options = {}) ⇒ Types::RestoreObjectOutput
975 976 977 978 979 980 981 982 |
# File 'lib/aws-sdk-s3/object.rb', line 975 def restore_object( = {}) = .merge( bucket: @bucket_name, key: @key ) resp = @client.restore_object() resp.data end |
#server_side_encryption ⇒ String
The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
159 160 161 |
# File 'lib/aws-sdk-s3/object.rb', line 159 def server_side_encryption data[:server_side_encryption] end |
#size ⇒ Object
5 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 5 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.
173 174 175 |
# File 'lib/aws-sdk-s3/object.rb', line 173 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.
182 183 184 |
# File 'lib/aws-sdk-s3/object.rb', line 182 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 (KMS) master encryption key that was used for the object.
189 190 191 |
# File 'lib/aws-sdk-s3/object.rb', line 189 def ssekms_key_id data[:ssekms_key_id] end |
#storage_class ⇒ String
194 195 196 |
# File 'lib/aws-sdk-s3/object.rb', line 194 def storage_class data[:storage_class] end |
#upload_file(source, options = {}) ⇒ 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')
247 248 249 250 251 252 253 254 |
# File 'lib/aws-sdk-s3/customizations/object.rb', line 247 def upload_file(source, = {}) = .dup uploader = FileUploader.new( multipart_threshold: .delete(:multipart_threshold), client: client) uploader.upload(source, .merge(bucket: bucket_name, key: key)) true end |
#version(id) ⇒ ObjectVersion
1016 1017 1018 1019 1020 1021 1022 1023 |
# File 'lib/aws-sdk-s3/object.rb', line 1016 def version(id) ObjectVersion.new( bucket_name: @bucket_name, object_key: @key, id: id, client: @client ) end |
#version_id ⇒ String
Version of the object.
101 102 103 |
# File 'lib/aws-sdk-s3/object.rb', line 101 def version_id data[:version_id] end |
#wait_until(options = {}, &block) ⇒ 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) {|instance| instance.state.name == 'running' }
## 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
384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 |
# File 'lib/aws-sdk-s3/object.rb', line 384 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 = {}) ⇒ Object
274 275 276 277 278 279 280 281 282 283 284 285 |
# File 'lib/aws-sdk-s3/object.rb', line 274 def wait_until_exists( = {}) , params = () waiter = Waiters::ObjectExists.new() yield_waiter_and_warn(waiter, &Proc.new) 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 = {}) ⇒ Object
293 294 295 296 297 298 299 300 301 302 303 304 |
# File 'lib/aws-sdk-s3/object.rb', line 293 def wait_until_not_exists( = {}) , params = () waiter = Waiters::ObjectNotExists.new() yield_waiter_and_warn(waiter, &Proc.new) 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.
152 153 154 |
# File 'lib/aws-sdk-s3/object.rb', line 152 def website_redirect_location data[:website_redirect_location] end |