view release on metacpan or  search on metacpan

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

=item Low Dependency

It does not require any XML::* modules, so installation is easy;

=item Low Learning Cost

The interfaces are designed to follow S3 official REST APIs.
So it is easy to learn.

=back

=head2 Comparison to precedent modules

There are already some useful modules like L<Amazon::S3>, L<Net::Amazon::S3>
 on CPAN. They provide a "Perlish" interface, which looks pretty
 for Perl programmers, but they also hide low-level behaviors.
For example, the "get_key" method translate HTTP status 404 into C<undef> and
 HTTP 5xx status into exception.

In some situations, it is very important to see the raw HTTP communications.
That's why I made this module.

=head1 CONSTRUCTOR

=head2 new( \%params )

B<Receives:> hashref with options.

B<Returns:> Amazon::S3::Thin object

It can receive the following arguments:

=over 4

=item * C<credential_provider> (B<default: credentials>) - specify where to source credentials from. Options are:

=over 2

=item * C<credentials> - existing behaviour, pass in credentials via C<aws_access_key_id> and C<aws_secret_access_key>

=item * C<env> - fetch credentials from environment variables

=item * C<metadata> - fetch credentials from EC2 instance metadata service

=item * C<ecs_container> - fetch credentials from ECS task role

=back

=item * C<region> - (B<REQUIRED>) region of your buckets you access- (currently used only when signature version is 4)

=item * C<aws_access_key_id> (B<REQUIRED [provider: credentials]>) - an access key id
of your credentials.

=item * C<aws_secret_access_key> (B<REQUIRED [provider: credentials]>) - an secret access key
 of your credentials.

=item * C<version> (B<OPTIONAL [provider: metadata]>) - version of metadata service to use, either 1 or 2.
L<read more|https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html>

=item * C<role> (B<OPTIONAL [provider: metadata]>) - IAM instance role to use, otherwise the first is selected

=item * C<secure> - whether to use https or not. Default is 0 (http).

=item * C<ua> - a user agent object, compatible with LWP::UserAgent.
Default is an instance of L<LWP::UserAgent>.

=item * C<signature_version> - AWS signature version to use. Supported values
are 2 and 4. Default is 4.

=item * C<debug> - debug option. Default is 0 (false). 
If set 1, contents of HTTP request and response are shown on stderr

=item * C<virtual_host> - whether to use virtual-hosted style request format. Default is 0 (path-style).

=back

=head1 ACCESSORS

The following accessors are provided. You can use them to get/set your
object's attributes.

=head2 secure

Whether to use https (1) or http (0) when connecting to S3.

=head2 ua

The user agent used internally to perform requests and return responses.
If you set this attribute, please make sure you do so with an object
compatible with L<LWP::UserAgent> (i.e. providing the same interface).

=head2 debug

Debug option.

=head1 Operations on Buckets

=head2 put_bucket( $bucket [, $headers])

B<Arguments>:

=over 2

=item 1. bucket - a string with the bucket

=item 2. headers (B<optional>) - hashref with extra header information

=back

=head2 delete_bucket( $bucket [, $headers])

B<Arguments>:

=over 3

=item 1. bucket - a string with the bucket

=item 2. headers (B<optional>) - hashref with extra header information

=back