view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

Amazon::S3::Thin is a thin, lightweight, low-level Amazon S3 client.

It's designed for only ONE purpose: Send a request and get a response.

In detail, it offers the following features:

- Low Level

    It returns an [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse) object so you can easily inspect
    what's happening inside, and can handle errors as you like.

- Low Dependency

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

- Low Learning Cost

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

## Comparison to precedent modules

There are already some useful modules like [Amazon::S3](https://metacpan.org/pod/Amazon%3A%3AS3), [Net::Amazon::S3](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3AS3)
 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 `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.

# CONSTRUCTOR

## new( \\%params )

**Receives:** hashref with options.

**Returns:** Amazon::S3::Thin object

It can receive the following arguments:

- `credential_provider` (**default: credentials**) - specify where to source credentials from. Options are:
    - `credentials` - existing behaviour, pass in credentials via `aws_access_key_id` and `aws_secret_access_key`
    - `env` - fetch credentials from environment variables
    - `metadata` - fetch credentials from EC2 instance metadata service
    - `ecs_container` - fetch credentials from ECS task role
- `region` - (**REQUIRED**) region of your buckets you access- (currently used only when signature version is 4)
- `aws_access_key_id` (**REQUIRED \[provider: credentials\]**) - an access key id
of your credentials.
- `aws_secret_access_key` (**REQUIRED \[provider: credentials\]**) - an secret access key
 of your credentials.
- `version` (**OPTIONAL \[provider: metadata\]**) - version of metadata service to use, either 1 or 2.
[read more](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)
- `role` (**OPTIONAL \[provider: metadata\]**) - IAM instance role to use, otherwise the first is selected
- `secure` - whether to use https or not. Default is 0 (http).
- `ua` - a user agent object, compatible with LWP::UserAgent.
Default is an instance of [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent).
- `signature_version` - AWS signature version to use. Supported values
are 2 and 4. Default is 4.
- `debug` - debug option. Default is 0 (false). 
If set 1, contents of HTTP request and response are shown on stderr
- `virtual_host` - whether to use virtual-hosted style request format. Default is 0 (path-style).

# ACCESSORS

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

## secure

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

## 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 [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent) (i.e. providing the same interface).

## debug

Debug option.

# Operations on Buckets

## put\_bucket( $bucket \[, $headers\])

**Arguments**:

- 1. bucket - a string with the bucket
- 2. headers (**optional**) - hashref with extra header information

## delete\_bucket( $bucket \[, $headers\])

**Arguments**:

- 1. bucket - a string with the bucket
- 2. headers (**optional**) - hashref with extra header information

# Operations on Objects

## get\_object( $bucket, $key \[, $headers\] )

**Arguments**:

- 1. bucket - a string with the bucket
- 2. key - a string with the key
- 3. headers (**optional**) - hashref with extra header information

**Returns**: an [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse) object for the request. Use the `content()`
method on the returned object to read the contents:

    my $res = $s3->get_object( 'my.bucket', 'my/key.ext' );

    if ($res->is_success) {
        my $content = $res->content;
    }

The GET operation retrieves an object from Amazon S3.

For more information, please refer to
[Amazon's documentation for GET](http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html).

## head\_object( $bucket, $key )

**Arguments**:

- 1. bucket - a string with the bucket
- 2. key - a string with the key

**Returns**: an [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse) object for the request. Use the `header()`
method on the returned object to read the metadata:

    my $res = $s3->head_object( 'my.bucket', 'my/key.ext' );

    if ($res->is_success) {
        my $etag = $res->header('etag'); #=> `"fba9dede5f27731c9771645a39863328"`
    }

The HEAD operation retrieves metadata of an object from Amazon S3.