NAME
AWS::S3 - Lightweight interface to Amazon S3 (Simple Storage Service)
SYNOPSIS
use AWS::S3;
my $s3 = AWS::S3->new(
access_key_id => 'E654SAKIASDD64ERAF0O',
secret_access_key => 'LgTZ25nCD+9LiCV6ujofudY1D6e2vfK0R4GLsI4H',
honor_leading_slashes => 0, # set to allow leading slashes in bucket names, defaults to 0
);
# Add a bucket:
my $bucket = $s3->add_bucket(
name => 'foo-bucket',
);
# Set the acl:
$bucket->acl( 'private' );
# Add a file:
my $new_file = $bucket->add_file(
key => 'foo/bar.txt',
contents => \'This is the contents of the file',
);
# You can also set the contents with a coderef:
# Coderef should eturn a reference, not the actual string of content:
$new_file = $bucket->add_file(
key => 'foo/bar.txt',
contents => sub { return \"This is the contents" }
);
# Get the file:
my $same_file = $bucket->file( 'foo/bar.txt' );
# Get the contents:
my $scalar_ref = $same_file->contents;
print $$scalar_ref;
# Update the contents with a scalar ref:
$same_file->contents( \"New file contents" );
# Update the contents with a code ref:
$same_file->contents( sub { return \"New file contents" } );
# Delete the file:
$same_file->delete();
# Iterate through lots of files:
my $iterator = $bucket->files(
page_size => 100,
page_number => 1,
);
while( my @files = $iterator->next_page )
{
warn "Page number: ", $iterator->page_number, "\n";
foreach my $file ( @files )
{
warn "\tFilename (key): ", $file->key, "\n";
warn "\tSize: ", $file->size, "\n";
warn "\tETag: ", $file->etag, "\n";
warn "\tContents: ", ${ $file->contents }, "\n";
}# end foreach()
}# end while()
# You can't delete a bucket until it's empty.
# Empty a bucket like this:
while( my @files = $iterator->next_page )
{
map { $_->delete } @files;
# Return to page 1:
$iterator->page_number( 1 );
}# end while()
# Now you can delete the bucket:
$bucket->delete();DESCRIPTION
AWS::S3 attempts to provide an alternate interface to the Amazon S3 Simple Storage Service.
NOTE: Until AWS::S3 gets to version 1.000 it will not implement the full S3 interface.
Disclaimer: Several portions of AWS::S3 have been adopted from Net::Amazon::S3.
NOTE: AWS::S3 is NOT a drop-in replacement for Net::Amazon::S3.
TODO: CloudFront integration.
CONSTRUCTOR
Call new() with the following parameters.
access_key_id
Required. String.
Provided by Amazon, this is your access key id.
secret_access_key
Required. String.
Provided by Amazon, this is your secret access key.
secure
Optional. Boolean.
Default is 0
endpoint
Optional. String.
Default is s3.amazonaws.com
ua
Optional. Should be an instance of LWP::UserAgent or a subclass of it.
Defaults to creating a new instance of LWP::UserAgent::Determined
honor_leading_slashes
Optional. Boolean to set if bucket names should include any leading slashes when sent to S3 - defaults to zero
PUBLIC PROPERTIES
access_key_id
String. Read-only
secret_access_key
String. Read-only.
secure
Boolean. Read-only.
endpoint
String. Read-only.
ua
LWP::UserAgent object. Read-only.
owner
AWS::S3::Owner object. Read-only.
PUBLIC METHODS
buckets
Returns an array of AWS::S3::Bucket objects.
bucket( $name )
Returns the AWS::S3::Bucket object matching $name if found.
Returns nothing otherwise.
add_bucket( name => $name, location => 'us-west-1' )
Attempts to create a new bucket with the name provided. The location parameter is optional and, as per the AWS docs, will default to "us-east-1".
On success, returns the new AWS::S3::Bucket
On failure, dies with the error message.
See AWS::S3::Bucket for details on how to use buckets (and access their files).
SEE ALSO
The Amazon S3 API Documentation
AUTHOR
Originally John Drago jdrago_999@yahoo.com, currently maintained by Lee Johnson (LEEJO) leejo@cpan.org
with contributions from Evan Carroll, Robin Clarke, Ulrich Kautz, simbabque, Dave Rolsky
LICENSE
This software is Free software and may be used and redistributed under the same terms as any version of perl itself.
Copyright John Drago 2011 all rights reserved.