Provides an expressive, object-oriented interface to Amazon S3.
To use Amazon S3 you must first [sign up here](aws.amazon.com/s3/).
For more information about Amazon S3, see:
# Credentials
You can setup default credentials for all AWS services via AWS.config:
AWS.config( :access_key_id => 'YOUR_ACCESS_KEY_ID', :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
Or you can set them directly on the S3 interface:
s3 = AWS::S3.new( :access_key_id => 'YOUR_ACCESS_KEY_ID', :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
# Buckets
Before you can upload files to S3, you need to create a bucket.
s3 = AWS::S3.new bucket = s3.buckets.create('my-bucket')
If a bucket already exists, you can get a reference to the bucket.
bucket = s3.buckets['my-bucket'] # no request made
You can also enumerate all buckets in your account.
s3.buckets.each do |bucket| puts bucket.name end
See {BucketCollection} and {Bucket} for more information on working with buckets.
# Objects
Buckets contain objects. Each object in a bucket has a unique key.
## Getting an Object
If the object already exists, you can get a reference to the object.
# makes no request, returns an AWS::S3::S3Object obj = bucket.objects['key']
## Reading and Writing an Object
The example above returns an {S3Object}. You call {S3Object#write} and {S3Object#read} to upload to and download from S3 respectively.
# streaming upload a file to S3 obj.write(Pathname.new('/path/to/file.txt')) # streaming download from S3 to a file on disk File.open('file.txt', 'wb') do |file| obj.read do |chunk| file.write(chunk) end end
## Enumerating Objects
You can enumerate objects in your buckets.
# enumerate ALL objects in the bucket (even if the bucket contains # more than 1k objects) bucket.objects.each do |obj| puts obj.key end # enumerate at most 20 objects with the given prefix bucket.objects.with_prefix('photos/').each(:limit => 20) do |photo| puts photo.key end
See {ObjectCollection} and {S3Object} for more information on working with objects.
GetBucketAcl | = | GetObjectAcl = BaseGrammar.customize do element "AccessControlList" do ignore |
@return [BucketCollection] Returns a collection that represents all
buckets in the account.
Generates fields for a presigned POST to this object. This method adds a constraint that the key must match the key of this object. All options are sent to the PresignedPost constructor.
@see PresignedPost @return [PresignedPost]
Generates a public (not authenticated) URL for the object.
@param [Hash] options Options for generating the URL.
@option options [Boolean] :secure Whether to generate a
secure (HTTPS) URL or a plain HTTP url.
@return [URI::HTTP, URI::HTTPS]
@note Changing the storage class of an object incurs a COPY
operation.
Changes the storage class of the object to enable or disable Reduced Redundancy Storage (RRS).
@param [true,false] value If this is true, the object will be
copied in place and stored with reduced redundancy at a lower cost. Otherwise, the object will be copied and stored with the standard storage class.
@return [true,false] The `value` parameter.
Generates a presigned URL for an operation on this object. This URL can be used by a regular HTTP client to perform the desired operation without credentials and without changing the permissions of the object.
@example Generate a url to read an object
bucket.objects.myobject.url_for(:read)
@example Generate a url to delete an object
bucket.objects.myobject.url_for(:delete)
@example Override response headers for reading an object
object = bucket.objects.myobject url = object.url_for(:read, :response_content_type => "application/json")
@example Generate a url that expires in 10 minutes
bucket.objects.myobject.url_for(:read, :expires => 10*60)
@param [Symbol, String] method The HTTP verb or object
method for which the returned URL will be valid. Valid values: * `:get` or `:read` * `:put` or `:write` * `:delete` * `:head`
@param [Hash] options Additional options for generating the URL.
@option options :expires Sets the expiration time of the
URL; after this time S3 will return an error if the URL is used. This can be an integer (to specify the number of seconds after the current time), a string (which is parsed as a date using Time#parse), a Time, or a DateTime object. This option defaults to one hour after the current time.
@option options [Boolean] :secure (true) Whether to generate a
secure (HTTPS) URL or a plain HTTP url.
@option options [String] :content_type Object content type for
HTTP PUT. When provided, has to be also added to the request header as a 'content-type' field
@option options [String] :content_md5 Object MD5 hash for HTTP PUT.
When provided, has to be also added to the request header as a 'content-md5' field
@option options [String] :endpoint Sets the hostname of the
endpoint.
@option options [Integer] :port Sets the port of the
endpoint (overrides config.s3_port).
@option options [Boolean] :force_path_style (false) Indicates
whether the generated URL should place the bucket name in the path (true) or as a subdomain (false).
@option options [String] :response_content_type Sets the
Content-Type header of the response when performing an HTTP GET on the returned URL.
@option options [String] :response_content_language Sets the
Content-Language header of the response when performing an HTTP GET on the returned URL.
@option options [String] :response_expires Sets the Expires
header of the response when performing an HTTP GET on the returned URL.
@option options [String] :response_cache_control Sets the
Cache-Control header of the response when performing an HTTP GET on the returned URL.
@option options [String] :response_content_disposition Sets
the Content-Disposition header of the response when performing an HTTP GET on the returned URL.
@option options [String] :acl The value to use for the
x-amz-acl.
@option options [String] :response_content_encoding Sets the
Content-Encoding header of the response when performing an HTTP GET on the returned URL.
@option options [:v3, :v4] :signature_version (:v3)
@return [URI::HTTP, URI::HTTPS]