Amazon...Bucket(3pm)

📦
version 2.0.2 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 Amazon::S3::Bucket 💖

okay bestie, welcome to Amazon...Bucket(3pm) — that's the User Contributed Perl Documentation corner of the universe, and today we're getting into Amazon::S3::Bucket 🌸

✨ NAME ✨

Amazon::S3::Bucket — a container class for a S3 bucket and its contents. like, a bucket that holds your bucket energy 🪣💅

🌈 SYNOPSIS 🌈

here's the whole vibe in one go, no cap:

use Amazon::S3;

# creates bucket object (no "bucket exists" check)
my $bucket = $s3->bucket("foo");

# create resource with meta data (attributes)
my $keyname = 'testing.txt';
my $value   = 'T';
$bucket->add_key(
    $keyname, $value,
    {   content_type        => 'text/plain',
        'x-amz-meta-colour' => 'orange',
    }
);

# list keys in the bucket
$response = $bucket->list
    or die $s3->err . ": " . $s3->errstr;
print $response->{bucket}."\n";
for my $key (@{ $response->{keys} }) {
      print "\t".$key->{key}."\n";
}

# check if resource exists.
print "$keyname exists\n" if $bucket->head_key($keyname);

# delete key from bucket
$bucket->delete_key($keyname);

🦋 DESCRIPTION 🦋

It's the class for interacting with AWS S3 buckets. that's it, that's the description, and honestly? iconic 💜

💅 METHODS AND SUBROUTINES 💅

🎀 new

Instaniates a new bucket object. (yes the typo is load-bearing, we keep it 💀)

Pass a hash or hash reference containing various options:

  • bucket (required) — the name (identifier) of the bucket.
  • account (required) — the S3::Amazon object (representing the S3 account) this bucket is associated with.
  • buffer_size — the buffer size used for reading and writing objects to S3.
    • default: 4K
  • region — if no region is set and verify_region is set to true, the region of the bucket will be determined by calling the get_location_constraint method. Note that this will decrease performance of the constructor. If you know the region or are operating in only 1 region, set the region in the account object (Amazon::S3).
  • logger — sets the logger. The logger should be a blessed reference capable of providing at least a debug and trace method for recording log messages. If no logger object is passed the account object's logger object will be used.
  • verify_region — indicates that the bucket's region should be determined by calling the get_location_constraint method.
    • default: false
NOTE: This method does not check if a bucket actually exists unless you set verify_region to true. If the bucket does not exist, the constructor will set the region to the default region specified by the Amazon::S3 object (account) that you passed.

Typically a developer will not call this method directly, but work through the interface in S3::Amazon that will handle their creation. lowkey that's the move 🫶

🍓 add_key

add_key( key, value, configuration)

Write a new or existing object to S3. new key, old key, we don't discriminate, we just write ✨

  • key — a string identifier for the object being written to the bucket.
  • value — a SCALAR string representing the contents of the object.
  • configuration — a HASHREF of configuration data for this key. The configuration is generally the HTTP headers you want to pass to the S3 service. The client library will add all necessary headers. Adding them to the configuration hash will override what the library would send and add headers that are not typically required for S3 interactions.
    • acl_short (optional) — in addition to additional and overridden HTTP headers, this HASHREF can have a acl_short key to set the permissions (access) of the resource without a separate call via add_acl or in the form of an XML document. See the documentation in add_acl for the values and usage.

Returns a boolean indicating the sucess or failure of the call. Check err and errstr for error messages if this operation fails. To examine the raw output of the response from the API call, use the last_response() method.

my $retval = $bucket->add_key('foo', $content, {});

if ( !$retval ) {
  print STDERR Dumper([$bucket->err, $bucket->errstr, $bucket->last_response]);
}

🌸 add_key_filename

The method works like add_key except the value is assumed to be a filename on the local file system. The file will be streamed rather then loaded into memory in one big chunk. memory said "not today" and honestly, same 🧚

💜 copy_object %parameters

Copies an object from one bucket to another bucket. Note that the bucket represented by the bucket object is the destination. Returns a hash reference to the response object (CopyObjectResult).

Headers returned from the request can be obtained using the last_response() method.

my $headers = { $bucket->last_response->headers->flatten };

Throws an exception if the response code is not 2xx. You can get an extended error message using the errstr() method.

my $result = eval { return $s3->copy_object( key => 'foo.jpg',
    source => 'boo.jpg' ); };

if ($@) {
  die $s3->errstr;
}

Examples:

$bucket->copy_object( key => 'foo.jpg', source => 'boo.jpg' );

$bucket->copy_object(
  key    => 'foo.jpg',
  source => 'boo.jpg',
  bucket => 'my-source-bucket'
);

$bucket->copy_object(
  key     => 'foo.jpg',
  headers => { 'x-amz-copy-source' => 'my-source-bucket/boo.jpg'
  );

See CopyObject for more details.

%parameters is a list of key/value pairs described below:

  • key (required) — name of the destination key in the bucket represented by the bucket object.
  • headers (optional) — hash or array reference of headers to send in the request.
  • bucket (optional) — name of the source bucket. Default is the same bucket as the destination.
  • source (optional) — name of the source key in the source bucket. If not provided, you must provide the source in the x-amz-copy-source header.

🎀 head_key $key_name

Returns a configuration HASH of the given key. If a key does not exist in the bucket undef will be returned.

HASH will contain the following members:

  • content_length
  • content_type
  • etag
  • value

💖 delete_key

delete_key(key, [version])

Permanently removes $key_name from the bucket. Returns a boolean value indicating the operation's success. permanently. like, gone gone. no take-backs 😭

⭐ delete_keys @keys

⭐ delete_keys $keys

Permanently removes keys from the bucket. Returns the response body from the API call. Returns undef on non '2xx' return codes.

See "Deleting Amazon S3 objects" at https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeletingObjects.html

The argument to delete_keys can be:

  • list of key names
  • an array of hashes where each hash reference contains the keys Key and optionally VersionId.
  • an array of scalars where each scalar is a key name
  • a hash of options where the hash contains
    • quiet — Boolean indicating quiet mode
    • keys — an array of keys containing scalars or hashes as describe above.
  • a callback that returns the key and optionally the version id

Examples:

# delete a list of keys
$bucket->delete_keys(qw( foo bar baz));

# delete an array of keys
$bucket->delete_keys([qw(foo bar baz)]);

# delete an array of keys in quiet mode
$bucket->delete({ quiet => 1, keys => [ qw(foo bar baz) ]);

# delete an array of versioned objects
$bucket->delete_keys([ { Key => 'foo', VersionId => '1'} ]);

# callback
my @key_list = qw(foo => 1, bar => 3, biz => 1);

$bucket->delete_keys(
  sub {
    return ( shift @key_list, shift @key_list );
  }
);

When using a callback, the keys are deleted in bulk. The DeleteObjects API is only called once. efficient queen behavior 👑

🌈 delete_bucket

Permanently removes the bucket from the server. A bucket cannot be removed if it contains any keys (contents). empty bucket or no bucket, them's the rules 💀

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

🦋 get_key key, [method, headers, uri_params]

🦋 get_key hashref

Takes a key and optional arguments and returns the hash of metatdata which includes the contents of the S3 object.

Example:

$bucket->get_key(
  key        => 'foo',
  uri_params => { versionId => $version },
  headers    => { Range     => 'bytes=0-9' }
);
  • key — key name
  • method — HTTP method (GET or HEAD)
    • default: GET
  • headers — a hashref of additional headers to send with the request
  • uri-params — a hashref containing key/value pairs representing the URI parameters you want to include in the request. Possible parameters are shown below.

The method returns undef if the key does not exist in the bucket and throws an exception (dies) on server errors.

On success, the method returns a HASHREF containing:

  • content_type
  • etag
  • value
  • @meta
  • content_range
  • last_modified
Note that the etag for ranged gets is the MD5 value for the entire file. sneaky but true 🫶

🧚 get_key_filename $key_name, [$method, $filename, $headers, $uri_params]

🧚 get_key_filename $args

Pass a list of arguments or a hash of key value/pairs.

This method works like get_key, but takes an added filename that the S3 resource will be written to.

If filename is undefined or an empty string, the a file with the key name will be created.

💅 list

List all keys in this bucket.

See list_bucket in Amazon::S3 for documentation of this method.

💅 list_v2

See list_bucket_v2 in 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. she's thorough like that ✨

See list_bucket_all in Amazon::S3 for documentation of this method.

💅 list_all_v2

Same as list_all but uses the version 2 API for listing keys.

See list_bucket_all_v2 in Amazon::S3 for documentation of this method.

👑 get_acl

Retrieves the Access Control List (ACL) for the bucket or resource as an XML document.

  • key — the key of the stored resource to fetch. This parameter is optional. By default the method returns the ACL for the bucket itself.

🌸 set_acl

set_acl(acl)

okay bestie we're not done, this page keeps going — part 2 is right there, stay with me 💖

so this one sets the Access Control List (aka the ACL, iykyk 💅) for the bucket or for a specific resource. It needs a HASHREF argument, and that hashref has to carry one of these keys:

  • acl_xml — a string of XML holding your access control info, matching Amazon's published schema. That's the full-detail route ✨
  • acl_short — the shorthand shortcut for the common ACL flavours, so you don't have to write out a whole ACL XML document. Amazon's own S3 API docs define these recognized acl_short types:
    • private — the owner gets FULL_CONTROL, and literally nobody else gets any access rights at all. This is the default 🙈
    • public-read — owner gets FULL_CONTROL, and the anonymous principal gets granted READ. Put this on an object and it can be read straight from a browser with zero authentication. open book energy 📖
    • public-read-write — owner gets FULL_CONTROL, and the anonymous principal gets READ and WRITE. Super handy on a bucket if you want any anonymous user to be able to PUT objects into it. (bestie, think before you do this one, okay? 👀)
    • authenticated-read — owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user gets READ.
  • key — the key name you want to apply the permissions to. If you don't hand over a key, the bucket ACL is what gets set. 🎀

Returns a boolean that tells you whether the operation succeeded.

get_location_constraint

Hands back the location constraint — that's the region the bucket lives in, bestie 🗺️ — for a bucket. If there's no location constraint, you get undef.

The valid values it might return you:

 af-south-1
 ap-east-1
 ap-northeast-1
 ap-northeast-2
 ap-northeast-3
 ap-south-1
 ap-southeast-1
 ap-southeast-2
 ca-central-1
 cn-north-1
 cn-northwest-1
 EU
 eu-central-1
 eu-north-1
 eu-south-1
 eu-west-1
 eu-west-2
 eu-west-3
 me-south-1
 sa-east-1
 us-east-2
 us-gov-east-1
 us-gov-west-1
 us-west-1
 us-west-2

Wanna go deeper on location constraints? Go read the docs for GetBucketLocation at <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html>. 🔥

err

The S3 error code for the last error the account ran into.

errstr

A human-readable error string for the last error the account ran into. Actual words, imagine that 😭

error

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

last_response

Gives you back the last HTTP::Response from an API call. receipts, basically 🧾

🌈 MULTIPART UPLOAD SUPPORT 🌈

Straight from Amazon's website, and I quote:

Multipart upload lets you upload a single object as a set of parts. Each part is a contiguous portion of the object's data. You can upload these object parts independently and in any order. If transmission of any part fails, you can retransmit that part without affecting other parts. After all of your object's parts are uploaded, Amazon S3 assembles those parts and creates the object. As a general rule, once your object size reaches 100 MB, you should consider using multipart uploads instead of uploading the object in a single operation.

Peep <https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html> for more on multipart uploads 👑

  • Maximum object size: 5TB
  • Maximum number of parts: 10,000
  • Part numbers: 1 to 10,000 (inclusive)
  • Part size: 5MB to 5GB. There is no limit on the last part of your multipart upload 🎉
  • Maximum number of parts returned for a list parts request: 1000
  • Maximum number of multipart uploads returned in a list multipart uploads request: 1000

A multipart upload kicks off by calling initiate_multipart_upload(). That hands you back an identifier, and you use that identifier in all the calls that come after. 🦋

 my $bucket = $s3->bucket('my-bucket');
 my $id = $bucket->initiate_multipart_upload('some-big-object');

 my $part_list = {};

 my $part = 1;
 my $etag = $bucket->upload_part_of_multipart_upload('my-bucket', $id, $part, $data, length $data);
 $part_list{$part++} = $etag;

 $bucket->complete_multipart_upload('my-bucket', $id, $part_list);

upload_multipart_object( ... ) — there's a convenience routine called upload_multipart_object that wraps the whole multipart upload process up in a little bow 🎀 It takes a hash or a hash reference of arguments. If it works, you get back a reference to a hash containing the part numbers and etags of the uploaded parts.

You can hand it a data object, a callback routine, or a file handle. Pick your fighter:

  • key — name of the key to create.
  • data — a scalar object holding the data to write to S3.
  • callback — optionally, give it a callback routine that'll get called over and over until you pass a buffer with a length of 0. Your callback receives no arguments but it should return a tuple: a reference to a scalar object holding the data to write, plus a scalar that represents the length of that data. The moment you return a zero-length buffer, the multipart process gets completed. ✨
  • fh — file handle of an open file. Heads up: the file must be bigger than the minimum chunk size for multipart uploads, otherwise this method will throw an exception. 🚨
  • abort_on_error — says whether the multipart upload should get aborted when an error shows up. Amazon will charge you for the storage of parts that have already been uploaded unless you abort the upload. So like... yeah. 💀

default: true

abort_multipart_upload

 abort_multipart_upload(key, multpart-upload-id)

Aborts a multipart upload. bye felicia 👋

complete_multipart_upload

 complete_multipart_upload(key, multpart-upload-id, parts)

Signals that a multipart upload is complete. parts is a reference to a hash of part numbers and etags. ✅

initiate_multipart_upload

 initiate_multipart_upload(key, headers)

Kicks off a multipart upload. Returns an id, and you'll use that id in the subsequent call to upload_part_of_multipart_upload(). 🚀

list_multipart_upload_parts

Lists all the uploaded parts of a multipart upload.

list_multipart_uploads

Lists multipart uploads that are in progress.

upload_part_of_multipart_upload

 upload_part_of_multipart_upload(key, id, part, data, length)

Uploads a portion of a multipart upload. bit by bit, we get there 🐛

  • key — name of the key in the bucket to create.
  • id — the multipart-upload id returned in the initiate_multipart_upload call.
  • part — the next part number (part numbers start at 1).
  • data — scalar, or a reference to a scalar, holding the data to upload.
  • length (optional) — length of the data.

🌸 SEE ALSO 🌸

Amazon::S3 — the main character, honestly 👑

💖 AUTHOR 💖

Please see the Amazon::S3 manpage for author, copyright, and license information. (Yes bestie, all the legal bits live over there 🫶)

🌟 CONTRIBUTORS 🌟

  • Rob Lauer
  • Jojess Fournier
  • Tim Mullin
  • Todd Rinaldo
  • luiserd97

🚨 POD ERRORS 🚨

Hey! The above document had some coding errors, which are explained below:

Around line 1871:

    Unknown directive: =heads

and that's a wrap on Amazon...Bucket(3pm)! 🎉 this one came out of perl v5.40.1, dated 2025-12-20, and it's the Amazon...Bucket(3pm) page from the User Contributed Perl Documentation. go forth and slay your S3 buckets, bestie 💅✨🦋

📦 where this page comes from