view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    
    # delete bucket
    $bucket->delete_bucket;

# DESCRIPTION

This documentation refers to version 2.0.2.

`Amazon::S3` provides a portable client interface to Amazon Simple
Storage System (S3).

This module is rather dated, however with some help from a few
contributors it has had some recent updates. Recent changes include
implementations of:

- ListObjectsV2
- CopyObject
- DeleteObjects
- ListObjectVersions

Additionally, this module now implements Signature Version 4 signing,
unit tests have been updated and more documentation has been added or
corrected. Credentials are encrypted if you have encryption modules installed.

_NEW!_

The `Amazon::S3` modules have been heavily refactored over the last
few releases to increase maintainability and to add new features. New
features include:

- [Amazon::S3::BucketV2](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucketV2)

    This new module implements a mechanism to invoke _almost_ all of the
    S3 APIs using a standard calling method.

    The module will format your Perl objects as XML payloads and enable
    you to provide all of the parameters required to make an API
    call. Headers and URI parameters can also be passed to the
    methods. [Amazon::S3::BucketV2](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucketV2) is a subclass of
    [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket), meaning you can still invoke all of the same
    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

README.md  view on Meta::CPAN

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

- secure

    Set this to a true value if you want to use SSL-encrypted connections
    when connecting to S3. Starting in version 0.49, the default is true.

    default: true

- timeout

    Defines the time, in seconds, your script should wait or a
    response before bailing.

    default: 30s

- retry

    Enables or disables the library to retry upon errors. This
    uses exponential backoff with retries after 1, 2, 4, 8, 16,
    32 seconds, as recommended by Amazon.

    default: off

- host

    Defines the S3 host endpoint to use.

    default: s3.amazonaws.com

    Note that requests are made to domain buckets when possible.  You can
    prevent that behavior if either the bucket name does not conform to
    DNS bucket naming conventions or you preface the bucket name with '/'
    or explicitly turn off domain buckets by setting `dns_bucket_names`
    to false.

    If you set a region then the host name will be modified accordingly if
    it is an Amazon endpoint.

- region

    The AWS region you where your bucket is located.

    default: us-east-1

- buffer\_size

    The default buffer size when reading or writing files.

    default: 4096

## signer

Sets or retrieves the signer object. API calls must be signed using
your AWS credentials. By default, starting with version 0.54 the
module will use [Net::Amazon::Signature::V4](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3ASignature%3A%3AV4) as the signer and
instantiate a signer object in the constructor. Note however, that
signers need your credentials and they _will_ get stored by that
class, making them susceptible to inadvertant exfiltration. You have a
few options here:

- 1. Use your own signer.

    You may have noticed that you can also provide your own credentials
    object forcing this module to use your object for retrieving
    credentials. Likewise, you can use your own signer so that this
    module's signer never sees or stores those credentials.

- 2. Pass the credentials object and set `cache_signer` to a
false value.

    If you pass a credentials object and set `cache_signer` to a false
    value, the module will use the credentials object to retrieve
    credentials and create a new signer each time an API call is made that
    requires signing. This prevents your credentials from being stored
    inside of the signer class.

    _Note that using your own credentials object that stores your
    credentials in plaintext is also going to expose your credentials when
    someone dumps the class._

- 3. Pass credentials, set `cache_signer` to a false value.

    Unfortunately, while this will prevent [Net::Amazon::Signature::V4](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3ASignature%3A%3AV4)
    from hanging on to your credentials, you credentials will be stored in
    the `Amazon::S3` object.

    Starting with version 0.55 of this module, if you have installed
    [Crypt::CBC](https://metacpan.org/pod/Crypt%3A%3ACBC) and [Crypt::Blowfish](https://metacpan.org/pod/Crypt%3A%3ABlowfish), your credentials will be
    encrypted using a random key created when the class is
    instantiated. While this is more secure than leaving them in
    plaintext, if the key is discovered (the key however is not stored in
    the object's hash) and the object is dumped, your _encrypted_
    credentials can be exposed.

- 4. Use very granular credentials for bucket access only.

    Use credentials that only allow access to a bucket or portions of a