view release on metacpan or  search on metacpan

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

use this library and the S3 service, please visit the Amazon
Web Services web site at http://www.amazonaws.com/.

You will be billed accordingly by Amazon when you use this
module and must be responsible for these costs.

To learn more about Amazon's S3 service, please visit:
http://s3.amazonaws.com/.

The need for this module arose from some work that needed
to work with S3 and would be distributed, installed and used
on many various environments where compiled dependencies may
not be an option. L<Net::Amazon::S3> used L<XML::LibXML>
tying it to that specific and often difficult to install
option. In order to remove this potential barrier to entry,
this module is forked and then modified to use L<XML::SAX>
via L<XML::Simple>.

=back

=head1 LIMITATIONS AND DIFFERENCES WITH EARLIER VERSIONS

As noted, this module is no longer a I<drop-in> replacement for
C<Net::Amazon::S3> and has limitations and differences that may impact
the use of this module in your applications. Additionally, one of the
original intents of this fork of C<Net::Amazon::S3> was to reduce the
number of dependencies and make it I<easy to install>. Recent changes
to this module have introduced new dependencies in order to improve
the maintainability and provide additional features. Installing CPAN
modules is never easy, especially when the dependencies of the
dependencies are impossible to control and include may include XS
modules.

=over 5

=item MINIMUM PERL

Technically, this module should run on versions 5.10 and above,
however some of the dependencies may require higher versions of
C<perl> or some lower versions of the dependencies due to conflicts
with other versions of dependencies...it's a crapshoot when dealing
with older C<perl> versions and CPAN modules.

You may however, be able to build this module by installing older
versions of those dependencies and take your chances that those older
versions provide enough working features to support C<Amazon::S3>. It
is likely they do...and this module has recently been tested on
version 5.10.0 C<perl> using some older CPAN modules to resolve
dependency issues.

To build this module on an earlier version of C<perl> you may need to
downgrade some modules.  In particular I have found this recipe to
work for building and testing on 5.10.0.

In this order install:

 HTML::HeadParser 2.14
 LWP 6.13
 Amazon::S3

...other versions I<may> work...YMMV. If you do decide to run on an
earlier version of C<perl>, you are encouraged to run the test
suite. See the L</TESTING> section for more details.

=item API Signing

Making calls to AWS APIs requires that the calls be signed.  Amazon
has added a new signing method (Signature Version 4) to increase
security around their APIs. This module no longer utilizes Signature
Version V2.

B<New regions after January 30, 2014 will only support Signature Version 4.>

See L</Signature Version V4> below for important details.

=over 10

=item Signature Version 4

L<https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html>

I<IMPORTANT NOTE:>

Unlike Signature Version 2, Version 4 requires a regional
parameter. This implies that you need to supply the bucket's region
when signing requests for any API call that involves a specific
bucket. Starting with version 0.55 of this module,
C<Amazon::S3::Bucket> provides a new method (C<region()>) and accepts
in the constructor a C<region> parameter.  If a region is not
supplied, the region for the bucket will be set to the region set in
the C<account> object (C<Amazon::S3>) that you passed to the bucket's
new constructor.  Alternatively, you can request that the bucket's new
constructor determine the bucket's region for you by calling the
C<get_location_constraint()> method.

When signing API calls, the region for the specific bucket will be
used. For calls that are not regional (C<buckets()>, e.g.) the default
region ('us-east-1') will be used.

=item Signature Version 2

L<https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html>

=back

=item Multipart Upload Support

There are some recently added unit tests for multipart uploads that
seem to indicate this feature is working as expected.  Please report
any deviation from expected results if you are using those methods.

For more information regarding multipart uploads visit the link below.

L<https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html>

=back

=head1 METHODS AND SUBROUTINES

Unless otherwise noted methods will return an C<undef> if an error
occurs.  You can get more information about the error by calling