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
1051 1052 1053 1054 1055 1056 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1051 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
1059 1060 1061 1062 1063 1064 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1059 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.metric('RESOURCE_MODEL') 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.metric('RESOURCE_MODEL') 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.metric('RESOURCE_MODEL') 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
1067 1068 1069 1070 1071 1072 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1067 def lifecycle BucketLifecycle.new( bucket_name: @name, client: @client ) end |
#lifecycle_configuration ⇒ BucketLifecycleConfiguration
1075 1076 1077 1078 1079 1080 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1075 def lifecycle_configuration BucketLifecycleConfiguration.new( bucket_name: @name, client: @client ) end |
#logging ⇒ BucketLogging
1083 1084 1085 1086 1087 1088 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1083 def logging BucketLogging.new( bucket_name: @name, client: @client ) end |
#multipart_uploads(options = {}) ⇒ MultipartUpload::Collection
1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1207 def multipart_uploads( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') 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
1231 1232 1233 1234 1235 1236 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1231 def notification BucketNotification.new( bucket_name: @name, client: @client ) end |
#object(key) ⇒ Object
1240 1241 1242 1243 1244 1245 1246 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1240 def object(key) Object.new( bucket_name: @name, key: key, client: @client ) end |
#object_versions(options = {}) ⇒ ObjectVersion::Collection
1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1324 def object_versions( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') 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
1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1443 def objects( = {}) batches = Enumerator.new do |y| = .merge(bucket: @name) resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') 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
1466 1467 1468 1469 1470 1471 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1466 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
1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1036 def put_object( = {}) = .merge(bucket: @name) Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do @client.put_object() end Object.new( bucket_name: @name, key: [:key], client: @client ) end |
#request_payment ⇒ BucketRequestPayment
1474 1475 1476 1477 1478 1479 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1474 def request_payment BucketRequestPayment.new( bucket_name: @name, client: @client ) end |
#tagging ⇒ BucketTagging
1482 1483 1484 1485 1486 1487 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1482 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
1490 1491 1492 1493 1494 1495 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1490 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.metric('RESOURCE_MODEL') 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.metric('RESOURCE_MODEL') 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.metric('RESOURCE_MODEL') do waiter.wait(params.merge(bucket: @name)) end Bucket.new({ name: @name, client: @client }) end |
#website ⇒ BucketWebsite
1498 1499 1500 1501 1502 1503 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/bucket.rb', line 1498 def website BucketWebsite.new( bucket_name: @name, client: @client ) end |