view release on metacpan or  search on metacpan

lib/Amazon/S3/BucketV2.pm  view on Meta::CPAN

__END__

=pod

=head1 NAME

Amazon::S3::BucketV2 - lightweight interface to various S3 methods

=head1 SYNOPSIS

  use Amazon::S3;
  use Amazon::S3::BucketV2;

  my $s3 = Amazon::S3->new(
      {   aws_access_key_id     => $aws_access_key_id,
          aws_secret_access_key => $aws_secret_access_key,
      }
  );

  my $s3 = Amazon::S3->new();

  my $bucket = Amazon::S3::BucketV2->new(account => $s3, bucket => 'foo');

  $bucket->DeleteObject($key);

  $bucket->DeleteObjects(undef,
    { Delete => { Object => [ { Key => $key, Version => $version } ] } } );

=head1 DESCRIPTION

A lightweight, generic interface to the AWS S3
API. C<Amazon::S3::BucketV2> is a subclass of L<Amazon::S3::Bucket>. In
addition to the methods described below you can still use the
convenience methods offered in the parent class.

I<Note that this is an experimental implementation and may change in
the future.>

The methods listed below should be called with a list (or hash
reference) of key/value pairs.  Depending on your needs and the API
being invoked some of these keys may not be required.

=over 5

=item key

The key in the S3 bucket.

=item body

The request body. This should be a hash ref which will be converted
to an XML payload to be sent for the request.

You need to review the required payload for the API being invoked and
provide the appropriate Perl object to be converted to XML.

To see how your Perl object will be serialized call the C<create_xml>
method.

For example the DeleteObjects API takes a payload that looks like this:

 <Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Object>
       <Key>string</Key>
       <VersionId>string</VersionId>
    </Object>
    ...
    <Quiet>boolean</Quiet>
 </Delete>

The corresponding Perl object would be created like this:

 my $content = {
   Delete => {
     Object => [
       { Key       => '/foo',
         VersionId => 'OYcLXagmS.WaD..oyH4KRguB95_YhLs7'
       }
     ]
   }
 };


...and to verify how that Perl object would be serialized as XML:

 use Amazon::S3::Util qw(create_xml_request);

 my $content = {
   Delete => {
     Object => [
       { Key       => '/foo',
         VersionId => 'OYcLXagmS.WaD..oyH4KRguB95_YhLs7'
       }
     ]
   }
 };

 print create_xml_request($content);
 
=item uri_params

A hash ref of additional query string parameters.

=item headers

A hash ref of additional headers to send with the request. The API
methods will automatically add the rquired headers for most calls.
Review the API specifications to see how to send additional headers
you might require.

=back

Example:

 $bucket->DeleteObject(key => $key);
 $bucket->DeleteObject(key => $key, uri_param => { versionId => $version });

 my $content
   = { Delete => { Object => [ { Key => $key, Version => $version } ] } };