Class | AWS::S3::Bucket |
In: |
lib/aws/s3/bucket.rb
|
Parent: | Object |
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.
name | [R] | @return [String] The bucket name |
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]
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]
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]
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?
@return [CORSRuleCollection] Returns a collection that can be
used to manage (add, edit and delete) CORS rules for this bucket.
Sets the bucket CORS rules. @param (see CORSRuleCollection#set) @see CORSRuleCollection#set
@return [Boolean] Returns true if the bucket has no objects
(this includes versioned objects that are delete markers).
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]
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]
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]
@return [MultipartUploadCollection] Represents all of the
multipart uploads that are in progress for this bucket.
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.
Generates fields for a presigned POST to this object. All options are sent to the PresignedPost constructor.
@see PresignedPost
@return [nil] Deletes the bucket website configuration. @see configure_website @see website_configuration @see website_configuration= @see website?
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]
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.
Returns the versioning status for this bucket. States include:
@return [Symbol] the versioning state
@return [BucketVersionCollection] Represents all of the versioned
objects stored in this bucket.
@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
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?
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?