Class: Aws::S3::Bucket
- Inherits:
-
Object
- Object
- Aws::S3::Bucket
- Defined in:
- gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb,
gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb
Defined Under Namespace
Classes: Collection
Read-Only Attributes collapse
-
#creation_date ⇒ Time
Date the bucket was created.
-
#name ⇒ String
Actions collapse
-
#create(options = {}) ⇒ Types::CreateBucketOutput
-
#delete(options = {}) ⇒ EmptyStructure
-
#delete_objects(options = {}) ⇒ Types::DeleteObjectsOutput
-
#put_object(options = {}) ⇒ Object
Associations collapse
-
#acl ⇒ BucketAcl
-
#cors ⇒ BucketCors
-
#lifecycle ⇒ BucketLifecycle
-
#lifecycle_configuration ⇒ BucketLifecycleConfiguration
-
#logging ⇒ BucketLogging
-
#multipart_uploads(options = {}) ⇒ MultipartUpload::Collection
-
#notification ⇒ BucketNotification
-
#object(key) ⇒ Object
-
#object_versions(options = {}) ⇒ ObjectVersion::Collection
-
#objects(options = {}) ⇒ ObjectSummary::Collection
-
#policy ⇒ BucketPolicy
-
#request_payment ⇒ BucketRequestPayment
-
#tagging ⇒ BucketTagging
-
#versioning ⇒ BucketVersioning
-
#website ⇒ BucketWebsite
Instance Method Summary collapse
-
#clear! ⇒ void
Deletes all objects and versioned objects from this bucket.
-
#client ⇒ Client
-
#data ⇒ Types::Bucket
Returns the data for this Bucket.
-
#data_loaded? ⇒ Boolean
Returns
true
if this resource is loaded. -
#delete!(options = {}) ⇒ void
Deletes all objects and versioned objects from this bucket and then deletes the bucket.
-
#exists?(options = {}) ⇒ Boolean
Returns
true
if the Bucket exists. -
#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.
-
#url(options = {}) ⇒ String
Returns a public URL for this bucket.
-
#wait_until(options = {}) {|resource| ... } ⇒ Resource
deprecated
Deprecated.
Use [Aws::S3::Client] #wait_until instead
-
#wait_until_exists(options = {}, &block) ⇒ Bucket
-
#wait_until_not_exists(options = {}, &block) ⇒ Bucket
Instance Method Details
#acl ⇒ BucketAcl
580 581 582 583 584 585 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 580 def acl BucketAcl.new( bucket_name: @name, client: @client ) end |
#clear! ⇒ void
This method returns an undefined value.
Deletes all objects and versioned objects from this bucket
31 32 33 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 31 def clear! object_versions.batch_delete! end |
#client ⇒ Client
47 48 49 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 47 def client @client end |
#cors ⇒ BucketCors
588 589 590 591 592 593 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 588 def cors BucketCors.new( bucket_name: @name, client: @client ) end |
#create(options = {}) ⇒ Types::CreateBucketOutput
256 257 258 259 260 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 256 def create( = {}) = .merge(bucket: @name) resp = @client.create_bucket() resp.data end |
#creation_date ⇒ Time
Date the bucket was created. This date can change when making changes to your bucket, such as editing its bucket policy.
40 41 42 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 40 def creation_date data[:creation_date] end |
#data ⇒ Types::Bucket
Returns the data for this Aws::S3::Bucket.
62 63 64 65 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 62 def data load unless @data @data end |
#data_loaded? ⇒ Boolean
Returns true
if this resource is loaded. Accessing attributes or
#data on an unloaded resource will trigger a call to #load.
70 71 72 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 70 def data_loaded? !!@data end |
#delete(options = {}) ⇒ EmptyStructure
273 274 275 276 277 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 273 def delete( = {}) = .merge(bucket: @name) resp = @client.delete_bucket() resp.data end |
#delete!(options = {}) ⇒ void
This method returns an undefined value.
Deletes all objects and versioned objects from this bucket and then deletes the bucket.
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 51 def delete!( = {}) = { initial_wait: 1.3, max_attempts: 3 }.merge() attempts = 0 begin clear! delete rescue Errors::BucketNotEmpty attempts += 1 raise if attempts >= [:max_attempts] Kernel.sleep([:initial_wait]**attempts) retry end end |
#delete_objects(options = {}) ⇒ Types::DeleteObjectsOutput
323 324 325 326 327 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 323 def delete_objects( = {}) = .merge(bucket: @name) resp = @client.delete_objects() resp.data end |
#exists?(options = {}) ⇒ Boolean
Returns true
if the Bucket exists.
77 78 79 80 81 82 83 84 85 86 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 77 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 |
#lifecycle ⇒ BucketLifecycle
596 597 598 599 600 601 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 596 def lifecycle BucketLifecycle.new( bucket_name: @name, client: @client ) end |
#lifecycle_configuration ⇒ BucketLifecycleConfiguration
604 605 606 607 608 609 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 604 def lifecycle_configuration BucketLifecycleConfiguration.new( bucket_name: @name, client: @client ) end |
#logging ⇒ BucketLogging
612 613 614 615 616 617 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 612 def logging BucketLogging.new( bucket_name: @name, client: @client ) end |
#multipart_uploads(options = {}) ⇒ MultipartUpload::Collection
675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 675 def multipart_uploads( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = @client.list_multipart_uploads() resp.each_page do |page| batch = [] page.data.uploads.each do |u| batch << MultipartUpload.new( bucket_name: @name, object_key: u.key, id: u.upload_id, data: u, client: @client ) end y.yield(batch) end end MultipartUpload::Collection.new(batches) end |
#name ⇒ String
33 34 35 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 33 def name @name end |
#notification ⇒ BucketNotification
697 698 699 700 701 702 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 697 def notification BucketNotification.new( bucket_name: @name, client: @client ) end |
#object(key) ⇒ Object
706 707 708 709 710 711 712 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 706 def object(key) Object.new( bucket_name: @name, key: key, client: @client ) end |
#object_versions(options = {}) ⇒ ObjectVersion::Collection
755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 755 def object_versions( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = @client.list_object_versions() resp.each_page do |page| batch = [] page.data.versions_delete_markers.each do |v| batch << ObjectVersion.new( bucket_name: @name, object_key: v.key, id: v.version_id, data: v, client: @client ) end y.yield(batch) end end ObjectVersion::Collection.new(batches) end |
#objects(options = {}) ⇒ ObjectSummary::Collection
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 811 def objects( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = @client.list_objects_v2() resp.each_page do |page| batch = [] page.data.contents.each do |c| batch << ObjectSummary.new( bucket_name: @name, key: c.key, data: c, client: @client ) end y.yield(batch) end end ObjectSummary::Collection.new(batches) end |
#policy ⇒ BucketPolicy
832 833 834 835 836 837 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 832 def policy BucketPolicy.new( bucket_name: @name, client: @client ) end |
#presigned_post(options = {}) ⇒ PresignedPost
You must specify :key
or :key_starts_with
. All other options
are optional.
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.
124 125 126 127 128 129 130 131 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 124 def presigned_post( = {}) PresignedPost.new( client.config.credentials, client.config.region, name, { url: url }.merge() ) end |
#put_object(options = {}) ⇒ Object
567 568 569 570 571 572 573 574 575 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 567 def put_object( = {}) = .merge(bucket: @name) @client.put_object() Object.new( bucket_name: @name, key: [:key], client: @client ) end |
#request_payment ⇒ BucketRequestPayment
840 841 842 843 844 845 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 840 def request_payment BucketRequestPayment.new( bucket_name: @name, client: @client ) end |
#tagging ⇒ BucketTagging
848 849 850 851 852 853 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 848 def tagging BucketTagging.new( bucket_name: @name, client: @client ) end |
#url(options = {}) ⇒ String
Returns a public URL for this bucket.
It will also work when provided an Access Point ARN.
You can pass virtual_host: true
to use the bucket name as the
host name.
bucket = s3.bucket('my.bucket.com')
bucket.url(virtual_host: true)
#=> "http://my.bucket.com"
100 101 102 103 104 105 106 107 108 109 110 111 112 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 100 def url( = {}) if [:virtual_host] "http://#{name}" elsif @arn Plugins::ARN.resolve_url!( client.config.endpoint.dup, @arn, @resolved_region ).to_s else s3_bucket_url end end |
#versioning ⇒ BucketVersioning
856 857 858 859 860 861 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 856 def versioning BucketVersioning.new( bucket_name: @name, client: @client ) 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
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 202 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) ⇒ Bucket
94 95 96 97 98 99 100 101 102 103 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 94 def wait_until_exists( = {}, &block) , params = () waiter = Waiters::BucketExists.new() yield_waiter_and_warn(waiter, &block) if block_given? waiter.wait(params.merge(bucket: @name)) Bucket.new({ name: @name, client: @client }) end |
#wait_until_not_exists(options = {}, &block) ⇒ Bucket
111 112 113 114 115 116 117 118 119 120 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 111 def wait_until_not_exists( = {}, &block) , params = () waiter = Waiters::BucketNotExists.new() yield_waiter_and_warn(waiter, &block) if block_given? waiter.wait(params.merge(bucket: @name)) Bucket.new({ name: @name, client: @client }) end |
#website ⇒ BucketWebsite
864 865 866 867 868 869 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 864 def website BucketWebsite.new( bucket_name: @name, client: @client ) end |