NAME
Net::Amazon::S3 - Use the Amazon S3 - Simple Storage Service
SYNOPSIS
use Net::Amazon::S3;
# this synopsis is presented as a test file
my $s3 = Net::Amazon::S3->new(
{ aws_access_key_id => $aws_access_key_id,
aws_secret_access_key => $aws_secret_access_key
}
);
# you can also pass a timeout in seconds
# list all buckets that i own
my $response = $s3->buckets;
is( $response->{owner_id}, '46a801915a1711f...' );
is( $response->{owner_displayname}, '_acme_' );
is_deeply($response->{buckets}, []);
# create a bucket
my $bucketname = $aws_access_key_id . '-net-amazon-s3-test';
my $bucket_obj = $s3->add_bucket( { bucket => $bucketname } )
or die $s3->err . ": " . $s3->errstr;
is(ref $bucket_obj, "Net::Amazon::S3::Bucket");
# another way to get a bucket object (does no network I/O,
# assumes it already exists). Read Net::Amazon::S3::Bucket.
$bucket_obj = $s3->bucket("named_bucket");
is( ref $bucket_obj, "Net::Amazon::S3::Bucket" );
# fetch contents of the bucket
# note prefix, marker, max_keys options can be passed in
$response = $bucket->list
or die $s3->err . ": " . $s3->errstr;
is( $response->{bucket}, $bucketname );
is( $response->{prefix}, '' );
is( $response->{marker}, '' );
is( $response->{max_keys}, 1_000 );
is( $response->{is_truncated}, 0 );
is_deeply( $response->{keys}, [] );
# store a key with a content-type and some optional metadata
my $keyname = 'testing.txt';
my $value = 'T';
$bucket->add_key($key, $value, {
content_type => 'text/plain',
'x-amz-meta-colour' => 'orange',
});
# list keys in the bucket
$response = $bucket->list
or die $s3->err . ": " . $s3->errstr;
is( $response->{bucket}, $bucketname );
is( $response->{prefix}, '' );
is( $response->{marker}, '' );
is( $response->{max_keys}, 1_000 );
is( $response->{is_truncated}, 0 );
my @keys = @{ $response->{keys} };
is( @keys, 1 );
my $key = $keys[0];
is( $key->{key}, $keyname );
# the etag is the MD5 of the value
is( $key->{etag}, 'b9ece18c950afbfa6b0fdbfa4ff731d3' );
is( $key->{size}, 1 );
is( $key->{owner_id}, '46a801915a1711f...');
is( $key->{owner_displayname}, '_acme_' );
# see more docs in Net::Amazon::S3::Bucket
DESCRIPTION
This module provides a Perlish interface to Amazon S3. From the
developer blurb: "Amazon S3 is storage for the Internet. It is designed
to make web-scale computing easier for developers. Amazon S3 provides a
simple web services interface that can be used to store and retrieve any
amount of data, at any time, from anywhere on the web. It gives any
developer access to the same highly scalable, reliable, fast,
inexpensive data storage infrastructure that Amazon uses to run its own
global network of web sites. The service aims to maximize benefits of
scale and to pass those benefits on to developers".
To find out more about S3, please visit:
http://s3.amazonaws.com/
To use this module you will need to sign up to Amazon Web Services and
provide an "Access Key ID" and " Secret Access Key". If you use this
module, you will incurr costs as specified by Amazon. Please check the
costs. If you use this module with your Access Key ID and Secret Access
Key you must be responsible for these costs.
I highly recommend reading all about S3, but in a nutshell data is
stored in values. Values are referenced by keys, and keys are stored in
buckets. Bucket names are global.
Some features, such as ACLs, are not yet implemented. Patches welcome!
ABOUT
This module contains code modified from Amazon that contains the
following notice:
# This software code is made available "AS IS" without warranties of any
# kind. You may copy, display, modify and redistribute the software
# code either by itself or as incorporated into your code; provided that
# you do not remove any proprietary notices. Your use of this software
# code is at your own risk and you waive any claim against Amazon
# Digital Services, Inc. or its affiliates with respect to your use of
# this software code. (c) 2006 Amazon Digital Services, Inc. or its
# affiliates.
AUTHOR
Leon Brocard <
[email protected]> and unknown Amazon Digital Services
programmers.
Brad Fitzpatrick <
[email protected]> - return values, Bucket object
SEE ALSO
Net::Amazon::S3::Bucket
