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 <acme@astray.com> and unknown Amazon Digital Services
    programmers.

    Brad Fitzpatrick <brad@danga.com> - return values, Bucket object

SEE ALSO
    Net::Amazon::S3::Bucket