Amazon::S3::Thin - Thin, lightweight, low - level Amazon S3 client - Perl ABC - Perl Installation, Perl Tutorial, Many Examples

Perl
Module
here

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

Amazon::S3::Thin is a thin, lightweight, low-level Amazon S3 client. The following is a Japanese translation of Amazon::S3::Thin 0.29.

Overview

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,
      # aws_session_token => $aws_session_token, optional
      # region => $region, e.g.'ap-northeast-1'
    });
 
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 user agent as you like

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

By default, signature version 4 is used. To use signature version 2, add an option. signature_version

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

Explanation

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

It is designed solely for the purpose of sending a request and getting a response.

In detail, it provides the following features:

Low level

HTTP::Response You can easily find out what's going on inside by returning an object, you need You can handle the error accordingly.

Low dependence

No XML::* module is needed, so it's easy to install.

Low learning cost

The interface is designed to follow the official S3 REST API. So it's easy to learn.

Comparison with previously created modules

There are already useful modules like Amazon::S3, Net::Amazon::S3. They provide a "Perlish" interface that looks nice to Perl programmers, but also hides low-level behavior. For example, the "get_key" method converts the HTTP status 404 to undef and the HTTP 5xx status to an exception.

In some situations it is very important to check her raw HTTP communication. That's why I made this module.

Constructor

new(\%params)

Arguments: Hash reference with options.

Return value : Amazon::S3::Thin object

You can receive the following arguments:

aws_access_key_id ( Required )-Credential access key ID.
aws_secret_access_key ( Required )-The secret access key for your credentials.
region-( required ) Region of bucket to access (currently only used if signature version is 4)
secure- Whether to use https. The default is 0 (http).
ua-User agent object compatible with LWP::UserAgent. The default is an instance of LWP::user agent.
signature_version-Her AWS signature version to use. The supported values are 2 and 4. The default is 4.
debug- Debug options. The default is 0 (false). If the setting value is 1, the contents of HTTP requests and responses are displayed in stderr.
virtual_host-Whether to use a virtual host type request format. The default is 0 (path style).

Accessor

The following accessors are provided:You can use these to get/set the attributes of an object.

secure

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

ua

The user agent used it internally to execute the request and return a response. If you set this attribute, it's an object compatible with LWP::UserAgent (which provides the same interface). Please set with.

debug

Debug options.

Operation on bucket

put_bucket ($bucket[, $headers])

Arguments:

1. Bucket-a string with a bucket

2. Header (optional)-Hash reference with extra header information

delete_bucket ($bucket[$headers])

Arguments:

1. Bucket-a string with a bucket

2. Header (optional)-Hash reference with extra header information

Operations on objects

get_object ($bucket, $key[, $headers])

Arguments:

1. Bucket-a string with a bucket

2. Key-A string with a key

3. Header (optional)-Hash reference with extra header information

Return: HTTP::Response object in response to the request. You can use the content () method on the returned object to read its contents.

my $res = $s3->get_object('my.bucket', 'my/key.ext');
 
if ($res->is_success) {
    my $content = $res->content;
}

The GET operation gets an object from Amazon S3.

For more information, see Amazon documentation on GET.

head_object ($bucket, $key)

Arguments:

1. Bucket-a string with a bucket

2. Key-A string with a key

Return: HTTP::Response object in response to the request. You can 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 gets the object's metadata from Amazon S3.

For more information, Amazon documentation on HEAD.

delete_object ($bucket, $key)

Arguments: A string with a bucket name and a string with a key name.

Return: HTTP::Response object in response to the request.

The DELETE operation deletes the null version of the object (if it exists) and inserts a delete marker. If there is no null version, Amazon S3 will not delete the object.

Use the response object to see if it succeeded.

For more information, see Amazon documentation on DELETE.

copy_object ($src_bucket, $src_key, $dst_bucket, $dst_key[, $headers])

Arguments: A list with source (bucket, key) and destination (bucket, key), hash reference (optional) with additional header information.

Return: HTTP::Response object in response to the request.

This method is a variation of the PUT operation described in Amazon's S3 API. Make a copy of the 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 performing her PUT on the new bucket/key.

A COPY request may return an error response with 200 OK, but this method determines the error response and rewrites the status code to 500.

For more information, see Amazon documentation on COPY.

put_object ($bucket, $key, $content[, $headers])

Arguments:

1. Bucket-a string containing the destination bucket

2. Key-A string with a destination key

3. Content-A string containing the content to upload

4. Header (optional)-Hash reference with extra header information

Return: HTTP::Response object in response to the request.

The PUT operation adds an object to the bucket. Amazon S3 doesn't add partial objects. When you receive a success response, Amazon S3 adds the entire object to your bucket.

For more information, see Amazon documentation on PUT.

delete_multiple_objects ($bucket, @keys)

Arguments: An array containing a string with the bucket name and all the keys to delete.

Return: HTTP::Response object in response to the request.

The delete multiple objects operation allows you to delete multiple objects (up to 1000) from your bucket using a single HTTP request. If you know the object key to delete, this operation reduces the overhead for each request instead of sending individual delete requests. delete_object ()

For more information, see DELETE's Amazon documentation on deleting multiple objects. Please give me.

list_objects ($bucket[, \%options])

Arguments: Use either a string with the bucket name and a hash reference (optional) that includes the following options:

prefix (string)-Returns only keys that start with the specified prefix. You can use prefixes to separate buckets into different groups of keys, just as you would with folders in the file system.
delimiter (string)-A group key that contains the same string between the beginning of the key (or after the prefix, if specified) and the first occurrence of the delimiter.
encoding-type (string)-Set to "url" to encode the response key (useful if the XML parser cannot work with Unicode keys).
marker (string)-Specifies the key to start when listing objects. Amazon S3 returns the object keys in alphabetical order, starting with the key immediately following the marker.
max-keys(string) -Sets the maximum number of keys returned in the response body. If you want to get fewer keys than the default 1000 keys, you can add this to your request.

Return: HTTP::Response object in response to the request. You can use the content () method on the returned object to read its contents.

This method returns some or all of the objects in the bucket (up to 1000). Note that the response may contain fewer keys, but no more. If a key that meets the search criteria is not returned because it exceeds the limit (1000 or max-key), the response will return an additional key, see "marker" above.

For more information, see AMAZON REST Bucket GET Documentation.

generate_presigned_post ($bucket, $key[, $fields, $conditions, $expires_in])

Arguments:

1. Bucket (string)-a string containing the destination bucket

2. Key (string)-a string with a destination key

3. Field (Array Reference)-Builds an array reference for key/value pairs on top of the pre-filled form field.

4. Condition (array reference)-Array reference of the condition (array reference or hash reference) to include in the policy

5. expires_in (number)-the number of seconds since the current time before the signed URL expired

Return value: Returns a hash reference with two elements, "url" and "fields". "Url" is the posted URL. "Fields" are the fields of the form and their respective values that were used when submitting POST. Is an array reference with the form fields to use when submitting the post and their respective values. (You must follow the order of fields.)

This method uses HTTP POST to generate a signed URL for uploading a file to Amazon S3. The original implementation from boto3 is S3Client.generate_presigned_post ( ) was referenced and ported.

Note: This method only supports signature v4.

This is an example of generating a signed URL and uploading the file "test.txt". In this case, you can set the object metadata "x-amz-meta-foo" with any value and the upload size is limited to 1MB.

my $presigned = $s3->generate_presigned_post('my.bucket', 'my/key.ext', [
    'x-amz-meta-foo' =>'bar',
], [
    ['starts-with' =>'$x-amz-meta-foo', ''],
    ['content-length-range' => 1, 1024 * 1024],
], 24 * 60 * 60);
 
my $ua = LWP::UserAgent->new;
my $res = $ua->post(
    $signed->{url},
    Content_Type =>'multipart/form-data',
    Content => [
        @{$signed->{fields}},
        file => ['test.txt'],
    ],,
);

For more information, see Amazon documentation on creating POST policies. Please give me.

Todo

Many APIs have not been implemented yet.

Repository

https://github.com/DQNEO/Amazon-S3-Thin

License

This library is free software. It can be redistributed or modified using the same terminology as Perl itself.

Perl ABC