Class: AWS::S3::Bucket
- Inherits:
-
Object
- Object
- AWS::S3::Bucket
- Defined in:
- lib/aws/s3/bucket.rb
Overview
Represents a bucket in S3.
Creating Buckets
You create a bucket by name. Bucket names must be globally unique and must be DNS compatible.
s3 = AWS::S3.new
bucket = s3.buckets.create('dns-compat-bucket-name')
Getting a Bucket
You can create a reference to a bucket, given its name.
bucket = s3.buckets['bucket-name'] # makes no request
bucket.exists? #=> returns true/false
Enumerating Buckets
The BucketCollection class is enumerable.
s3.buckets.each do |bucket|
puts bucket.name
end
Deleting a Bucket
You can delete an empty bucket you own.
bucket = s3.buckets.create('my-temp-bucket')
bucket.objects['abc'].write('xyz')
bucket.clear! # deletes all object versions in batches
bucket.delete
You can alternatively call #delete! which will clear the bucket for your first.
bucket.delete!
Objects
Given a bucket you can access its objects, either by key or by enumeration.
bucket.objects['key'] #=> makes no request, returns an S3Object
bucket.objects.each do |obj|
puts obj.key
end
See ObjectCollection and S3Object for more information on working with objects.
Bucket Policies and ACLs
You can control access to your bucket and its contents a number of ways. You can specify a bucket ACL (access control list) or a bucket policy.
ACLs
ACLs control access to your bucket and its contents via a list of grants and grantees.
Canned ACLs
The simplest way to specify an ACL is to use one of Amazon’s “canned” ACLs. Amazon accepts the following canned ACLs:
-
:private
-
:public_read
-
:public_read_write
-
:authenticated_read
-
:bucket_owner_read
-
:bucket_owner_full_control
You can specify a the ACL at bucket creation or later update a bucket.
# at create time, defaults to :private when not specified
bucket = s3.buckets.create('name', :acl => :public_read)
# replacing an existing bucket ACL
bucket.acl = :private
Grants
Alternatively you can specify a hash of grants. Each entry in the :grant
hash has a grant (key) and a list of grantees (values). Valid grant keys are:
-
:grant_read
-
:grant_write
-
:grant_read_acp
-
:grant_write_acp
-
:grant_full_control
Each grantee can be a String, Hash or array of strings or hashes. The following example uses grants to provide public read to everyone while providing full control to a user by email address and to another by their account id (cannonical user id).
bucket = s3.buckets.create('name', :grants => {
:grant_read => [
{ :uri => "http://acs.amazonaws.com/groups/global/AllUsers" },
],
:grant_full_control => [
{ :id => 'abc...mno' } # cannonical user id
{ :email_address => '[email protected]' }, # email address
]
})
ACL Object
Lastly, you can build an ACL object and use a Ruby DSL to specify grants and grantees. See ACLObject for more information.
# updating an existing bucket acl using ACLObject
bucket.acl.change do |acl|
acl.grants.reject! do |g|
g.grantee.canonical_user_id != bucket.owner.id
end
end
Policies
You can also work with bucket policies.
policy = AWS::S3::Policy.new
policy.allow(
:actions => [:put_object, :get_object]
:resources => [bucket]
:principals => :any)
bucket.policy = policy
See Core::Policy and Policy for more information on build policy objects.
Versioned Buckets
You can enable versioning on a bucket you control. When versioning is enabled, S3 will keep track of each version of each object you write to the bucket (even deletions).
bucket.versioning_enabled? #=> false
bucket.enable_versioning
# there is also a #disable_versioning method
obj = bucket.objects['my-obj']
obj.write('a')
obj.write('b')
obj.delete
obj.write('c')
obj.versions.each do |obj_version|
if obj_version.delete_marker?
puts obj_version.read
else
puts "- DELETE MARKER"
end
end
Alternatively you can enumerate all versions of all objects in your bucket.
bucket.versions.each do |obj_version|
puts obj_version.key + " : " + obj_version.version_id
end
See BucketVersionCollection, ObjectVersionCollection and ObjectVersion for more information on working with objects in a versioned bucket. Also see the S3 documentation for information on object versioning.
Instance Attribute Summary collapse
-
#name ⇒ String
readonly
The bucket name.
Instance Method Summary collapse
-
#==(other) ⇒ Boolean
Returns true if the two buckets have the same name.
-
#acl ⇒ AccessControlList
Returns the bucket’s access control list.
-
#acl=(acl) ⇒ nil
Sets the bucket’s ACL (access control list).
-
#as_tree(options = {}) ⇒ Tree
Returns a tree that allows you to expose the bucket contents like a directory structure.
-
#clear! ⇒ nil
Deletes all objects from this bucket.
-
#cors ⇒ CORSRuleCollection
Returns a collection that can be used to manage (add, edit and delete) CORS rules for this bucket.
-
#cors=(*rules) ⇒ Object
Sets the bucket CORS rules.
-
#delete ⇒ nil
Deletes the current bucket.
-
#delete! ⇒ nil
Deletes all objects in a bucket and then deletes the bucket.
-
#empty? ⇒ Boolean
Returns true if the bucket has no objects (this includes versioned objects that are delete markers).
-
#enable_versioning(opts = {}) ⇒ nil
Enables versioning on this bucket.
-
#eql?(other_bucket) ⇒ Boolean
Returns true if the two buckets have the same name.
-
#exists? ⇒ Boolean
Returns true if the bucket exists in S3.
-
#initialize(name, options = {}) ⇒ Bucket
constructor
A new instance of Bucket.
-
#lifecycle_configuration ⇒ BucketLifecycleConfiguration
The primary interface for editing the lifecycle configuration.
-
#lifecycle_configuration=(config) ⇒ nil
You can call this method if you prefer to build your own lifecycle configuration.
-
#location_constraint ⇒ String?
Returns the location constraint for a bucket (if it has one), nil otherwise.
-
#multipart_uploads ⇒ MultipartUploadCollection
Represents all of the multipart uploads that are in progress for this bucket.
-
#objects ⇒ ObjectCollection
Represents all objects(keys) in this bucket.
-
#owner ⇒ String
Bucket owner id.
-
#policy ⇒ Policy?
Returns the bucket policy.
-
#policy=(policy) ⇒ nil
Sets the bucket’s policy.
-
#presigned_post(options = {}) ⇒ Object
Generates fields for a presigned POST to this object.
-
#suspend_versioning(opts = {}) ⇒ nil
Suspends versioning on this bucket.
-
#tags ⇒ BucketTagCollection
Returns the tags for this bucket.
-
#tags=(tags) ⇒ Object
Sets the tags for this bucket.
-
#url ⇒ String
Returns the url for this bucket.
-
#versioning_enabled? ⇒ Boolean
(also: #versioned?)
Returns
true
if version is enabled on this bucket. -
#versioning_state ⇒ Symbol
Returns the versioning status for this bucket.
-
#versions ⇒ BucketVersionCollection
Represents all of the versioned objects stored in this bucket.
Constructor Details
#initialize(name, options = {}) ⇒ Bucket
Returns a new instance of Bucket.
200 201 202 203 204 205 206 207 |
# File 'lib/aws/s3/bucket.rb', line 200 def initialize(name, = {}) # the S3 docs disagree with what the service allows, # so it's not safe to toss out invalid bucket names # S3::Client.validate_bucket_name!(name) @name = name @owner = [:owner] super end |
Instance Attribute Details
#name ⇒ String (readonly)
Returns The bucket name.
210 211 212 |
# File 'lib/aws/s3/bucket.rb', line 210 def name @name end |
Instance Method Details
#==(other) ⇒ Boolean
Returns true if the two buckets have the same name.
379 380 381 |
# File 'lib/aws/s3/bucket.rb', line 379 def ==(other) other.kind_of?(Bucket) && other.name == name end |
#acl ⇒ AccessControlList
Returns the bucket’s access control list. This will be an instance of AccessControlList, plus an additional change
method:
bucket.acl.change do |acl|
acl.grants.reject! do |g|
g.grantee.canonical_user_id != bucket.owner.id
end
end
446 447 448 449 450 451 452 453 454 455 |
# File 'lib/aws/s3/bucket.rb', line 446 def acl resp = client.get_bucket_acl(:bucket_name => name) acl = AccessControlList.new(resp.data) acl.extend ACLProxy acl.bucket = self acl end |
#acl=(acl) ⇒ nil
Sets the bucket’s ACL (access control list). You can provide an ACL in a number of different formats.
461 462 463 464 |
# File 'lib/aws/s3/bucket.rb', line 461 def acl= acl client.set_bucket_acl((acl).merge(:bucket_name => name)) nil end |
#as_tree(options = {}) ⇒ Tree
Returns a tree that allows you to expose the bucket contents like a directory structure.
614 615 616 |
# File 'lib/aws/s3/bucket.rb', line 614 def as_tree = {} objects.as_tree() end |
#clear! ⇒ nil
Deletes all objects from this bucket.
347 348 349 350 351 |
# File 'lib/aws/s3/bucket.rb', line 347 def clear! versions.each_batch do |versions| objects.delete(versions) end end |
#cors ⇒ CORSRuleCollection
Returns a collection that can be used to manage (add, edit and delete) CORS rules for this bucket.
277 278 279 |
# File 'lib/aws/s3/bucket.rb', line 277 def cors CORSRuleCollection.new(self) end |
#cors=(*rules) ⇒ Object
Sets the bucket CORS rules.
284 285 286 |
# File 'lib/aws/s3/bucket.rb', line 284 def cors= *rules self.cors.set(*rules) end |
#delete ⇒ nil
Deletes the current bucket. An error will be raised if the bucket is not empty.
356 357 358 359 |
# File 'lib/aws/s3/bucket.rb', line 356 def delete client.delete_bucket(:bucket_name => @name) nil end |
#delete! ⇒ nil
Deletes all objects in a bucket and then deletes the bucket.
363 364 365 366 |
# File 'lib/aws/s3/bucket.rb', line 363 def delete! clear! delete end |
#empty? ⇒ Boolean
Returns true if the bucket has no objects (this includes versioned objects that are delete markers).
224 225 226 |
# File 'lib/aws/s3/bucket.rb', line 224 def empty? versions.first ? false : true end |
#enable_versioning(opts = {}) ⇒ nil
Enables versioning on this bucket.
299 300 301 302 303 304 305 306 |
# File 'lib/aws/s3/bucket.rb', line 299 def enable_versioning(opts = {}) client.set_bucket_versioning( :bucket_name => @name, :state => :enabled, :mfa_delete => opts[:mfa_delete], :mfa => opts[:mfa]) nil end |
#eql?(other_bucket) ⇒ Boolean
Returns true if the two buckets have the same name
384 385 386 |
# File 'lib/aws/s3/bucket.rb', line 384 def eql?(other_bucket) self == other_bucket end |
#exists? ⇒ Boolean
This method only indicates if there is a bucket in S3, not if you have permissions to work with the bucket or not.
Returns true if the bucket exists in S3.
391 392 393 394 395 396 397 398 399 400 401 402 403 |
# File 'lib/aws/s3/bucket.rb', line 391 def exists? begin versioned? # makes a get bucket request without listing contents # raises a client error if the bucket doesn't exist or # if you don't have permission to get the bucket # versioning status. true rescue Errors::NoSuchBucket => e false # bucket does not exist rescue Errors::ClientError => e true # bucket exists end end |
#lifecycle_configuration ⇒ BucketLifecycleConfiguration
The primary interface for editing the lifecycle configuration. See AWS::S3::BucketLifecycleConfiguration for more information.
543 544 545 |
# File 'lib/aws/s3/bucket.rb', line 543 def lifecycle_configuration @lifecycle_cfg ||= BucketLifecycleConfiguration.new(self) end |
#lifecycle_configuration=(config) ⇒ nil
You can call this method if you prefer to build your own lifecycle configuration.
bucket.lifecycle_configuration = <<-XML
<LifecycleConfiguration>
...
</LifecycleConfiguration>
XML
You can also use this method to copy a lifecycle configuration from another bucket.
bucket.lifecycle_configuration = other_bucket.lifecycle_configuration
If you call this method, passing nil, the lifecycle configuration for this bucket will be deleted.
570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 |
# File 'lib/aws/s3/bucket.rb', line 570 def lifecycle_configuration= config if config.nil? client_opts = {} client_opts[:bucket_name] = name client.delete_bucket_lifecycle_configuration(client_opts) @lifecycle_cfg = BucketLifecycleConfiguration.new(self, :empty => true) else xml = config.is_a?(String) ? config : config.to_xml client_opts = {} client_opts[:bucket_name] = name client_opts[:lifecycle_configuration] = xml client.set_bucket_lifecycle_configuration(client_opts) @lifecycle_cfg = BucketLifecycleConfiguration.new(self, :xml => xml) end nil end |
#location_constraint ⇒ String?
Returns the location constraint for a bucket (if it has one), nil otherwise.
230 231 232 |
# File 'lib/aws/s3/bucket.rb', line 230 def location_constraint client.get_bucket_location(:bucket_name => name).location_constraint end |
#multipart_uploads ⇒ MultipartUploadCollection
Returns Represents all of the multipart uploads that are in progress for this bucket.
419 420 421 |
# File 'lib/aws/s3/bucket.rb', line 419 def multipart_uploads MultipartUploadCollection.new(self) end |
#objects ⇒ ObjectCollection
Returns Represents all objects(keys) in this bucket.
407 408 409 |
# File 'lib/aws/s3/bucket.rb', line 407 def objects ObjectCollection.new(self) end |
#owner ⇒ String
Returns bucket owner id.
369 370 371 |
# File 'lib/aws/s3/bucket.rb', line 369 def owner @owner || client.list_buckets.owner end |
#policy ⇒ Policy?
Returns the bucket policy. This will be an instance of Policy. The returned policy will also have the methods of PolicyProxy mixed in, so you can use it to change the current policy or delete it, for example:
if policy = bucket.policy
# add a statement
policy.change do |p|
p.allow(...)
end
# delete the policy
policy.delete
end
Note that changing the policy is not an atomic operation; it fetches the current policy, yields it to the block, and then sets it again. Therefore, it’s possible that you may overwrite a concurrent update to the policy using this method.
505 506 507 508 509 510 511 512 513 |
# File 'lib/aws/s3/bucket.rb', line 505 def policy resp = client.get_bucket_policy(:bucket_name => name) policy = Policy.from_json(resp.data[:policy]) policy.extend(PolicyProxy) policy.bucket = self policy rescue Errors::NoSuchBucketPolicy => e nil end |
#policy=(policy) ⇒ nil
Sets the bucket’s policy.
522 523 524 525 |
# File 'lib/aws/s3/bucket.rb', line 522 def policy=(policy) client.set_bucket_policy(:bucket_name => name, :policy => policy) nil end |
#presigned_post(options = {}) ⇒ Object
Generates fields for a presigned POST to this object. All options are sent to the PresignedPost constructor.
622 623 624 |
# File 'lib/aws/s3/bucket.rb', line 622 def presigned_post( = {}) PresignedPost.new(self, ) end |
#suspend_versioning(opts = {}) ⇒ nil
Suspends versioning on this bucket.
319 320 321 322 323 324 325 326 |
# File 'lib/aws/s3/bucket.rb', line 319 def suspend_versioning(opts = {}) client.set_bucket_versioning( :bucket_name => @name, :state => :suspended, :mfa_delete => opts[:mfa_delete], :mfa => opts[:mfa]) nil end |
#tags ⇒ BucketTagCollection
Returns the tags for this bucket.
= bucket.
#=> <AWS::S3::BucketTagCollection>
# adds a tag to the bucket
['foo'] = 'abc'
# replaces all tags
.set('new' => 'tags')
# removes all tags from the bucket
.clear
# returns tags as a hash
.to_h
254 255 256 |
# File 'lib/aws/s3/bucket.rb', line 254 def BucketTagCollection.new(self) end |
#tags=(tags) ⇒ Object
Sets the tags for this bucket.
bucket. = { 'contents' => 'photots' }
You can remove all tags for the bucket by passing an empty hash or nil
.
bucket. = nil # {} also deletes all tags
bucket.
#=> {}
271 272 273 |
# File 'lib/aws/s3/bucket.rb', line 271 def self..set() end |
#url ⇒ String
Returns the url for this bucket.
214 215 216 217 218 219 220 |
# File 'lib/aws/s3/bucket.rb', line 214 def url if client.dns_compatible_bucket_name?(name) "http://#{name}.s3.amazonaws.com/" else "http://s3.amazonaws.com/#{name}/" end end |
#versioning_enabled? ⇒ Boolean Also known as: versioned?
Returns true
if version is enabled on this bucket.
329 330 331 |
# File 'lib/aws/s3/bucket.rb', line 329 def versioning_enabled? versioning_state == :enabled end |
#versioning_state ⇒ Symbol
Returns the versioning status for this bucket. States include:
-
:enabled
- currently enabled -
:suspended
- currently suspended -
:unversioned
- versioning has never been enabled
341 342 343 |
# File 'lib/aws/s3/bucket.rb', line 341 def versioning_state client.get_bucket_versioning(:bucket_name => @name).status end |
#versions ⇒ BucketVersionCollection
Returns Represents all of the versioned objects stored in this bucket.
413 414 415 |
# File 'lib/aws/s3/bucket.rb', line 413 def versions BucketVersionCollection.new(self) end |