Net::Amazon::S3

This library implements the Amazon S3 REST API (Rubyfied for your pleasure). Its usage is hopefully pretty straightforward. See below for examples.

Author:	Ryan Grove (ryan@wonko.com)
Version:	0.1.0
Copyright:	Copyright (c) 2006 Ryan Grove. All rights reserved.
License:	New BSD License (opensource.org/licenses/bsd-license.php)
Website:	wonko.com/software/net-amazon-s3

A Brief Overview of Amazon S3

Amazon S3 stores arbitrary values (objects) identified by keys and organized into buckets. An S3 bucket is essentially a glorified Hash. Object values can be up to 5 GB in size, and objects can also have up to 2 KB of metadata associated with them.

Bucket names share a global namespace and must be unique across all of S3, but object keys only have to be unique within the bucket in which they are stored.

For more details, visit s3.amazonaws.com

Installation

  gem install net-amazon-s3

Examples

Create an instance of the S3 client

  require 'rubygems'
  require 'net/amazon/s3'

  access_key_id     = 'DXM37ARQ25519H34E6W2'
  secret_access_key = '43HM88c+8kYr/UeFp+shjTnzFgisO5AZzpEO06FU'

  s3 = Net::Amazon::S3.new(access_key_id, secret_access_key)

Create a bucket and add an object to it

  foo = s3.create_bucket('foo')
  foo['bar'] = 'baz'            # create object 'bar' and assign it the
                                # value 'baz'

Upload a large file to the bucket

  File.open('mybigmovie.avi', 'rb') do |file|
    foo['mybigmovie.avi'] = file
  end

Download a large file from the bucket

  File.open('mybigmovie.avi', 'wb') do |file|
    foo['mybigmovie.avi'].value {|chunk| file.write(chunk) }
  end

Get a hash containing all objects in the bucket

  objects = foo.get_objects

Get all objects in the bucket whose keys begin with "my"

  my_objects = foo.get_objects('my')

Delete the bucket and everything in it

  s3.delete_bucket('foo', true)

TODO

Owner support
Object metadata support
ACLs
Logging configuration

Methods

[] bucket_exist? create_bucket delete_bucket each error? get_bucket get_buckets has_bucket? new request_delete request_get request_head request_put

Classes and Modules

Class Net::Amazon::S3::Bucket
Class Net::Amazon::S3::Object
Class Net::Amazon::S3::S3Error

Constants

REST_ENDPOINT = 's3.amazonaws.com'

Attributes

 access_key_id
 options
 secret_access_key

Public Class methods

new(access_key_id, secret_access_key, options = {})

Creates and returns a new S3 client. The following options are available:

:enable_cache: Set to true to enable intelligent caching of frequently-used requests. This can improve performance, but may result in staleness if other clients are simultaneously modifying the buckets and objects in this S3 account. Default is true.
:ssl: Set to true to use SSL for all requests. No verification is performed on the server‘s certificate when SSL is used. Default is true.

Public Instance methods

[](bucket_name)

Alias for get_bucket

bucket_exist?(bucket_name)

Returns true if a bucket with the specified bucket_name exists in this S3 account, false otherwise.

create_bucket(bucket_name)

Creates a new bucket with the specified bucket_name and returns a Bucket object representing it.

delete_bucket(bucket_name, recursive = false)

Deletes the bucket with the specified bucket_name. If recursive is true, all objects contained in the bucket will also be deleted. If recursive is false and the bucket is not empty, a S3Error::BucketNotEmpty error will be raised.

each() {|key, value| ...}

Iterates through the list of buckets.

error?(response)

Raises the appropriate error if the specified Net::HTTPResponse object contains an Amazon S3 error; returns false otherwise.

get_bucket(bucket_name)

Returns a Bucket object representing the specified bucket, or nil if the bucket doesn‘t exist.

get_buckets()

Gets a list of all buckets owned by this account. Returns a Hash of Bucket objects indexed by bucket name.

has_bucket?(bucket_name)

Alias for bucket_exist?

request_delete(path, headers = {})

Sends a properly-signed DELETE request to the specified S3 path and returns a Net::HTTPResponse object.

request_get(path, headers = {}) {|response| ...}

Sends a properly-signed GET request to the specified S3 path and returns a Net::HTTPResponse object.

When called with a block, yields a Net::HTTPResponse object whose body has not been read; the caller can process it using Net::HTTPResponse.read_body.

request_head(path, headers = {})

Sends a properly-signed HEAD request to the specified S3 path and returns a Net::HTTPResponse object.

request_put(path, content = nil, headers = {})

Sends a properly-signed PUT request to the specified S3 path and returns a Net::HTTPResponse object.

If content is an open IO stream, the body of the request will be read from the stream.