Class: Aws::S3::Bucket
Instance Attribute Summary collapse
-
#creation_date ⇒ Object
readonly
Returns the value of attribute creation_date.
-
#name ⇒ Object
readonly
Returns the value of attribute name.
-
#owner ⇒ Object
readonly
Returns the value of attribute owner.
-
#s3 ⇒ Object
readonly
Returns the value of attribute s3.
Class Method Summary collapse
-
.create(s3, name, create = false, perms = nil, headers = {}) ⇒ Object
Create a Bucket instance.
Instance Method Summary collapse
-
#clear ⇒ Object
Remove all keys from a bucket.
-
#copy_key(old_key_or_name, new_key_or_name) ⇒ Object
Create an object copy.
-
#delete(force = false) ⇒ Object
Delete a bucket.
-
#delete_folder(folder, separator = '/') ⇒ Object
Delete all keys where the ‘folder_key’ can be interpreted as a ‘folder’ name.
-
#disable_logging ⇒ Object
Disables S3 server access logging on a bucket.
-
#enable_logging(params) ⇒ Object
Enables S3 server access logging on a bucket.
-
#get(key, headers = {}) ⇒ Object
Retrieve object data from Amazon.
-
#grantees ⇒ Object
Return a list of grantees.
-
#initialize(s3, name, creation_date = nil, owner = nil) ⇒ Bucket
constructor
Create a bucket instance.
-
#key(key_name, head = false) ⇒ Object
Retrieve key information from Amazon.
-
#keys(options = {}, head = false) ⇒ Object
Retrieve a group of keys from Amazon.
-
#keys_and_service(options = {}, head = false) ⇒ Object
Same as
keys
method but return an array of [keys, service_data]. -
#location ⇒ Object
Returns the bucket location.
-
#logging_info ⇒ Object
Retrieves the logging configuration for a bucket.
-
#move_key(old_key_or_name, new_key_or_name) ⇒ Object
Move an object to other location.
-
#public_link ⇒ Object
Return a public link to bucket.
-
#put(key, data = nil, meta_headers = {}, perms = nil, headers = {}) ⇒ Object
Store object data.
-
#rename_key(old_key_or_name, new_name) ⇒ Object
Rename object.
-
#to_s ⇒ Object
(also: #full_name)
Return bucket name as a String.
Constructor Details
#initialize(s3, name, creation_date = nil, owner = nil) ⇒ Bucket
Create a bucket instance. In normal use this method should not be called directly. Use Aws::S3::Bucket.create or Aws::S3.bucket instead.
142 143 144 145 146 147 148 149 150 |
# File 'lib/s3/right_s3.rb', line 142 def initialize(s3, name, creation_date=nil, owner=nil) @s3 = s3 @name = name @owner = owner @creation_date = creation_date if @creation_date && !@creation_date.is_a?(Time) @creation_date = Time.parse(@creation_date) end end |
Instance Attribute Details
#creation_date ⇒ Object (readonly)
Returns the value of attribute creation_date.
112 113 114 |
# File 'lib/s3/right_s3.rb', line 112 def creation_date @creation_date end |
#name ⇒ Object (readonly)
Returns the value of attribute name.
112 113 114 |
# File 'lib/s3/right_s3.rb', line 112 def name @name end |
#owner ⇒ Object (readonly)
Returns the value of attribute owner.
112 113 114 |
# File 'lib/s3/right_s3.rb', line 112 def owner @owner end |
#s3 ⇒ Object (readonly)
Returns the value of attribute s3.
112 113 114 |
# File 'lib/s3/right_s3.rb', line 112 def s3 @s3 end |
Class Method Details
.create(s3, name, create = false, perms = nil, headers = {}) ⇒ Object
Create a Bucket instance. If the bucket does not exist and create
is set, a new bucket is created on S3. Launching this method with create
=true
may affect on the bucket’s ACL if the bucket already exists. Returns Bucket instance or nil
if the bucket does not exist and create
is not set.
s3 = Aws::S3.new(aws_access_key_id, aws_secret_access_key)
...
bucket1 = Aws::S3::Bucket.create(s3, 'my_awesome_bucket_1')
bucket1.keys #=> exception here if the bucket does not exists
...
bucket2 = Aws::S3::Bucket.create(s3, 'my_awesome_bucket_2', true)
bucket2.keys #=> list of keys
# create a bucket at the European location with public read access
bucket3 = Aws::S3::Bucket.create(s3,'my-awesome-bucket-3', true, 'public-read', :location => :eu)
see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html
(section: Canned Access Policies)
134 135 136 |
# File 'lib/s3/right_s3.rb', line 134 def self.create(s3, name, create=false, perms=nil, headers={}) s3.bucket(name, create, perms, headers) end |
Instance Method Details
#clear ⇒ Object
Remove all keys from a bucket. Returns true
.
bucket.clear #=> true
333 334 335 |
# File 'lib/s3/right_s3.rb', line 333 def clear @s3.interface.clear_bucket(@name) end |
#copy_key(old_key_or_name, new_key_or_name) ⇒ Object
Create an object copy. Returns a destination Aws::S3::Key instance.
new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
puts key.name #=> 'logs/today/2.log'
key.exists? #=> true
312 313 314 315 |
# File 'lib/s3/right_s3.rb', line 312 def copy_key(old_key_or_name, new_key_or_name) old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key) old_key_or_name.copy(new_key_or_name) end |
#delete(force = false) ⇒ Object
Delete a bucket. Bucket must be empty. If force
is set, clears and deletes the bucket. Returns true
.
bucket.delete(true) #=> true
354 355 356 |
# File 'lib/s3/right_s3.rb', line 354 def delete(force=false) force ? @s3.interface.force_delete_bucket(@name) : @s3.interface.delete_bucket(@name) end |
#delete_folder(folder, separator = '/') ⇒ Object
Delete all keys where the ‘folder_key’ can be interpreted as a ‘folder’ name. Returns an array of string keys that have been deleted.
bucket.keys.map{|key| key.name}.join(', ') #=> 'test, test/2/34, test/3, test1, test1/logs'
bucket.delete_folder('test') #=> ['test','test/2/34','test/3']
344 345 346 |
# File 'lib/s3/right_s3.rb', line 344 def delete_folder(folder, separator='/') @s3.interface.delete_folder(@name, folder, separator) end |
#disable_logging ⇒ Object
Disables S3 server access logging on a bucket. Takes no arguments.
201 202 203 204 |
# File 'lib/s3/right_s3.rb', line 201 def disable_logging xmldoc = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><BucketLoggingStatus xmlns=\"http://doc.s3.amazonaws.com/2006-03-01\"></BucketLoggingStatus>" @s3.interface.put_logging(:bucket => @name, :xmldoc => xmldoc) end |
#enable_logging(params) ⇒ Object
Enables S3 server access logging on a bucket. The target bucket must have been properly configured to receive server access logs.
Params:
:targetbucket - either the target bucket object or the name of the target bucket
:targetprefix - the prefix under which all logs should be stored
bucket.enable_logging(:targetbucket=>"mylogbucket", :targetprefix=>"loggylogs/")
=> true
193 194 195 196 197 198 |
# File 'lib/s3/right_s3.rb', line 193 def enable_logging(params) AwsUtils.mandatory_arguments([:targetbucket, :targetprefix], params) AwsUtils.allow_only([:targetbucket, :targetprefix], params) xmldoc = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><BucketLoggingStatus xmlns=\"http://doc.s3.amazonaws.com/2006-03-01\"><LoggingEnabled><TargetBucket>#{params[:targetbucket]}</TargetBucket><TargetPrefix>#{params[:targetprefix]}</TargetPrefix></LoggingEnabled></BucketLoggingStatus>" @s3.interface.put_logging(:bucket => @name, :xmldoc => xmldoc) end |
#get(key, headers = {}) ⇒ Object
Retrieve object data from Amazon. The key
is a String
or Key. Returns Key instance.
key = bucket.get('logs/today/1.log') #=>
puts key.data #=> 'sasfasfasdf'
289 290 291 292 |
# File 'lib/s3/right_s3.rb', line 289 def get(key, headers={}) key = Key.create(self, key.to_s) unless key.is_a?(Key) key.get(headers) end |
#grantees ⇒ Object
Return a list of grantees.
360 361 362 |
# File 'lib/s3/right_s3.rb', line 360 def grantees Grantee::grantees(self) end |
#key(key_name, head = false) ⇒ Object
Retrieve key information from Amazon. The key_name
is a String
or Key instance. Retrieves meta-header information if head
is true
. Returns new Key instance.
key = bucket.key('logs/today/1.log', true) #=> #<Aws::S3::Key:0xb7b1e240 ... >
# is the same as:
key = Aws::S3::Key.create(bucket, 'logs/today/1.log')
key.head
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 |
# File 'lib/s3/right_s3.rb', line 254 def key(key_name, head=false) raise 'Key name can not be empty.' if key_name.blank? key_instance = nil # if this key exists - find it .... keys({'prefix'=>key_name}, head).each do |key| if key.name == key_name.to_s key_instance = key break end end # .... else this key is unknown unless key_instance key_instance = Key.create(self, key_name.to_s) end key_instance end |
#keys(options = {}, head = false) ⇒ Object
Retrieve a group of keys from Amazon. options
is a hash: { ‘prefix’=>”, ‘marker’=>”, ‘max-keys’=>5, ‘delimiter’=>” }). Retrieves meta-headers information if head
it true
. Returns an array of Key instances.
bucket.keys #=> # returns all keys from bucket
bucket.keys('prefix' => 'logs') #=> # returns all keys that starts with 'logs'
214 215 216 |
# File 'lib/s3/right_s3.rb', line 214 def keys(={}, head=false) keys_and_service(, head)[0] end |
#keys_and_service(options = {}, head = false) ⇒ Object
Same as keys
method but return an array of [keys, service_data]. where service_data
is a hash with additional output information.
keys, service = bucket.keys_and_service({'max-keys'=> 2, 'prefix' => 'logs'})
p keys #=> # 2 keys array
p service #=> {"max-keys"=>"2", "prefix"=>"logs", "name"=>"my_awesome_bucket", "marker"=>"", "is_truncated"=>true}
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 |
# File 'lib/s3/right_s3.rb', line 225 def keys_and_service(={}, head=false) opt = {}; .each{ |key, value| opt[key.to_s] = value } service_data = {} thislist = {} list = [] @s3.interface.incrementally_list_bucket(@name, opt) do |thislist| thislist[:contents].each do |entry| owner = Owner.new(entry[:owner_id], entry[:owner_display_name]) key = Key.new(self, entry[:key], nil, {}, {}, entry[:last_modified], entry[:e_tag], entry[:size], entry[:storage_class], owner) key.head if head list << key end end thislist.each_key do |key| service_data[key] = thislist[key] unless (key == :contents || key == :common_prefixes) end [list, service_data] end |
#location ⇒ Object
Returns the bucket location
172 173 174 |
# File 'lib/s3/right_s3.rb', line 172 def location @location ||= @s3.interface.bucket_location(@name) end |
#logging_info ⇒ Object
Retrieves the logging configuration for a bucket. Returns a hash of :targetbucket, :targetprefix
bucket.logging_info()
=> {:enabled=>true, :targetbucket=>"mylogbucket", :targetprefix=>"loggylogs/"}
181 182 183 |
# File 'lib/s3/right_s3.rb', line 181 def logging_info @s3.interface.get_logging_parse(:bucket => @name) end |
#move_key(old_key_or_name, new_key_or_name) ⇒ Object
Move an object to other location. Returns a destination Aws::S3::Key instance.
new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
puts key.name #=> 'logs/today/2.log'
key.exists? #=> true
323 324 325 326 |
# File 'lib/s3/right_s3.rb', line 323 def move_key(old_key_or_name, new_key_or_name) old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key) old_key_or_name.move(new_key_or_name) end |
#public_link ⇒ Object
Return a public link to bucket.
bucket.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket'
166 167 168 169 |
# File 'lib/s3/right_s3.rb', line 166 def public_link params = @s3.interface.params "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name}" end |
#put(key, data = nil, meta_headers = {}, perms = nil, headers = {}) ⇒ Object
Store object data. The key
is a String
or Key instance. Returns true
.
bucket.put('logs/today/1.log', 'Olala!') #=> true
277 278 279 280 |
# File 'lib/s3/right_s3.rb', line 277 def put(key, data=nil, ={}, perms=nil, headers={}) key = Key.create(self, key.to_s, data, ) unless key.is_a?(Key) key.put(data, perms, headers) end |
#rename_key(old_key_or_name, new_name) ⇒ Object
Rename object. Returns Aws::S3::Key instance.
new_key = bucket.rename_key('logs/today/1.log','logs/today/2.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
puts key.name #=> 'logs/today/2.log'
key.exists? #=> true
300 301 302 303 304 |
# File 'lib/s3/right_s3.rb', line 300 def rename_key(old_key_or_name, new_name) old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key) old_key_or_name.rename(new_name) old_key_or_name end |