[](https://travis-ci.org/DQNEO/Amazon-S3-Thin)
# NAME

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

# SYNOPSIS

   use Amazon::S3::Thin;

   my $s3client = Amazon::S3::Thin->new(
       {   aws_access_key_id     => $aws_access_key_id,
           aws_secret_access_key => $aws_secret_access_key,
       }
   );

   my $key = "dir/file.txt";
   my $response;
   $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->copy_object($src_bucket, $src_key,
                                      $dst_bucket, $dst_key);

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

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

You can also pass any useragent as you like

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

# DESCRIPTION

Amazon::S3::Thin is a thin, lightweight, low-level Amazon S3 client.
It offers the following features:

- Low Level

   It returns an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) 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::S3), [Net::Amazon::S3](https://metacpan.org/pod/Net::Amazon::S3)
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:

- `aws_access_key_id` (**REQUIRED**) - an access key id
of your credentials.
- `aws_secret_access_key` (**REQUIRED**) - an secret access key
of your credentials.
- `secure` - whether to use https or not. Default is 0 (http).
- `host` - the base host to use. Default is '_s3.amazonaws.com_'.
- `ua` - a user agent object, compatible with LWP::UserAgent.
Default is an instance of [LWP::UserAgent](https://metacpan.org/pod/LWP::UserAgent).

# 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.

## host

The base host to use for 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::UserAgent) (i.e. providing the same interface).

# METHODS

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

**Arguments**: a string with the bucket name, and a string with the key name.

**Returns**: an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) 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).

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

**Arguments**: a string with the bucket name, and a string with the key name.

**Returns**: an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object for the request.

The DELETE operation removes the null version (if there is one) of an object
and inserts a delete marker, which becomes the current version of the
object. If there isn't a null version, Amazon S3 does not remove any objects.

Use the response object to see if it succeeded or not.

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

## copy\_object( $src\_bucket, $src\_key, $dst\_bucket, $dst\_key )

**Arguments**: a list with source (bucket, key) and destination (bucket, key)

**Returns**: an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object for the request.

This method is a variation of the PUT operation as described by
Amazon's S3 API. It creates a copy of an object that is already stored
in Amazon S3. This "PUT copy" operation is the same as performing a GET
from the old bucket/key and then a PUT to the new bucket/key.

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

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

**Arguments**:

a list of the following items, in order:

- 1. bucket - a string with the destination bucket
- 2. key - a string with the destination key
- 3. content - a string with the content to be uploaded
- 4. headers (**optional**) - hashref with extra headr information

**Returns**: an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object for the request.

The PUT operation adds an object to a bucket. Amazon S3 never adds partial
objects; if you receive a success response, Amazon S3 added the entire
object to the bucket.

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

# TODO

lots of APIs are not implemented yet.

# REPOSITORY

[https://github.com/DQNEO/Amazon-S3-Thin](https://github.com/DQNEO/Amazon-S3-Thin)

# LICENSE

Copyright (C) DQNEO.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

# AUTHOR

DQNEO

## ORIGINAL AUTHOR

Timothy Appnel <[email protected]> [Amazon::S3](https://metacpan.org/pod/Amazon::S3)
[https://github.com/tima/perl-amazon-s3](https://github.com/tima/perl-amazon-s3)

# SEE ALSO

[Amazon::S3](https://metacpan.org/pod/Amazon::S3), [Net::Amazon::S3](https://metacpan.org/pod/Net::Amazon::S3)

[Amazon S3 API Reference : REST API](http://docs.aws.amazon.com/AmazonS3/latest/API/APIRest.html)

[Amazon S3 API Reference : List of Error Codes](http://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html#ErrorCodeList)

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.