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:

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:

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

name[R]

@return [String] The bucket name

Public Class Methods

new(name, options = {}) click to toggle source

@param [String] name @param [Hash] options @option options [String] :owner (nil) The owner id of this bucket.

Calls superclass method 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

==(other) click to toggle source

@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
acl() click to toggle source

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
acl=(acl) click to toggle source

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 575
def acl= acl
  client.set_bucket_acl(acl_options(acl).merge(:bucket_name => name))
  nil
end
as_tree(options = {}) click to toggle source

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
clear!() click to toggle source

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_website() { |website_config| ... } click to toggle source

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
cors() click to toggle source

@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
cors=(*rules) click to toggle source

Sets the bucket CORS rules. @param (see AWS::S3::CORSRuleCollection#set) @see AWS::S3::CORSRuleCollection#set

# File lib/aws/s3/bucket.rb, line 398
def cors= *rules
  self.cors.set(*rules)
end
delete() click to toggle source

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
delete!() click to toggle source

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
empty?() click to toggle source

@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
enable_versioning(opts = {}) click to toggle source

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
eql?(other_bucket) click to toggle source

@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
exists?() click to toggle source

@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
inspect() click to toggle source

@api private

# File lib/aws/s3/bucket.rb, line 488
def inspect
  "#<AWS::S3::Bucket:#{name}>"
end
lifecycle_configuration() click to toggle source

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
lifecycle_configuration=(config) click to toggle source

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
location_constraint() click to toggle source

@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
multipart_uploads() click to toggle source

@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
objects() click to toggle source

@return [ObjectCollection] Represents all objects(keys) in

this bucket.
# File lib/aws/s3/bucket.rb, line 521
def objects
  ObjectCollection.new(self)
end
owner() click to toggle source

@return [String] bucket owner id

# File lib/aws/s3/bucket.rb, line 483
def owner
  @owner || client.list_buckets.owner
end
policy() click to toggle source

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
policy=(policy) click to toggle source

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
presigned_post(options = {}) click to toggle source

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
remove_website_configuration() click to toggle source

@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
suspend_versioning(opts = {}) click to toggle source

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
tags() click to toggle source

Returns the tags for this bucket.

tags = bucket.tags
#=> <AWS::S3::BucketTagCollection>

# adds a tag to the bucket
tags['foo'] = 'abc'

# replaces all tags
tags.set('new' => 'tags')

# removes all tags from the bucket
tags.clear

# returns tags as a hash
tags.to_h

@return [BucketTagCollection] Returns a collection that represents

the tags for this bucket.
# File lib/aws/s3/bucket.rb, line 368
def tags
  BucketTagCollection.new(self)
end
tags=(tags) click to toggle source

Sets the tags for this bucket.

bucket.tags = { 'contents' => 'photots' }

You can remove all tags for the bucket by passing an empty hash or `nil`.

bucket.tags = nil # {} also deletes all tags
bucket.tags
#=> {}

@param [Hash,nil] tags The tags to set on this bucket.

# File lib/aws/s3/bucket.rb, line 385
def tags= tags
  self.tags.set(tags)
end
url(options = {}) click to toggle source

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
versioned?()
Alias for: versioning_enabled?
versioning_enabled?() click to toggle source

@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
Also aliased as: versioned?
versioning_state() click to toggle source

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
versions() click to toggle source

@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
website?() click to toggle source

@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
website_configuration() click to toggle source

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
website_configuration=(website_configuration) click to toggle source

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