view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    methods found there.

    See [Amazon::S3::BucketV2](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucketV2) for more details.

- Limited Support for Directory Buckets

    This version include limited support for directory buckets.

    You can create and list directory buckets.

    _Directory buckets use the S3 Express One Zone storage class, which
    is recommended if your application is performance sensitive and
    benefits from single-digit millisecond PUT and GET latencies._ -
    [https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html)

    - list\_directory\_buckets

        List the directory buckets. Note this only returns a list of you
        directory buckets, not their contents. In order to list the contents
        of a directory bucket you must first create a session that establishes
        temporary credentials used to acces the Zonal endpoints. You then use
        those credentials for signing requests using the ListObjectV2 API.

        This process is currently **not supported** by this class.

        [https://docs.aws.amazon.com/AmazonS3/latest/API/API\_CreateSession.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html)

        <Lhttps://docs.aws.amazon.com/AmazonS3/latest/API/API\_ListObjectsV2.html>

    - add\_bucket

        You can add a regin and availability zone to this call in order to
        create a directory bucket.

            $bucket->add_bucket({ bucket => $bucket_name, availability_zone => 'use1-az5' });

        Note that your bucket name must conform to the naming conventions for
        directory buckets. -
        [https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html#directory-buckets-name](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html#directory-buckets-name)

- Addition of version parameter for `delete_key`

    You can now delete a version of a key by including its verion ID.

        $bucket->delete_key($key, $version_id);

- Methods that accept a hash reference can now accept a
`headers` object that may contain any additional headers you might want
to send with a request. Some of the methods that now allow you to pass
a header object include:
    - add\_bucket
    - add\_key
    - get\_key

        Can now be called with a hashref which may include both a `headers`
        and `uri_params` object.

    - delete\_bucket
    - list\_bucket
    - list\_object\_versions
    - upload\_multipart\_object

## Comparison to Other Perl S3 Modules

Other implementations for accessing Amazon's S3 service include
`Net::Amazon::S3` and the `Paws` project. `Amazon::S3` ostensibly
was intended to be a drop-in replacement for `Net:Amazon::S3` that
"traded some performance in return for portability". That statement is
no longer accurate as `Amazon::S3` may have changed the interface in
ways that might break your applications if you are relying on
compatibility with `Net::Amazon::S3`.

However, `Net::Amazon::S3` and `Paws::S3` today, are dependent on
`Moose` which may in fact level the playing field in terms of
performance penalties that may have been introduced by recent updates
to `Amazon::S3`. Changes to `Amazon::S3` include the use of more
Perl modules in lieu of raw Perl code to increase maintainability and
stability as well as some refactoring. `Amazon::S3` also strives now
to adhere to best practices as much as possible.

`Paws::S3` may be a much more robust implementation of a Perl S3
interface, however this module may still appeal to those that favor
simplicity of the interface and a lower number of dependencies. The
new [Amazon::S3::BucketV2](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucketV2) module now provides access to nearly all
of the main S3 API metods.

    Below is the original description of the module.

> 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 sign up for an Amazon Web Services account, required to
> 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. [Net::Amazon::S3](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3AS3) used [XML::LibXML](https://metacpan.org/pod/XML%3A%3ALibXML)
> 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 [XML::SAX](https://metacpan.org/pod/XML%3A%3ASAX)
> via [XML::Simple](https://metacpan.org/pod/XML%3A%3ASimple).

# LIMITATIONS AND DIFFERENCES WITH EARLIER VERSIONS

As noted, this module is no longer a _drop-in_ replacement for

README.md  view on Meta::CPAN

    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 `Amazon::S3`. It
    is likely they do...and this module has recently been tested on
    version 5.10.0 `perl` using some older CPAN modules to resolve
    dependency issues.

    To build this module on an earlier version of `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 _may_ work...YMMV. If you do decide to run on an
    earlier version of `perl`, you are encouraged to run the test
    suite. See the ["TESTING"](#testing) section for more details.

- 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.

    **New regions after January 30, 2014 will only support Signature Version 4.**

    See ["Signature Version V4"](#signature-version-v4) below for important details.

    - Signature Version 4

        [https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html)

        _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,
        `Amazon::S3::Bucket` provides a new method (`region()`) and accepts
        in the constructor a `region` parameter.  If a region is not
        supplied, the region for the bucket will be set to the region set in
        the `account` object (`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
        `get_location_constraint()` method.

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

    - Signature Version 2

        [https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html)

- 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.

    [https://docs.aws.amazon.com/AmazonS3/latest/API/API\_CreateMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html)

# METHODS AND SUBROUTINES

Unless otherwise noted methods will return an `undef` if an error
occurs.  You can get more information about the error by calling
`err()` and `errstr()`.

## new 

Create a new S3 client object. Takes some arguments:

- credentials (optional)

    Reference to a class (like `Amazon::Credentials`) that can provide
    credentials via the methods:

        get_aws_access_key_id()
        get_aws_secret_access_key()
        get_token()

    If you do not provide a credential class you must provide the keys
    when you instantiate the object. See below.

    _You are strongly encourage to use a class that provides getters. If
    you choose to provide your credentials to this class then they will be
    stored in this object. If you dump the class you will likely expose
    those credentials._

- 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.**

    _Consider using a credential class as described above to provide
    credentials, otherwise this class will store your credentials for
    signing the requests. If you dump this object to logs your credentials
    could be discovered._

- token

    An optional temporary token that will be inserted in the request along
    with your access and secret key.  A token is used in conjunction with
    temporary credentials when your EC2 instance has
    assumed a role and you've scraped the temporary credentials from
    _http://169.254.169.254/latest/meta-data/iam/security-credentials_