Net::Amazon::S3::Bucket(3)

NAME
Net::Amazon::S3::Bucket - convenience object for working with Amazon S3 buckets

VERSION
version 0.99

SYNOPSIS
  use Net::Amazon::S3;

  my $bucket = $s3->bucket("foo");

  ok($bucket->add_key("key", "data"));
  ok($bucket->add_key("key", "data", {
     content_type => "text/html",
    'x-amz-meta-colour' => 'orange',
  }));

  # Enable server-side encryption
  ok($bucket->add_key("key", "data", {
     encryption => 'AES256',
  }));

  # the err and errstr methods just proxy up to the Net::Amazon::S3's
  # objects err/errstr methods.
  $bucket->add_key("bar", "baz") or
      die $bucket->err . $bucket->errstr;

  # fetch a key
  $val = $bucket->get_key("key");
  is( $val->{value},               'data' );
  is( $val->{content_type},        'text/html' );
  is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
  is( $val->{'x-amz-meta-colour'}, 'orange' );

  # fetch a part of the key
  $val = $bucket->get_key("key", { range => "bytes=1024-10240" });

  # returns undef on missing or on error (check $bucket->err)
  is(undef, $bucket->get_key("non-existing-key"));
  die $bucket->errstr if $bucket->err;

  # fetch a key's metadata
  $val = $bucket->head_key("key");
  is( $val->{value},               '' );
  is( $val->{content_type},        'text/html' );
  is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
  is( $val->{'x-amz-meta-colour'}, 'orange' );

  # delete a key
  ok($bucket->delete_key($key_name));
  ok(! $bucket->delete_key("non-exist-key"));

  # delete the entire bucket (Amazon requires it first be empty)
  $bucket->delete_bucket;

DESCRIPTION
This module represents an S3 bucket. You get a bucket object from the Net::Amazon::S3 object.

METHODS

  new
Create a new bucket object. Expects a hash containing these two arguments:

bucket
account

  add_key
Takes three positional parameters:

key
value
configuration
    A hash of configuration data for this key.

    acl
    encryption
    any additional HTTP header

    See Net::Amazon::S3::Operation::Object::Add::Request for details

Returns a boolean.

  add_key_filename
Use this to upload a large file to S3. Takes three positional parameters:

key
filename
configuration
    A hash of configuration data for this key. (See synopsis);

Returns a boolean.

  copy_key
Creates (or replaces) a key, copying its contents from another key elsewhere in S3. Takes the following parameters:

key The key to (over)write

source
    Where to copy the key from. Should be in the form "/bucketname/keyname"/.

conf
    Optional configuration hash. If present and defined, the configuration (ACL and headers) there will be used for the new key; otherwise it will be copied from the source key.

  edit_metadata
Changes the metadata associated with an existing key. Arguments:

key The key to edit

conf
    The new configuration hash to use

  head_key KEY
Takes the name of a key in this bucket and returns its configuration hash

  query_string_authentication_uri KEY, EXPIRES_AT
        my $uri = $bucket->query_string_authentication_uri (
                key => 'foo',
                expires_at => time + 3_600, # valid for one hour
        );

        my $uri = $bucket->query_string_authentication_uri (
                key => 'foo',
                expires_at => time + 3_600,
                method => 'PUT',
        );

Returns uri presigned with your credentials.

When used with Signature V4 you have to specify also HTTP method this presigned uri will be used for (default: "GET")

Method provides authenticated uri only for direct object operations.

Method follows API's "CALLING CONVENTION".

Recognized positional arguments (mandatory).

key
expires_at
    Expiration time (epoch time).

Optional arguments

method
    Default: "GET"

    Intended HTTP method this uri will be presigned for.

    Signature V2 doesn't use it but Signature V4 does.

    See <https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html>

  get_key $key_name [$method]
Takes a key name and an optional HTTP method (which defaults to "GET". Fetches the key from AWS.

On failure:

Returns undef on missing content, throws an exception (dies) on server errors.

On success:

Returns a hashref of { content_type, etag, value, @meta } on success. Other values from the server are there too, with the key being lowercased.

  get_key_filename $key_name $method $filename
Use this to download large files from S3. Takes a key name and an optional HTTP method (which defaults to "GET". Fetches the key from AWS and writes it to the filename. THe value returned will be empty.

On failure:

Returns undef on missing content, throws an exception (dies) on server errors.

On success:

Returns a hashref of { content_type, etag, value, @meta } on success

  delete_key $key_name
Removes $key from the bucket. Forever. It's gone after this.

Returns true on success and false on failure

  delete_bucket
Delete the current bucket object from the server. Takes no arguments.

Fails if the bucket has anything in it.

This is an alias for "$s3->delete_bucket($bucket)"

  list
List all keys in this bucket.

see "list_bucket" in Net::Amazon::S3 for documentation of this method.

  list_all
List all keys in this bucket without having to worry about 'marker'. This may make multiple requests to S3 under the hood.

see "list_bucket_all" in Net::Amazon::S3 for documentation of this method.

  get_acl
Takes one optional positional parameter

key (optional)
    If no key is specified, it returns the acl for the bucket.

Returns an acl in XML format.

  set_acl
Takes a configuration hash_ref containing:

acl_xml (cannot be used in conjunction with acl_short)
    An XML string which contains access control information which matches Amazon's published schema. There is an example of one of these XML strings in the tests for this module.

acl_short (cannot be used in conjunction with acl_xml)
    You can use the shorthand notation instead of specifying XML for certain 'canned' types of acls.

    (from the Amazon API documentation)

    private: Owner gets FULL_CONTROL. No one else has any access rights. This is the default.

    public-read:Owner gets FULL_CONTROL and the anonymous principal is granted READ access. If this policy is used on an object, it can be read from a browser with no authentication.

    public-read-write:Owner gets FULL_CONTROL, the anonymous principal is granted READ and WRITE access. This is a useful policy to apply to a bucket, if you intend for any anonymous user to PUT objects into the bucket.

    authenticated-read:Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.

key (optional)
    If the key is not set, it will apply the acl to the bucket.

Returns a boolean.

  get_location_constraint
Retrieves the location constraint set when the bucket was created. Returns a string (eg, 'EU'), or undef if no location constraint was set.

  err
The S3 error code for the last error the object ran into

  errstr
A human readable error string for the last error the object ran into

  add_tags
        # Add tags for a bucket
        $s3->add_tags ({
                bucket => 'bucket-name',
                tags   => { tag1 => 'value-1', tag2 => 'value-2' },
        });

        # Add tags for an object
        $s3->add_tags ({
                bucket => 'bucket-name',
                key    => 'key',
                tags   => { tag1 => 'value-1', tag2 => 'value-2' },
        });

Takes configuration parameters

key (optional, scalar)
    If key is specified, add tag(s) to object, otherwise on bucket.

tags (mandatory, hashref)
    Set specified tags and their respective values.

version_id (optional)
    Is specified (in conjunction with "key") add tag(s) to versioned object.

Returns "true" on success.

Returns "false" and sets "err"/"errstr" otherwise.

  delete_tags
        # Add tags for a bucket
        $s3->delete_tags ({
                bucket => 'bucket-name',
        });

        # Add tags for an object
        $s3->delete_tags ({
                bucket     => 'bucket-name',
                key        => 'key',
                version_id => $version_id,
        });

Takes configuration parameters

key (optional, scalar)
    If key is specified, add tag(s) to object, otherwise on bucket.

version_id (optional)
    Is specified (in conjunction with "key") add tag(s) to versioned object.

Returns "true" on success.

Returns "false" and sets "err"/"errstr" otherwise.

SEE ALSO
Net::Amazon::S3

AUTHOR
Branislav Zahradník <barney@cpan.org>

COPYRIGHT AND LICENSE
This software is copyright (c) 2021 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník.

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