Net::A...:Bucket(3pm)

✨ NAME ✨

Net::Amazon::S3::Bucket — a ✨convenience object✨ for working with Amazon S3 buckets 💖

(and yes bestie, this whole page you're reading is Net::A...:Bucket(3pm) — the name up top is just abbreviated like that, no cap)

🌸 VERSION 🌸

version 0.992 💅

🦋 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 💜

Okay so this module is your little bestie representative for an S3 bucket — like, the vibe of one bucket, as an object 🪣✨

You don't just manifest a bucket object out of thin air tho. You get it from the Net::Amazon::S3 object. That's the plug. 🔌

👑 METHODS 👑

🎀 new

Creates a brand new bucket object, slay. It expects a hash that has these two arguments in it:

• bucket
• account

🎀 add_key

Takes three positional parameters, in order:

• key
• value
• configuration — a hash of configuration data for this key, containing things like:
  • acl
  • encryption
  • any additional HTTP header

(see Net::Amazon::S3::Operation::Object::Add::Request for the details, iykyk)

Returns a boolean. 🫶

🎀 add_key_filename

Use this one when you gotta upload a large file to S3, like actually large. Takes three positional parameters:

• key
• filename
• configuration — a hash of configuration data for this key. (See synopsis, bestie);

Returns a boolean. 💖

🎀 copy_key

Creates (or replaces) a key, and copies its contents over from another key somewhere else in S3 🌈 Takes these 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 that's hanging out 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 a uri presigned with your credentials, iconic 🔥

When you're using Signature V4 you have to also specify which HTTP method this presigned uri will be used for (default: GET).

Method provides authenticated uri only for direct object operations, jsyk.

Method follows API's "CALLING CONVENTION".

Recognized positional arguments (mandatory, no skipping them bestie):

• 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 one 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 💀 no takebacks, no undos, it's giving deleted.

Returns true on success and false on failure.

🎀 delete_bucket

Deletes the current bucket object from the server. Takes no arguments.

Fails if the bucket has anything in it. (Amazon said empty bucket or nothing, periodt.)

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

🎀 list

Lists all the keys in this bucket 🌸

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

🎀 list_all

Lists all the keys in this bucket without having to worry about 'marker'. This may make multiple requests to S3 under the hood, sneaky but efficient ✨

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 that was 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) 2025 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.

---

okay bestie that's the whole page, you ate that 💅 and for the receipts at the bottom: this page came from perl v5.40.1, dated 2025-12-07, and it's living under the name Net::A...:Bucket(3pm). go forth and bucket 🪣✨🦋