Amazon-S3
view release on metacpan or search on metacpan
# 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
interface, however this module may still appeal to those that favor
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_
- 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
bucket required for your application. This will at least limit the
_blast radius_ of any potential security breach.
- 5. Do nothing...send the credentials, use the default signer.
In this case, both the `Amazon::S3` class and the
[Net::Amazon::Signature::V4](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3ASignature%3A%3AV4) have your credentials. Caveat Emptor.
See also [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) for more information about safely
storing your credentials and preventing exfiltration.
## region
Sets the region for the API calls. This will also be the
default when instantiating the bucket object unless you pass the
region parameter in the `bucket` method or use the `verify_region`
flag that will _always_ verify the region of the bucket using the
`get_location_constraint` method.
default: us-east-1
## buckets
buckets([verify-region])
- verify-region (optional)
`verify-region` is a boolean value that indicates if the
bucket's region should be verified when the bucket object is
instantiated.
If set to true, this method will call the `bucket` method with
`verify_region` set to true causing the constructor to call the
`get_location_constraint` for each bucket to set the bucket's
region. This will cause a significant decrease in the peformance of
the `buckets()` method. Setting the region for each bucket is
necessary since API operations on buckets require the region of the
bucket when signing API requests. If all of your buckets are in the
same region and you have passed a region parameter to your S3 object,
then that region will be used when calling the constructor of your
bucket objects.
default: false
Returns a reference to a hash containing the metadata for all of the
buckets owned by the accout or (see below) or `undef` on error.
- owner\_id
The owner ID of the bucket's owner.
- owner\_display\_name
The name of the owner account.
- buckets
An array of [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) objects for the account. Returns
`undef` if there are not buckets or an error occurs.
## add\_bucket
add_bucket(bucket-configuration)
`bucket-configuration` is a reference to a hash with bucket
configuration parameters.
_Note that since April of 2023, new buckets are created that block
public access by default. If you attempt to set an ACL with public
permissions the create operation will fail. To create a public bucket
( run in 0.454 second using v1.01-cache-2.11-cpan-39bf76dae61 )