view release on metacpan or  search on metacpan

lib/Amazon/S3.pm  view on Meta::CPAN

=back

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
  }

=head2 get_bucket_location

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

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

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

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

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

=head2 get_logger

Returns the logger object. If you did not set a logger when you
created the object then an instance of C<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]) });

=head2 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 C<list_bucket>.

I<You are encouraged to use the newer C<list_bucket_all_v2> method.>

=head2 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
C<list_bucket>. This may change in the future.

See L<https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html>
for more information about the request parameters and the result body.

C<args> is hash reference containing the following parameters:

=over 5

=item bucket

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

=item headers

Optional headers. See
L<https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html>
for more details regarding optional headers.

=item 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.

=item encoding-type     

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

=item key-marker        

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

=item max-keys          

Sets the maximum number of keys returned in the response. By default,
the action returns up to 1,000 key names. The response might contain
fewer keys but will never contain more. If additional keys satisfy the
search criteria, but were not returned because max-keys was exceeded,
the response contains <isTruncated>true</isTruncated>. To return the
additional keys, see key-marker and version-id-marker.

default: 1000

=item prefix            

Use this parameter to select only those keys that begin with the
specified prefix. You can use prefixes to separate a bucket into
different groupings of keys. (You can think of using prefix to make
groups in the same way that you'd use a folder in a file system.) You
can use prefix with delimiter to roll up numerous objects into a
single result under CommonPrefixes.

=item version-id-marker 

Specifies the object version you want to start listing from.

=back

=head2 err

The S3 error code for the last error encountered.

=head2 errstr

A human readable error string for the last error encountered.

=head2 error

The decoded XML string as a hash object of the last error.

=head2 last_response

Returns the last L<HTTP::Response> object.

=head2 last_request

Returns the last L<HTTP::Request> object.

=head2 level

Set the logging level.

default: error

=head2 turn_on_special_retry

Called to add extra retry codes if retry has been set

=head2 turn_off_special_retry

Called to turn off special retry codes when we are deliberately
triggering them

=head1 ABOUT

This module contains code modified from Amazon that contains the
following 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.