class AWS::S3::Bucket
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.
# Website Configuration
It is easy to enable website hosting for a bucket.
bucket.configure_website
You can specify the index and error documents by passing a block. If your bucket is already configured as a website, the current configuration will be yielded. If you bucket it not currently configured as a website, a new configuration will be yielded with default values.
bucket.configure_website do |cfg| cfg.index_document_suffix = 'index.html' cfg.error_document_key = 'error.html' end
You can disable website hosting two ways:
bucket.remove_website_configuration bucket.website_configuration = nil
You can use {#website_configuration=} to copy a website configuration from one bucket to another.
bucket.website_configuration = other_bucket.website_configuration
# 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 => 'foo@bar.com' }, # 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 {S3::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 #suspend_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.
Attributes
@return [String] The bucket name
Public Class Methods
@param [String] name @param [Hash] options @option options [String] :owner (nil) The owner id of this bucket.
AWS::Core::Model::new
# File lib/aws/s3/bucket.rb, line 227 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
Public Instance Methods
@return [Boolean] Returns true if the two buckets have the same name.
# File lib/aws/s3/bucket.rb, line 493 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 560 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 ACLOptions#acl_options
) @return [nil]
# File lib/aws/s3/bucket.rb, line 575 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 728 def as_tree options = {} objects.as_tree(options) end
Deletes all objects from this bucket. @return [nil]
# File lib/aws/s3/bucket.rb, line 461 def clear! versions.each_batch do |versions| objects.delete(versions) end end
Configure the current bucket as a website.
bucket.configure_website
If you pass a block, the website configuration object will be yielded. You can modify it before it is saved.
bucket.configure_website do |cfg| cfg.index_document_suffix = 'index.html' cfg.error_document_key = 'error.html' end
If the bucket already has a website configuration, it will be loaded and yielded. This makes it possible to modify an existing configuration.
# only rename the error document bucket.configure_website do |cfg| cfg.error_document_key = 'oops.html' end
@yieldparam [WebsiteConfiguration] website_config @return [WebsiteConfiguration] @see website_configuration
@see website_configuration=
@see remove_website_configuration
@see website?
# File lib/aws/s3/bucket.rb, line 289 def configure_website &block website_config = self.website_configuration website_config ||= WebsiteConfiguration.new yield(website_config) if block_given? self.website_configuration = website_config end
@return [CORSRuleCollection] Returns a collection that can be
used to manage (add, edit and delete) CORS rules for this bucket.
# File lib/aws/s3/bucket.rb, line 391 def cors CORSRuleCollection.new(self) end
Sets the bucket CORS rules. @param (see CORSRuleCollection#set
) @see CORSRuleCollection#set
# File lib/aws/s3/bucket.rb, line 398 def cors= *rules self.cors.set(*rules) 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 470 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 477 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 252 def empty? versions.first ? false : true end
Enables versioning on this bucket.
@option opts [String] :mfa_delete Set to 'Enabled' or 'Disabled'
to control the state of MFA delete on the bucket versioning. Setting this option requires the :mfa option to also be set.
@option opts [String] :mfa The serial number and current token code of
the Multi-Factor Authentication (MFA) device for the user. Format is "SERIAL TOKEN" - with a space between the serial and token.
@return [nil]
# File lib/aws/s3/bucket.rb, line 413 def enable_versioning(opts = {}) client.set_bucket_versioning( :bucket_name => @name, :state => :enabled, :mfa_delete => opts[:mfa_delete], :mfa => opts[:mfa]) nil end
@return [Boolean] Returns true if the two buckets have the same name
# File lib/aws/s3/bucket.rb, line 498 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 505 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::AccessDenied => e true # bucket exists end end
@api private
# File lib/aws/s3/bucket.rb, line 488 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 657 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 684 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 258 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 533 def multipart_uploads MultipartUploadCollection.new(self) end
@return [ObjectCollection] Represents all objects(keys) in
this bucket.
# File lib/aws/s3/bucket.rb, line 521 def objects ObjectCollection.new(self) end
@return [String] bucket owner id
# File lib/aws/s3/bucket.rb, line 483 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 619 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 636 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 736 def presigned_post(options = {}) PresignedPost.new(self, options) end
@return [nil] Deletes the bucket website configuration. @see configure_website
@see website_configuration
@see website_configuration=
@see website?
# File lib/aws/s3/bucket.rb, line 332 def remove_website_configuration client.delete_bucket_website(:bucket_name => name) @website_configuration = false nil end
Suspends versioning on this bucket.
@option opts [String] :mfa_delete Set to 'Enabled' or 'Disabled'
to control the state of MFA delete on the bucket versioning. Setting this option requires the :mfa option to also be set.
@option opts [String] :mfa The serial number and current token code of
the Multi-Factor Authentication (MFA) device for the user. Format is "SERIAL TOKEN" - with a space between the serial and token.
@return [nil]
# File lib/aws/s3/bucket.rb, line 433 def suspend_versioning(opts = {}) client.set_bucket_versioning( :bucket_name => @name, :state => :suspended, :mfa_delete => opts[:mfa_delete], :mfa => opts[:mfa]) nil end
Returns the url for this bucket. @return [String] url to the bucket
# File lib/aws/s3/bucket.rb, line 241 def url(options = {}) protocol = options.fetch(:secure, false) ? "https://" : "http://" if client.dns_compatible_bucket_name?(name) "#{protocol}#{name}.s3.amazonaws.com/" else "#{protocol}s3.amazonaws.com/#{name}/" end end
@return [Boolean] returns `true` if version is enabled on this bucket.
# File lib/aws/s3/bucket.rb, line 443 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 455 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 527 def versions BucketVersionCollection.new(self) end
@return [Boolean] Returns `true` if this bucket is configured as
a website.
@see configure_website
@see website_configuration
@see website_configuration=
@see remove_website_configuration
# File lib/aws/s3/bucket.rb, line 344 def website? !!website_configuration end
Returns the bucket website configuration. Returns `nil` if the bucket is not configured as a website. @return [WebsiteConfiguration,nil] @see configure_website
@see website_configuration=
@see remove_website_configuration
@see website?
# File lib/aws/s3/bucket.rb, line 303 def website_configuration resp = client.get_bucket_website(:bucket_name => name) WebsiteConfiguration.new(resp.data) rescue Errors::NoSuchWebsiteConfiguration nil end
Sets the website configuration. Deletes the configuration if `nil` is passed. @param [WebsiteConfiguration,nil] website_configuration
@see configure_website
@see website_configuration
@see remove_website_configuration
@see website?
# File lib/aws/s3/bucket.rb, line 317 def website_configuration= website_configuration if website_configuration client_opts = website_configuration.to_hash client_opts[:bucket_name] = name client.put_bucket_website(client_opts) else remove_website_configuration end end