select results from the CPAN

select

Amazon-S3

view release on metacpan or search on metacpan


The `token` option is required only when temporary AWS credentials
include a session token.

For applications that obtain credentials dynamically, a credentials
object is preferred:

    my $s3 = Amazon::S3->new({ credentials => $credentials } );

The credentials object must provide:

    get_aws_access_key_id()
    get_aws_secret_access_key()
    get_token()

[Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) is one implementation of this interface.

Using a credentials object allows the credential provider to manage
credential discovery and refresh independently of `Amazon::S3`.

`Amazon::S3` uses Signature Version 4 for AWS API requests.

The signer normally uses the credentials associated with the
`Amazon::S3` object. A signer may also be supplied to the constructor
using the `signer` option.

By default, signers are not cached. Setting `cache_signer` to true
causes `Amazon::S3` to retain and reuse the signer object.

Applications should avoid dumping `Amazon::S3`, credential, or signer
objects to logs. These objects participate in request authentication
and may contain or provide access to sensitive authentication
material.

# CHECKSUMS

Version 2.1.0 adds checksum generation for uploads and checksum
verification for downloads.

The default upload checksum algorithm is `crc64nvme`.

`Amazon::S3` provides local implementations for:

    crc64nvme
    crc32
    crc32c
    md5
    sha1
    sha256
    sha512

Amazon S3 also defines XXHash checksum algorithms. They are recognized
by `Amazon::S3` but are not implemented locally in this release.

## Uploads

When an upload is performed through [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket),
`Amazon::S3` calculates the configured checksum when that operation
supports checksum submission.

The checksum algorithm is selected using `checksum_algorithm`. The
default is `crc64nvme`.

Managed multipart uploads performed by
`Amazon::S3::Bucket::upload_multipart_object()` also use the
configured checksum algorithm.

Low-level multipart methods do not implicitly enable an additional
checksum algorithm. Applications that directly manage the multipart
workflow are responsible for selecting and carrying the checksum
algorithm through that workflow.

## Downloads

Checksum verification is enabled by default.

When `verify_checksums` is true, object downloads request checksum
metadata from S3. `Amazon::S3` verifies supported `FULL_OBJECT`
checksums returned by the service.

Verification is opportunistic. If S3 does not return a checksum, or
returns a checksum for an algorithm that `Amazon::S3` cannot
calculate locally, the object can still be downloaded.

`COMPOSITE` checksums are not independently verified.

Partial and ranged downloads are not checksum verified because the
checksum returned for an object describes the complete object rather
than the requested byte range.

The `verify_checksums` setting controls download verification only.
It does not disable checksum generation for uploads.

# WORKING WITH BUCKETS AND OBJECTS

`Amazon::S3` creates bucket objects that provide the object-oriented
interface used for most S3 operations.

## Creating and Representing Buckets

`add_bucket()` creates a bucket in S3.

`bucket()` and `bucketv2()` do not create a bucket. They construct
client-side objects representing a bucket.

A bucket region can be supplied explicitly when constructing a bucket
object. Region verification can also be requested when the bucket
region is not already known; doing so requires an additional service
request.

Amazon S3 applies public-access-block settings to new buckets by
default. Applications that intentionally create public buckets or
apply public ACLs must ensure that the account and bucket public access
settings permit the requested policy.

Directory buckets have additional creation requirements. See
["DIRECTORY BUCKETS"](#directory-buckets).

    my $bucket = $s3->bucket('example-bucket');

Calling `bucket()` does not create the bucket and does not verify
that it exists. It constructs an [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) object
associated with the `Amazon::S3` client.

A bucket can be assigned a region explicitly:

    my $bucket = $s3->bucket(
      { bucket => 'example-bucket',
        region => 'us-west-2',
      }

share/README.md view on Meta::CPAN

    When false, construct a signer when one is needed.

    The default is false.

    See ["AUTHENTICATION AND CREDENTIALS"](#authentication-and-credentials).

- checksum\_algorithm

    Checksum algorithm used when `Amazon::S3` supplies a checksum with an
    upload.

    The default is `crc64nvme`.

    Recognized S3 checksum algorithm names are validated by the
    constructor. Local checksum implementations provided by this release
    are described in ["CHECKSUMS"](#checksums).

- credentials

    Credentials provider object.

    The object must provide:

        get_aws_access_key_id()
        get_aws_secret_access_key()
        get_token()

    [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) is one implementation of this interface.

    See ["AUTHENTICATION AND CREDENTIALS"](#authentication-and-credentials).

- debug

    Compatibility option that sets the default logger level to `debug`.

    Applications should normally use `level` instead.

    This option affects the internally created logger only.

- dns\_bucket\_names

    Controls whether virtual-hosted-style bucket names are used when
    possible.

    The default is true.

    A bucket name that cannot be used as a DNS subdomain is placed in the
    request path instead.

- endpoint\_url

    Optional explicit S3 service endpoint.

    When `endpoint_url` is supplied, `Amazon::S3` uses that endpoint as
    specified and does not rewrite the host when the configured region
    changes.

    The `region` setting still controls the AWS signing region.

    This is useful for S3-compatible services, local test environments, and
    other cases where the caller must select the service endpoint explicitly.

    For example:

        my $s3 = Amazon::S3->new(
          { endpoint_url => 'http://localhost:4566',
            region       => 'us-east-1',
            ...
          }
        );

    When `endpoint_url` is not supplied, `Amazon::S3` may derive the
    standard AWS S3 endpoint from the configured region.

    `endpoint_url` and `host` may not both be supplied.

- host

    S3 service endpoint.

    The default is `s3.amazonaws.com`.

    When `region()` is set and the host is a standard Amazon S3 endpoint,
    `Amazon::S3` adjusts the host for the configured region.

    This option can also be used with S3-compatible and local testing
    services.

- level

    Logging level used when `Amazon::S3` creates its default logger.

    The default is `error`.

    See ["LOGGING AND DEBUGGING"](#logging-and-debugging).

- logger

    Logger object.

    If omitted, `Amazon::S3::Logger` is used.

    A caller-supplied logger is expected to provide the logging methods
    used by `Amazon::S3`.

    See ["LOGGING AND DEBUGGING"](#logging-and-debugging).

- raise\_error

    When true, S3 request failures that would normally be reported through
    the return value and the `err()`, `errstr()`, and `error()` accessors
    instead throw an exception.

    The exception includes the HTTP status and, when available, the S3
    error code and message.

    The default is false for backward compatibility.

    See ["ERROR HANDLING"](#error-handling).

- region

share/README.md view on Meta::CPAN

    the configured credentials.

    See ["AUTHENTICATION AND CREDENTIALS"](#authentication-and-credentials).

- timeout

    HTTP request timeout in seconds.

    The default is 30.

- token

    Optional AWS session token used with temporary credentials.

- verify\_checksums

    Controls checksum verification when downloading objects.

    The default is true.

    See ["CHECKSUMS"](#checksums).

If neither a credentials provider nor both explicit access key values
are supplied, the constructor throws an exception.

An invalid `checksum_algorithm` also causes the constructor to throw
an exception.

On success, returns the new `Amazon::S3` object.

## ACCESSORS

### buffer\_size

    my $buffer_size = $s3->buffer_size;

    $s3->buffer_size($bytes);

Gets or sets the default streaming buffer size in bytes.

The constructor default is 4096.

### cache\_signer

    my $cache_signer = $s3->cache_signer;

    $s3->cache_signer($boolean);

Gets or sets whether a generated request signer is retained for reuse.

The constructor default is false.

See ["AUTHENTICATION AND CREDENTIALS"](#authentication-and-credentials).

### checksum\_algorithm

    my $algorithm = $s3->checksum_algorithm;

    $s3->checksum_algorithm('sha256');

Gets or sets the checksum algorithm selected for uploads.

The constructor default is `crc64nvme`.

The constructor validates the initial value. Callers that change this
accessor after construction are responsible for supplying an
algorithm supported by the operation being performed.

See ["CHECKSUMS"](#checksums).

### checksum\_types

    my $checksum_types = $s3->checksum_types;

Returns the checksum implementations initialized for this client.

The value is a hash reference keyed by algorithm name.

This accessor is intended for introspection. The internal checksum
implementation entries are not a public plugin interface in this
release.

See ["CHECKSUMS"](#checksums).

### credentials

    my $credentials = $s3->credentials;

    $s3->credentials($credentials);

Gets or sets the credentials provider object.

See ["AUTHENTICATION AND CREDENTIALS"](#authentication-and-credentials).

### dns\_bucket\_names

    my $enabled = $s3->dns_bucket_names;

    $s3->dns_bucket_names($boolean);

Gets or sets whether virtual-hosted-style bucket addressing is used
when possible.

The constructor default is true.

### err

Returns the most recent S3 error code or short error identifier.

See ["ERROR HANDLING"](#error-handling).

### error

Returns the most recent parsed structured error response.

See ["ERROR HANDLING"](#error-handling).

### errstr

Returns the most recent human-readable error message.

( run in 1.137 second using v1.01-cache-2.11-cpan-eca53f54451 )