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. -
#initialize(*args) ⇒ Bucket
constructor
A new instance of Bucket.
-
#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
Constructor Details
#initialize(name, options = {}) ⇒ Bucket #initialize(options = {}) ⇒ Bucket
Returns a new instance of Bucket.
22 23 24 25 26 27 28 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 22 def initialize(*args) = Hash === args.last ? args.pop.dup : {} @name = extract_name(args, ) @data = .delete(:data) @client = .delete(:client) || Client.new() @waiter_block_warned = false end |
Instance Method Details
#acl ⇒ BucketAcl
681 682 683 684 685 686 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 681 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
15 16 17 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 15 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
689 690 691 692 693 694 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 689 def cors BucketCors.new( bucket_name: @name, client: @client ) end |
#create(options = {}) ⇒ Types::CreateBucketOutput
276 277 278 279 280 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 276 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
293 294 295 296 297 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 293 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.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 35 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
362 363 364 365 366 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 362 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
697 698 699 700 701 702 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 697 def lifecycle BucketLifecycle.new( bucket_name: @name, client: @client ) end |
#lifecycle_configuration ⇒ BucketLifecycleConfiguration
705 706 707 708 709 710 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 705 def lifecycle_configuration BucketLifecycleConfiguration.new( bucket_name: @name, client: @client ) end |
#logging ⇒ BucketLogging
713 714 715 716 717 718 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 713 def logging BucketLogging.new( bucket_name: @name, client: @client ) end |
#multipart_uploads(options = {}) ⇒ MultipartUpload::Collection
776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 776 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
798 799 800 801 802 803 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 798 def notification BucketNotification.new( bucket_name: @name, client: @client ) end |
#object(key) ⇒ Object
807 808 809 810 811 812 813 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 807 def object(key) Object.new( bucket_name: @name, key: key, client: @client ) end |
#object_versions(options = {}) ⇒ ObjectVersion::Collection
856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 856 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
912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 912 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
933 934 935 936 937 938 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 933 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.
126 127 128 129 130 131 132 133 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 126 def presigned_post( = {}) PresignedPost.new( client.config.credentials, client.config.region, name, { url: url }.merge() ) end |
#put_object(options = {}) ⇒ Object
668 669 670 671 672 673 674 675 676 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 668 def put_object( = {}) = .merge(bucket: @name) @client.put_object() Object.new( bucket_name: @name, key: [:key], client: @client ) end |
#request_payment ⇒ BucketRequestPayment
941 942 943 944 945 946 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 941 def request_payment BucketRequestPayment.new( bucket_name: @name, client: @client ) end |
#tagging ⇒ BucketTagging
949 950 951 952 953 954 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 949 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"
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/customizations/bucket.rb', line 88 def url( = {}) if [:virtual_host] scheme = .fetch(:secure, true) ? 'https' : 'http' "#{scheme}://#{name}" else # Taken from Aws::S3::Endpoints module unless client.config.regional_endpoint endpoint = client.config.endpoint.to_s end params = Aws::S3::EndpointParameters.new( bucket: name, region: client.config.region, use_fips: client.config.use_fips_endpoint, use_dual_stack: client.config.use_dualstack_endpoint, endpoint: endpoint, force_path_style: client.config.force_path_style, accelerate: client.config.use_accelerate_endpoint, use_global_endpoint: client.config.s3_us_east_1_regional_endpoint == 'legacy', use_object_lambda_endpoint: nil, disable_access_points: nil, disable_multi_region_access_points: client.config.s3_disable_multiregion_access_points, use_arn_region: client.config.s3_use_arn_region, ) endpoint = Aws::S3::EndpointProvider.new.resolve_endpoint(params) endpoint.url end end |
#versioning ⇒ BucketVersioning
957 958 959 960 961 962 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 957 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
965 966 967 968 969 970 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 965 def website BucketWebsite.new( bucket_name: @name, client: @client ) end |