Represents a bucket in S3.
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')
You can create a reference to a bucket, given its name.
bucket = s3.buckets['bucket-name'] # makes no request bucket.exists? #=> returns true/false
The {BucketCollection} class is enumerable.
s3.buckets.each do |bucket| puts bucket.name end
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!
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.
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 control access to your bucket and its contents via a list of grants and grantees.
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
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 => 'foo@bar.com' }, # email address ] })
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
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 {S3::Policy} for more information on build policy objects.
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.
@return [String] The bucket name
@param [String] name @param [Hash] options @option options [String] :owner (nil) The owner id of this bucket.
# File lib/aws/s3/bucket.rb, line 200 def initialize(name, options = {}) # 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 = options[:owner] super end
@return [Boolean] Returns true if the two buckets have the same name.
# File lib/aws/s3/bucket.rb, line 303 def ==(other) other.kind_of?(Bucket) && other.name == name end
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
@return [AccessControlList]
# File lib/aws/s3/bucket.rb, line 370 def acl resp = client.get_bucket_acl(:bucket_name => name) acl = AccessControlList.new(resp.data) acl.extend ACLProxy acl.bucket = self acl end
Sets the bucket's ACL (access control list). You can provide an ACL in a number of different formats. @param (see AWS::S3::ACLOptions#acl_options) @return [nil]
# File lib/aws/s3/bucket.rb, line 385 def acl= acl client.set_bucket_acl(acl_options(acl).merge(:bucket_name => name)) nil end
Returns a tree that allows you to expose the bucket contents like a directory structure.
@see Tree @param [Hash] options @option options [String] :prefix (nil) Set prefix to choose where
the top of the tree will be. A value of +nil+ means that the tree will include all objects in the collection.
@option options [String] :delimiter ('/') The string that separates
each level of the tree. This is usually a directory separator.
@option options [Boolean] :append (true) If true, the delimiter is
appended to the prefix when the prefix does not already end with the delimiter.
@return [Tree]
# File lib/aws/s3/bucket.rb, line 538 def as_tree options = {} objects.as_tree(options) end
Deletes all objects from this bucket. @return [nil]
# File lib/aws/s3/bucket.rb, line 271 def clear! versions.each_batch do |versions| objects.delete(versions) end end
Deletes the current bucket. An error will be raised if the bucket is not empty. @return [nil]
# File lib/aws/s3/bucket.rb, line 280 def delete client.delete_bucket(:bucket_name => @name) nil end
Deletes all objects in a bucket and then deletes the bucket. @return [nil]
# File lib/aws/s3/bucket.rb, line 287 def delete! clear! delete end
@return [Boolean] Returns true if the bucket has no objects
(this includes versioned objects that are delete markers).
# File lib/aws/s3/bucket.rb, line 224 def empty? versions.first ? false : true end
Enables versioning on this bucket. @return [nil]
# File lib/aws/s3/bucket.rb, line 236 def enable_versioning client.set_bucket_versioning( :bucket_name => @name, :state => :enabled) nil end
@return [Boolean] Returns true if the two buckets have the same name
# File lib/aws/s3/bucket.rb, line 308 def eql?(other_bucket) self == other_bucket end
@note This method only indicates if there is a bucket in S3, not
if you have permissions to work with the bucket or not.
@return [Boolean] Returns true if the bucket exists in S3.
# File lib/aws/s3/bucket.rb, line 315 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
@private
# File lib/aws/s3/bucket.rb, line 298 def inspect "#<AWS::S3::Bucket:#{name}>" end
The primary interface for editing the lifecycle configuration. See {BucketLifecycleConfiguration} for more information.
@example Adding rules to a bucket's lifecycle configuration
bucket.lifecycle_configuration.update do add_rule 'cache-1/', 30 add_rule 'cache-2/', 30 end
@example Deleting the lifecycle configuration
bucket.lifecycle_configuration.clear
@return [BucketLifecycleConfiguration]
# File lib/aws/s3/bucket.rb, line 467 def lifecycle_configuration @lifecycle_cfg ||= BucketLifecycleConfiguration.new(self) end
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.
@param [String,Object] config You can pass an xml string or any
other object that responds to #to_xml (e.g. BucketLifecycleConfiguration).
@return [nil]
# File lib/aws/s3/bucket.rb, line 494 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
@return [String,nil] Returns the location constraint for a bucket
(if it has one), nil otherwise.
# File lib/aws/s3/bucket.rb, line 230 def location_constraint client.get_bucket_location(:bucket_name => name).location_constraint end
@return [MultipartUploadCollection] Represents all of the
multipart uploads that are in progress for this bucket.
# File lib/aws/s3/bucket.rb, line 343 def multipart_uploads MultipartUploadCollection.new(self) end
@return [ObjectCollection] Represents all objects(keys) in
this bucket.
# File lib/aws/s3/bucket.rb, line 331 def objects ObjectCollection.new(self) end
@return [String] bucket owner id
# File lib/aws/s3/bucket.rb, line 293 def owner @owner || client.list_buckets.owner end
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.
@return [Policy,nil] Returns the bucket policy (if it has one),
or it returns +nil+ otherwise.
# File lib/aws/s3/bucket.rb, line 429 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
Sets the bucket's policy.
@param policy The new policy. This can be a string (which
is assumed to contain a valid policy expressed in JSON), a Policy object or any object that responds to +to_json+.
@see Policy @return [nil]
# File lib/aws/s3/bucket.rb, line 446 def policy=(policy) client.set_bucket_policy(:bucket_name => name, :policy => policy) nil end
Generates fields for a presigned POST to this object. All options are sent to the PresignedPost constructor.
@see PresignedPost
# File lib/aws/s3/bucket.rb, line 546 def presigned_post(options = {}) PresignedPost.new(self, options) end
Suspends versioning on this bucket. @return [nil]
# File lib/aws/s3/bucket.rb, line 245 def suspend_versioning client.set_bucket_versioning( :bucket_name => @name, :state => :suspended) nil end
Returns the url for this bucket. @return [String] url to the bucket
# 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
@return [Boolean] returns true
if version is enabled on this
bucket.
# File lib/aws/s3/bucket.rb, line 253 def versioning_enabled? versioning_state == :enabled end
Returns the versioning status for this bucket. States include:
:enabled
- currently enabled
:suspended
- currently suspended
:unversioned
- versioning has never been enabled
@return [Symbol] the versioning state
# File lib/aws/s3/bucket.rb, line 265 def versioning_state client.get_bucket_versioning(:bucket_name => @name).status end
@return [BucketVersionCollection] Represents all of the versioned
objects stored in this bucket.
# File lib/aws/s3/bucket.rb, line 337 def versions BucketVersionCollection.new(self) end