view release on metacpan or  search on metacpan

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

NOTE: CommonPrefixes isn't currently supported by Amazon::S3. 

Example:

Suppose I have the keys:

 bar/baz
 bar/buz
 bar/buz/biz
 bar/buz/zip

And I'm only interest in object directly below 'bar'

 prefix=bar/
 delimiter=/

Would yield:

 bar/baz
 bar/buz

Omitting the delimiter would yield:

 bar/baz
 bar/buz
 bar/buz/biz
 bar/buz/zip

=item max-keys 

This optional argument limits the number of results returned in
response to your query. Amazon S3 will return no more than this
number of results, but possibly less. Even if max-keys is not
specified, Amazon S3 will limit the number of results in the response.
Check the IsTruncated flag to see if your results are incomplete.
If so, use the C<Marker> parameter to request the next page of results.
For the purpose of counting C<max-key>s, a 'result' is either a key
in the 'Contents' collection, or a delimited prefix in the
'CommonPrefixes' collection. So for delimiter requests, max-keys
limits the total number of list results, not just the number of
keys.

=item marker

This optional parameter enables pagination of large result sets.
C<marker> specifies where in the result set to resume listing. It
restricts the response to only contain results that occur alphabetically
after the value of marker. To retrieve the next page of results,
use the last key from the current page of results as the marker in
your next request.

See also C<next_marker>, below. 

If C<marker> is omitted,the first page of results is returned. 

=back

Returns C<undef> on error and a reference to a hash of data on success:

The return value looks like this:

  {
   bucket       => $bucket_name,
   prefix       => $bucket_prefix, 
   marker       => $bucket_marker, 
   next_marker  => $bucket_next_available_marker,
   max_keys     => $bucket_max_keys,
   is_truncated => $bucket_is_truncated_boolean
   keys          => [$key1,$key2,...]
  }

=over

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

=item next_marker 

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

=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