Class | AWS::S3::ObjectCollection |
In: |
lib/aws/s3/object_collection.rb
|
Parent: | Object |
Represents a collection of S3 objects.
## Getting an S3Object by Key
If you know the key of the object you want, you can reference it this way:
# this will not make any requests against S3 object = bucket.objects['foo.jpg'] object.key #=> 'foo.jpg'
## Finding objects with a Prefix
Given a bucket with the following keys:
photos/sunset.jpg photos/sunrise.jpg photos/winter.jpg videos/comedy.mpg videos/dancing.mpg
You can list objects that share a prefix:
bucket.objects.with_prefix('videos').collect(&:key) #=> ['videos/comedy.mpg', 'videos/dancing.mpg']
## Exploring Objects with a Tree Interface
Given a bucket with the following keys:
README.txt videos/wedding.mpg videos/family_reunion.mpg photos/2010/house.jpg photos/2011/fall/leaves.jpg photos/2011/summer/vacation.jpg photos/2011/summer/family.jpg tree = bucket.objects.with_prefix('photos').as_tree directories = tree.children.select(&:branch?).collect(&:prefix) #=> ['photos/2010', 'photos/2011']
bucket | [R] | @return [Bucket] The bucket this collection belongs to. |
The first param is the key you want to write this object to. All other params/options are documented in {S3Object#write}.
@see S3Object#write
@param [String] key Where in S3 to write the object. @return (see S3Object#write)
Deletes the objects provided in as few requests as possible.
# delete 2 objects (by key) in a single request bucket.objects.delete('abc', 'xyz')
You can delete objects also by passing their S3Object representation:
to_delete = [] to_delete << buckets.objects['foo'] to_delete << buckets.objects['bar'] bucket.objects.delete(to_delete)
@overload delete(objects)
@param [Mixed] objects One or more objects to delete. Each object can be one of the following: * An object key (string) * A hash with :key and :version_id (for versioned objects) * An {S3Object} instance * An {ObjectVersion} instance
@overload delete(objects, options)
Deletes multiple objects, with additional options. The array can contain any of the types of objects the first method invocation style accepts. @param [Array] objects One or more objects to delete. @param [Hash] options Optional headers to pass on.
@raise [BatchDeleteError] If any of the objects failed to delete,
a BatchDeleteError will be raised with a summary of the errors.
@return [nil]
Deletes all objects represented by this collection.
@example Delete all objects from a bucket
bucket.objects.delete_all
@example Delete objects with a given prefix
bucket.objects.with_prefix('2009/').delete_all
@raise [BatchDeleteError] If any of the objects failed to delete,
a BatchDeleteError will be raised with a summary of the errors.
@return [Array] Returns an array of results
Deletes each object in the collection that returns a true value from block passed to this method. Deletes are batched for efficiency.
# delete text files in the 2009 "folder" bucket.objects.with_prefix('2009/').delete_if {|o| o.key =~ /\.txt$/ }
@yieldparam [S3Object] object
@raise [BatchDeleteError] If any of the objects failed to delete,
a BatchDeleteError will be raised with a summary of the errors.
Iterates the collection, yielding instances of S3Object.
Use break or raise an exception to terminate the enumeration.
@param [Hash] options @option options [Integer] :limit (nil) The maximum number of
objects to yield.
@option options [Integer] :batch_size (1000) The number of objects to
fetch each request to S3. Maximum is 1000 keys at time.
@return [nil]