view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

[![Actions Status](https://github.com/DQNEO/Amazon-S3-Thin/workflows/test/badge.svg)](https://github.com/DQNEO/Amazon-S3-Thin/actions)
# NAME

Amazon::S3::Thin - A thin, lightweight, low-level Amazon S3 client

# SYNOPSIS

    use Amazon::S3::Thin;

    # Pass in explicit credentials
    my $s3client = Amazon::S3::Thin->new({
          aws_access_key_id     => $aws_access_key_id,
          aws_secret_access_key => $aws_secret_access_key,
          aws_session_token     => $aws_session_token, # optional
          region                => $region, # e.g. 'ap-northeast-1'
        });

    # Get credentials from environment
    my $s3client = Amazon::S3::Thin->new({region => $region, credential_provider => 'env'});

    # Get credentials from instance metadata
    my $s3client = Amazon::S3::Thin->new({
        region              => $region,
        credential_provider => 'metadata',
        version             => 2,         # optional (default 2)
        role                => 'my-role', # optional
      });

    # Get credentials from ECS task role
    my $s3client = Amazon::S3::Thin->new({
        region              => $region,
        credential_provider => 'ecs_container',
      });

    my $bucket = "mybucket";
    my $key = "dir/file.txt";
    my $response;

    $response = $s3client->put_bucket($bucket);

    $response = $s3client->put_object($bucket, $key, "hello world");

    $response = $s3client->get_object($bucket, $key);
    print $response->content; # => "hello world"

    $response = $s3client->delete_object($bucket, $key);

    $response = $s3client->list_objects(
                                $bucket,
                                {prefix => "foo", delimiter => "/"}
                               );

You can also pass any useragent as you like

    my $s3client = Amazon::S3::Thin->new({
            ...
            ua => $any_LWP_copmatible_useragent,
        });

Signature version 4 is used by default. 
To use signature version 2, add a `signature_version` option:

    my $s3client = Amazon::S3::Thin->new({
            ...
            signature_version     => 2,
        });

# DESCRIPTION

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: