NAME Net::Amazon::S3 - Use the Amazon S3 - Simple Storage Service SYNOPSIS #!/usr/bin/perl use warnings; use strict; use Test::More qw/no_plan/; # this synopsis is presented as a test file use Net::Amazon::S3; use vars qw/$OWNER_ID $OWNER_DISPLAYNAME/; my $aws_access_key_id = "Fill me in!"; my $aws_secret_access_key = "Fill me in too!"; 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; TODO: { local $TODO = "These tests only work if you're leon"; $OWNER_ID = $response->{owner_id}; $OWNER_DISPLAYNAME = $response->{owner_displayname}; 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($bucketname); 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_obj->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_obj->add_key( $keyname, $value, { content_type => 'text/plain', 'x-amz-meta-colour' => 'orange', } ); # list keys in the bucket $response = $bucket_obj->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}, $OWNER_ID ); is( $key->{owner_displayname}, $OWNER_DISPLAYNAME ); # You can't delete a bucket with things in it ok( !$bucket_obj->delete_bucket() ); $bucket_obj->delete_key($keyname); # fetch contents of the bucket # note prefix, marker, max_keys options can be passed in $response = $bucket_obj->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}, [] ); ok( $bucket_obj->delete_bucket() ); # 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! METHODS new Create a new S3 client object. Takes some arguments: aws_access_key_id Use your Access Key ID as the value of the AWSAccessKeyId parameter in requests you send to Amazon Web Services (when required). Your Access Key ID identifies you as the party responsible for the request. aws_secret_access_key Since your Access Key ID is not encrypted in requests to AWS, it could be discovered and used by anyone. Services that are not free require you to provide additional information, a request signature, to verify that a request containing your unique Access Key ID could only have come from you. DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE. YOU'LL BE SORRY secure Set this to 1 if you want to use SSL-encrypted connections when talking to S3. Defaults to 0. timeout How many seconds should your script wait before bailing on a request to S3? Defaults to 30. buckets Returns undef on error, else hashref of results add_bucket Takes a hashref: bucket The name of the bucket you want to add Returns 0 on failure, Net::Amazon::S3::Bucket object on success bucket BUCKET Takes a scalar argument, the name of the bucket you're creating Returns an (unverified) bucket object from an account. Does no network access. delete_bucket Takes either a Net::Amazon::S3::Bucket object or a hashref containing bucket The name of the bucket to remove Returns false (and fails) if the bucket isn't empty. Returns true if the bucket is successfully deleted. list_bucket List all keys in this bucket. Takes a hashref containing a single key: bucket The name of the bucket you want to list keys on Returns undef on error and a hashref of data on success: The hashref looks like this: { bucket => $bucket_name, prefix => $bucket_prefix, marker => $bucket_marker, max_keys => $bucket_max_keys, is_truncated => $bucket_is_truncated_boolean keys => [$key1,$key2,...] } Each key looks like this: { key => $key, last_modified => $last_mod_date, etag => $etag, size => $size, # Bytes? storage_class => $storage_class # Doc? owner_id => $owner_id, owner_displayname => $owner_name } add_key DEPRECATED. DO NOT USE get_key DEPRECATED. DO NOT USE head_key DEPRECATED. DO NOT USE delete_key DEPRECATED. DO NOT USE 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. TESTING Testing S3 is a tricky thing. Amazon wants to charge you a bit of money each time you use their service. And yes, testing counts as using. Because of this, the application's test suite skips anything approaching a real test unless you set these three environment variables: AMAZON_S3_EXPENSIVE_TESTS Doesn't matter what you set it to. Just has to be set AWS_ACCESS_KEY_ID Your AWS access key AWS_ACCESS_KEY_SECRET Your AWS sekkr1t passkey. Be forewarned that setting this environment variable on a shared system might leak that information to another user. Be careful. AUTHOR Leon Brocard and unknown Amazon Digital Services programmers. Brad Fitzpatrick - return values, Bucket object SEE ALSO Net::Amazon::S3::Bucket