Net::Amazon::S3::Bucket(3pm) User Contributed Perl Documentation Net::Amazon::S3::Bucket(3pm)

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

version 0.991

  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;

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

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

Takes three positional parameters:

A hash of configuration data for this key.

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

Returns a boolean.

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

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

Returns a boolean.

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

The key to (over)write
Where to copy the key from. Should be in the form "/bucketname/keyname"/.
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.

Changes the metadata associated with an existing key. Arguments:

The key to edit
The new configuration hash to use

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

        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).

Expiration time (epoch time).

Optional arguments

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>

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.

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

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

Returns true on success and false on failure

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 all keys in this bucket.

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

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.

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.

Takes a configuration hash_ref containing:

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

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

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

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

        # 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.
Set specified tags and their respective values.
Is specified (in conjunction with "key") add tag(s) to versioned object.

Returns "true" on success.

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

        # 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.
Is specified (in conjunction with "key") add tag(s) to versioned object.

Returns "true" on success.

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

Net::Amazon::S3

Branislav Zahradník <barney@cpan.org>

This software is copyright (c) 2022 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.

2022-07-18 perl v5.34.0