Class: AWS::S3::Bucket

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/s3/bucket.rb

Overview

Represents a single S3 bucket.

Examples:

Creating a Bucket


bucket = s3.buckets.create('mybucket')

Getting an Existing Bucket


bucket = s3.buckets['mybucket']

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options = {}) ⇒ Bucket

Returns a new instance of Bucket.

Parameters:

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

Options Hash (options):

  • :owner (String) — default: nil —

    The owner id of this bucket.



35
36
37
38
39
40
41
42
 
# File 'lib/aws/s3/bucket.rb', line 35

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

Instance Attribute Details

#name ⇒ String (readonly)

Returns The bucket name.

Returns:

  • (String) —

    The bucket name



45
46
47
 
# File 'lib/aws/s3/bucket.rb', line 45

def name
  @name
end

Instance Method Details

#==(other) ⇒ Boolean

Returns true if the two buckets have the same name.

Returns:

  • (Boolean) —

    Returns true if the two buckets have the same name.



138
139
140
 
# File 'lib/aws/s3/bucket.rb', line 138

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

Returns:



205
206
207
208
209
210
211
212
213
214
 
# File 'lib/aws/s3/bucket.rb', line 205

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.

Parameters:

  • acl (Symbol, String, Hash, AccessControlList) —

    Accepts an ACL description in one of the following formats:

    Canned ACL

    S3 supports a number of canned ACLs for buckets and objects. These include:

    • :private

    • :public_read

    • :public_read_write

    • :authenticated_read

    • :bucket_owner_read (object-only)

    • :bucket_owner_full_control (object-only)

    • :log_delivery_write (bucket-only)

    Here is an example of providing a canned ACL to a bucket:

    s3.buckets['bucket-name'].acl = :public_read

    ACL Grant Hash

    You can provide a hash of grants. The hash is composed of grants (keys) and grantees (values). Accepted grant keys are:

    • :grant_read

    • :grant_write

    • :grant_read_acp

    • :grant_write_acp

    • :grant_full_control

    Grantee strings (values) should be formatted like some of the following examples:

    id="8a6925ce4adf588a4532142d3f74dd8c71fa124b1ddee97f21c32aa379004fef"
uri="http://acs.amazonaws.com/groups/global/AllUsers"
emailAddress="[email protected]"

    You can provide a comma delimited list of multiple grantees in a single string. Please note the use of quotes inside the grantee string. Here is a simple example:

    {
  :grant_full_control => "emailAddress=\"[email protected]\", id=\"abc..mno\""
}

    See the S3 API documentation for more information on formatting grants.

    AcessControlList Object

    You can build an ACL using the AccessControlList class and pass this object.

    acl = AWS::S3::AccessControlList.new
acl.grant(:full_control).to(:canonical_user_id => "8a6...fef")
acl #=> this is acceptible

    ACL XML String

    Lastly you can build your own ACL XML document and pass it as a string.

    <<-XML
  <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
      <ID>8a6...fef</ID>
      <DisplayName>owner-display-name</DisplayName>
    </Owner>
    <AccessControlList>
      <Grant>
        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Canonical User">
          <ID>8a6...fef</ID>
          <DisplayName>owner-display-name</DisplayName>
        </Grantee>
        <Permission>FULL_CONTROL</Permission>
      </Grant>
    </AccessControlList>
  </AccessControlPolicy> 
XML

Returns:

  • (nil) 


220
221
222
223
 
# File 'lib/aws/s3/bucket.rb', line 220

def acl= acl
  client.set_bucket_acl(acl_options(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.

Parameters:

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

Options Hash (options):

  • :prefix (String) — default: 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.

  • :delimiter (String) — default: '/' —

    The string that separates each level of the tree. This is usually a directory separator.

  • :append (Boolean) — default: true —

    If true, the delimiter is appended to the prefix when the prefix does not already end with the delimiter.

Returns:

See Also:



373
374
375
 
# File 'lib/aws/s3/bucket.rb', line 373

def as_tree options = {}
  objects.as_tree(options)
end

#clear! ⇒ nil

Deletes all objects from this bucket.

Returns:

  • (nil) 


106
107
108
109
110
 
# File 'lib/aws/s3/bucket.rb', line 106

def clear!
  versions.each_batch do |versions|
    objects.delete(versions)
  end
end

#delete ⇒ nil

Deletes the current bucket. An error will be raised if the bucket is not empty.

Returns:

  • (nil) 


115
116
117
118
 
# File 'lib/aws/s3/bucket.rb', line 115

def delete
  client.delete_bucket(:bucket_name => @name)
  nil
end

#delete! ⇒ nil

Deletes all objects in a bucket and then deletes the bucket.

Returns:

  • (nil) 


122
123
124
125
 
# File 'lib/aws/s3/bucket.rb', line 122

def delete!
  clear!
  delete
end

#empty? ⇒ Boolean

Returns true if the bucket has no objects (this includes versioned objects that are delete markers).

Returns:

  • (Boolean) —

    Returns true if the bucket has no objects (this includes versioned objects that are delete markers).



59
60
61
 
# File 'lib/aws/s3/bucket.rb', line 59

def empty?
  versions.first ? false : true
end

#enable_versioning ⇒ nil

Enables versioning on this bucket.

Returns:

  • (nil) 


71
72
73
74
75
76
 
# File 'lib/aws/s3/bucket.rb', line 71

def enable_versioning
  client.set_bucket_versioning(
    :bucket_name => @name,
    :state => :enabled)
  nil
end

#eql?(other_bucket) ⇒ Boolean

Returns true if the two buckets have the same name

Returns:

  • (Boolean) —

    Returns true if the two buckets have the same name



143
144
145
 
# File 'lib/aws/s3/bucket.rb', line 143

def eql?(other_bucket)
  self == other_bucket
end

#exists? ⇒ Boolean

Note:

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.

Returns:

  • (Boolean) —

    Returns true if the bucket exists in S3.



150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/aws/s3/bucket.rb', line 150

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.

Examples:

Adding rules to a bucket’s lifecycle configuration


bucket.lifecycle_configuration.update do
  add_rule 'cache-1/', 30
  add_rule 'cache-2/', 30
end

Deleting the lifecycle configuration


bucket.lifecycle_configuration.clear

Returns:



302
303
304
 
# File 'lib/aws/s3/bucket.rb', line 302

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.

Parameters:

  • config (String, Object) —

    You can pass an xml string or any other object that responds to #to_xml (e.g. BucketLifecycleConfiguration).

Returns:

  • (nil) 


329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/aws/s3/bucket.rb', line 329

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.

Returns:

  • (String, nil) —

    Returns the location constraint for a bucket (if it has one), nil otherwise.



65
66
67
 
# File 'lib/aws/s3/bucket.rb', line 65

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.

Returns:



178
179
180
 
# File 'lib/aws/s3/bucket.rb', line 178

def multipart_uploads
  MultipartUploadCollection.new(self)
end

#objects ⇒ ObjectCollection

Returns Represents all objects(keys) in this bucket.

Returns:



166
167
168
 
# File 'lib/aws/s3/bucket.rb', line 166

def objects
  ObjectCollection.new(self)
end

#owner ⇒ String

Returns bucket owner id.

Returns:

  • (String) —

    bucket owner id



128
129
130
 
# File 'lib/aws/s3/bucket.rb', line 128

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.

Returns:

  • (Policy, nil) —

    Returns the bucket policy (if it has one), or it returns nil otherwise.



264
265
266
267
268
269
270
271
272
 
# File 'lib/aws/s3/bucket.rb', line 264

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.

Parameters:

  • 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.

Returns:

  • (nil)

See Also:



281
282
283
284
 
# File 'lib/aws/s3/bucket.rb', line 281

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.

See Also:



381
382
383
 
# File 'lib/aws/s3/bucket.rb', line 381

def presigned_post(options = {})
  PresignedPost.new(self, options)
end

#suspend_versioning ⇒ nil

Suspends versioning on this bucket.

Returns:

  • (nil) 


80
81
82
83
84
85
 
# File 'lib/aws/s3/bucket.rb', line 80

def suspend_versioning
  client.set_bucket_versioning(
    :bucket_name => @name,
    :state => :suspended)
  nil
end

#url ⇒ String

Returns the url for this bucket.

Returns:

  • (String) —

    url to the bucket



49
50
51
52
53
54
55
 
# File 'lib/aws/s3/bucket.rb', line 49

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.

Returns:

  • (Boolean) —

    returns true if version is enabled on this bucket.



88
89
90
 
# File 'lib/aws/s3/bucket.rb', line 88

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

Returns:

  • (Symbol) —

    the versioning state



100
101
102
 
# File 'lib/aws/s3/bucket.rb', line 100

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.

Returns:



172
173
174
 
# File 'lib/aws/s3/bucket.rb', line 172

def versions
  BucketVersionCollection.new(self)
end