view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

     max_keys     => $bucket_max_keys,
     is_truncated => $bucket_is_truncated_boolean
     keys          => [$key1,$key2,...]
    }

- is\_truncated

    Boolean flag that indicates whether or not all results of your query were
    returned in this response. If your results were truncated, you can
    make a follow-up paginated request using the Marker parameter to
    retrieve the rest of the results.

- next\_marker 

    A convenience element, useful when paginating with delimiters. The
    value of `next_marker`, if present, is the largest (alphabetically)
    of all key names and all CommonPrefixes prefixes in the response.
    If the `is_truncated` flag is set, request the next page of results
    by setting `marker` to the value of `next_marker`. This element
    is only present in the response if the `delimiter` parameter was
    sent with the request.

Each key is a reference to a hash that looks like this:

    {
      key           => $key,
      last_modified => $last_mod_date,
      etag          => $etag, # An MD5 sum of the stored content.
      size          => $size, # Bytes
      storage_class => $storage_class # Doc?
      owner_id      => $owner_id,
      owner_displayname => $owner_name
    }

## get\_bucket\_location

    get_bucket_location(bucket-name)
    get_bucket_locaiton(bucket-obj)

This is a convenience routines for the `get_location_constraint()` of
the bucket object.  This method will return the default
region of 'us-east-1' when `get_location_constraint()` returns a null
value.

    my $region = $s3->get_bucket_location('my-bucket');

Starting with version 0.55, `Amazon::S3::Bucket` will call this
`get_location_constraint()` to determine the region for the
bucket. You can get the region for the bucket by using the `region()`
method of the bucket object.

    my $bucket = $s3->bucket('my-bucket');
    my $bucket_region = $bucket->region;

## get\_logger

Returns the logger object. If you did not set a logger when you
created the object then an instance of `Amazon::S3::Logger` is
returned. You can log to STDERR using this logger. For example:

    $s3->get_logger->debug('this is a debug message');

    $s3->get_logger->trace(sub { return Dumper([$response]) });

## list\_bucket\_all, list\_bucket\_all\_v2

List all keys in this bucket without having to worry about
'marker'. This is a convenience method, but may make multiple requests
to S3 under the hood.

Takes the same arguments as `list_bucket`.

_You are encouraged to use the newer `list_bucket_all_v2` method._

## list\_object\_versions

    list_object_versions( args ) 

Returns metadata about all versions of the objects in a bucket. You
can also use request parameters as selection criteria to return
metadata about a subset of all the object versions.

This method will only return the raw result set and does not perform
pagination or unravel common prefixes as do other methods like
`list_bucket`. This may change in the future.

See [https://docs.aws.amazon.com/AmazonS3/latest/API/API\_ListObjectVersions.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html)
for more information about the request parameters and the result body.

`args` is hash reference containing the following parameters:

- bucket

    Name of the bucket. This method is not vailable for directory buckets.

- headers

    Optional headers. See
    [https://docs.aws.amazon.com/AmazonS3/latest/API/API\_ListObjectVersions.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html)
    for more details regarding optional headers.

- delimiter

    A delimiter is a character that you specify to group keys. All keys
    that contain the same string between the prefix and the first
    occurrence of the delimiter are grouped under a single result element
    in CommonPrefixes. These groups are counted as one result against the
    max-keys limitation. These keys are not returned elsewhere in the
    response.

- encoding-type     

    Requests Amazon S3 to encode the object keys in the response and
    specifies the encoding method to use.

- key-marker        

    Specifies the key to start with when listing objects in a bucket.

- max-keys          

README.md  view on Meta::CPAN

    Your AWS sekkr1t passkey. Be forewarned that setting this environment variable
    on a shared system might leak that information to another user. Be careful.

- AMAZON\_S3\_SKIP\_ACL\_TESTS

    Doesn't matter what you set it to. Just has to be set if you want
    to skip ACLs tests.

- AMAZON\_S3\_SKIP\_PERMISSIONS

    Skip tests that check for enforcement of ACLs...as of this version,
    LocalStack for example does not support enforcement of ACLs.

- AMAZON\_S3\_SKIP\_REGION\_CONSTRAINT\_TEST

    Doesn't matter what you set it to. Just has to be set if you want
    to skip region constraint test.

- AMAZON\_S3\_MINIO

    Doesn't matter what you set it to. Just has to be set if you want
    to skip tests that would fail on minio.

- AMAZON\_S3\_LOCALSTACK

    Doesn't matter what you set it to. Just has to be set if you want
    to skip tests that would fail on LocalStack.

- AMAZON\_S3\_REGIONS

    A comma delimited list of regions to use for testing. The default will
    only test creating a bucket in the local region.

_Consider using an S3 mocking service like `minio` or `LocalStack`
if you want to create real tests for your applications or this module._

Here's bash script for testing using LocalStack

    #!/bin/bash
    # -*- mode: sh; -*-
    
    BUCKET=net-amazon-s3-test-test 
    ENDPOINT_URL=s3.localhost.localstack.cloud:4566
    
    AMAZON_S3_EXPENSIVE_TESTS=1 \
    AMAZON_S3_HOST=$ENDPOINT_URL \
    AMAZON_S3_LOCALSTACK=1 \
    AWS_ACCESS_KEY_ID=test \
    AWS_ACCESS_SECRET_KEY=test  \
    AMAZON_S3_DOMAIN_BUCKET_NAMES=1 make test 2>&1 | tee test.log

To run the tests...clone the project and build the software.

    cd src/main/perl
    ./test.localstack

# ADDITIONAL INFORMATION

## LOGGING AND DEBUGGING

Additional debugging information can be output to STDERR by setting
the `level` option when you instantiate the `Amazon::S3`
object. Levels are represented as a string.  The valid levels are:

    fatal
    error
    warn
    info
    debug
    trace

You can set an optionally pass in a logger that implements a subset of
the `Log::Log4perl` interface.  Your logger should support at least
these method calls. If you do not supply a logger the default logger
(`Amazon::S3::Logger`) will be used.

    get_logger()
    fatal()
    error()
    warn()
    info()
    debug()
    trace()
    level()

At the `trace` level, every HTTP request and response will be output
to STDERR.  At the `debug` level information regarding the higher
level methods will be output to STDERR.  There currently is no
additional information logged at lower levels.

## S3 LINKS OF INTEREST

- [Bucket restrictions and limitations](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)
- [Bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html)
- [Amazon S3 REST API](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)
- [Authenticating Requests (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)
- [Authenticating Requests (AWS Signature Version 2)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html)
- [LocalStack](https://localstack.io)

# SUPPORT

Bugs should be reported via the CPAN bug tracker at

[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Amazon-S3](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Amazon-S3)

For other issues, contact the author.

# REPOSITORY

[https://github.com/rlauer6/perl-amazon-s3](https://github.com/rlauer6/perl-amazon-s3)

# AUTHOR

Original author: Timothy Appnel <tima@cpan.org>

Current maintainer: Rob Lauer <bigfoot@cpan.org>

# SEE ALSO

[Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket), [Net::Amazon::S3](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3AS3)

# COPYRIGHT AND LICENCE

This module was initially based on [Net::Amazon::S3](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3AS3) 0.41, by
Leon Brocard. Net::Amazon::S3 was based on example code from
Amazon with this notice:

_This software code is made available "AS IS" without warranties of any
kind.  You may copy, display, modify and redistribute the software
code either by itself or as incorporated into your code; provided that
you do not remove any proprietary notices.  Your use of this software
code is at your own risk and you waive any claim against Amazon
Digital Services, Inc. or its affiliates with respect to your use of
this software code. (c) 2006 Amazon Digital Services, Inc. or its
affiliates._

The software is released under the Artistic License. The
terms of the Artistic License are described at
http://www.perl.com/language/misc/Artistic.html. Except
where otherwise noted, `Amazon::S3` is Copyright 2008, Timothy
Appnel, tima@cpan.org. All rights reserved.