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
955 956 957 958 959 960 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 955 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
963 964 965 966 967 968 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 963 def cors BucketCors.new( bucket_name: @name, client: @client ) end |
#create(options = {}) ⇒ Types::CreateBucketOutput
335 336 337 338 339 340 341 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 335 def create( = {}) = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.feature('resource') do @client.create_bucket() end 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
360 361 362 363 364 365 366 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 360 def delete( = {}) = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.feature('resource') do @client.delete_bucket() end 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
474 475 476 477 478 479 480 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 474 def delete_objects( = {}) = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.feature('resource') do @client.delete_objects() end 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
971 972 973 974 975 976 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 971 def lifecycle BucketLifecycle.new( bucket_name: @name, client: @client ) end |
#lifecycle_configuration ⇒ BucketLifecycleConfiguration
979 980 981 982 983 984 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 979 def lifecycle_configuration BucketLifecycleConfiguration.new( bucket_name: @name, client: @client ) end |
#logging ⇒ BucketLogging
987 988 989 990 991 992 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 987 def logging BucketLogging.new( bucket_name: @name, client: @client ) end |
#multipart_uploads(options = {}) ⇒ MultipartUpload::Collection
1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1097 def multipart_uploads( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.feature('resource') do @client.list_multipart_uploads() end 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
1121 1122 1123 1124 1125 1126 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1121 def notification BucketNotification.new( bucket_name: @name, client: @client ) end |
#object(key) ⇒ Object
1130 1131 1132 1133 1134 1135 1136 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1130 def object(key) Object.new( bucket_name: @name, key: key, client: @client ) end |
#object_versions(options = {}) ⇒ ObjectVersion::Collection
1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1200 def object_versions( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.feature('resource') do @client.list_object_versions() end 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
1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1300 def objects( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.feature('resource') do @client.list_objects_v2() end 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
1323 1324 1325 1326 1327 1328 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1323 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
940 941 942 943 944 945 946 947 948 949 950 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 940 def put_object( = {}) = .merge(bucket: @name) Aws::Plugins::UserAgent.feature('resource') do @client.put_object() end Object.new( bucket_name: @name, key: [:key], client: @client ) end |
#request_payment ⇒ BucketRequestPayment
1331 1332 1333 1334 1335 1336 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1331 def request_payment BucketRequestPayment.new( bucket_name: @name, client: @client ) end |
#tagging ⇒ BucketTagging
1339 1340 1341 1342 1343 1344 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1339 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
1347 1348 1349 1350 1351 1352 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1347 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
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 206 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.feature('resource') do Aws::Waiters::Waiter.new().wait({}) end end |
#wait_until_exists(options = {}, &block) ⇒ Bucket
94 95 96 97 98 99 100 101 102 103 104 105 |
# 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? Aws::Plugins::UserAgent.feature('resource') do waiter.wait(params.merge(bucket: @name)) end Bucket.new({ name: @name, client: @client }) end |
#wait_until_not_exists(options = {}, &block) ⇒ Bucket
113 114 115 116 117 118 119 120 121 122 123 124 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 113 def wait_until_not_exists( = {}, &block) , params = () waiter = Waiters::BucketNotExists.new() yield_waiter_and_warn(waiter, &block) if block_given? Aws::Plugins::UserAgent.feature('resource') do waiter.wait(params.merge(bucket: @name)) end Bucket.new({ name: @name, client: @client }) end |
#website ⇒ BucketWebsite
1355 1356 1357 1358 1359 1360 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1355 def website BucketWebsite.new( bucket_name: @name, client: @client ) end |