You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::S3::BucketCollection

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/aws/s3/bucket_collection.rb

Overview

Represents a collection of buckets.

You can use this to create a bucket:

s3.buckets.create("mybucket")

You can get a handle for a specific bucket with indifferent access:

bucket = s3.buckets[:mybucket]
bucket = s3.buckets['mybucket']

You can also use it to find out which buckets are in your account:

s3.buckets.collect(&:name)
#=> ['bucket1', 'bucket2', ...]

Instance Method Summary collapse

Instance Method Details

#[](bucket_name) ⇒ Bucket

Returns the Bucket with the given name.

Makes no requests. The returned bucket object can be used to make requets for the bucket and its objects.

Examples:


bucket = s3.buckets[:mybucket],
bucket = s3.buckets['mybucket'],

Parameters:

  • bucket_name (String)

Returns:



126
127
128
 
# File 'lib/aws/s3/bucket_collection.rb', line 126

def [] bucket_name
  bucket_named(bucket_name)
end

#create(bucket_name, options = {}) ⇒ Bucket

Note:

If your bucket name contains one or more periods and it is hosted in a non-US region, you should make requests against the bucket using the S3 endpoint specific to the region in which your bucket resides. For example:

s3 = AWS::S3.new(:region => "eu-west-1")
bucket = s3.buckets.create("my.eu.bucket")

For a full list of endpoints and regions, see Regions and Endpoints in the Amazon Web Services General Reference.

Creates and returns a new Bucket. For example:

Examples:


bucket = s3.buckets.create('my-bucket')
bucket.name    #=> "my-bucket"
bucket.exists? #=> true

Parameters:

  • bucket_name (String)
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :location_constraint (String) — default: nil —

    The location where the bucket should be created. Defaults to the classic US region; however, if you configure a regional endpoint for Amazon S3 this option will default to the appropriate location constraint for the endpoint. For example:

    s3 = AWS::S3.new(:region => "us-west-1")
bucket = s3.buckets.create("my-us-west-bucket")
bucket.location_constraint # => "us-west-1"
  • :acl (Symbol, String) — default: :private —

    Sets the ACL of the bucket you are creating. Valid Values include: * :private * :public_read * :public_read_write * :authenticated_read * :log_delivery_write

  • :grant_read (String)
  • :grant_write (String)
  • :grant_read_acp (String)
  • :grant_write_acp (String)
  • :grant_full_control (String)

Returns:



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/aws/s3/bucket_collection.rb', line 91

def create bucket_name, options = {}

  # convert the symbolized-canned acl into the string version
  if acl = options[:acl]
    options[:acl] = acl.to_s.tr('_', '-')
  end

  # auto set the location constraint for the user if it is not
  # passed in and the endpoint is not the us-standard region.  don't
  # override the location constraint though, even it is wrong,
  unless
    config.s3_endpoint == 's3.amazonaws.com' or
    options[:location_constraint]
  then
    constraint = guess_constraint
    options[:location_constraint] = constraint if constraint
  end

  client.create_bucket(options.merge(:bucket_name => bucket_name))
  bucket_named(bucket_name)

end

#each(&block) ⇒ nil

Iterates the buckets in this collection.

Examples:


s3.buckets.each do |bucket|
  puts bucket.name
end

Returns:

  • (nil) 


139
140
141
142
143
144
145
 
# File 'lib/aws/s3/bucket_collection.rb', line 139

def each &block
  response = client.list_buckets
  response.buckets.each do |b|
    yield(bucket_named(b.name, response.owner))
  end
  nil
end