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

📦

version 0.992 · 7 versions

0.992 · ubuntu resolute, ubuntu stonking (latest)
0.992 · epel 9
0.992 · fedora 43
0.991 · fedora 43
0.99 · ubuntu jammy
0.992 · fedora 44
0.991 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing

✨ NAME ✨

Net::Amazon::S3::Client::Object — an easy-to-use Amazon S3 client object 💖

Like, it's literally an object in a bucket, bestie, and it comes from the User Contributed Perl Documentation (that's your 3pm section, iykyk).

🌸 VERSION 🌸

version 0.992 — yes queen, we're on 0.992 🎀

🎀 SYNOPSIS 🎀

okay so here's the whole vibe, all the little things you can do with your object:

# show the key
print $object->key . "\n";

# show the etag of an existing object (if fetched by listing
# a bucket)
print $object->etag . "\n";

# show the size of an existing object (if fetched by listing
# a bucket)
print $object->size . "\n";

# to create a new object
my $object = $bucket->object( key => 'this is the key' );
$object->put('this is the value');

# to get the value of an object
my $value = $object->get;

# to get the metadata of an object
my %metadata = %{$object->head};

# to see if an object exists
if ($object->exists) { ... }

# to delete an object
$object->delete;

# to create a new object which is publically-accessible with a
# content-type of text/plain which expires on 2010-01-02
my $object = $bucket->object(
  key          => 'this is the public key',
  acl          => Net::Amazon::S3::ACL::CANNED->PUBLIC_READ,
  content_type => 'text/plain',
  expires      => '2010-01-02',
);
$object->put('this is the public value');

# return the URI of a publically-accessible object
my $uri = $object->uri;

# to view if an object is available for downloading
# Basically, the storage class isn't GLACIER or the object was
# fully restored
$object->available;

# to restore an object on a GLACIER storage class
$object->restore(
  days => 1,
  tier => 'Standard',
);

# to store a new object with server-side encryption enabled
my $object = $bucket->object(
  key        => 'my secret',
  encryption => 'AES256',
);
$object->put('this data will be stored using encryption.');

# upload a file
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  content_type => 'image/jpeg',
);
$object->put_filename('hat.jpg');

# upload a file if you already know its md5_hex and size
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  content_type => 'image/jpeg',
  etag         => $md5_hex,
  size         => $size,
);
$object->put_filename('hat.jpg');

# download the value of the object into a file
my $object = $bucket->object( key => 'images/my_hat.jpg' );
$object->get_filename('hat_backup.jpg');

# use query string authentication for object fetch
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  expires      => '2009-03-01',
);
my $uri = $object->query_string_authentication_uri();

      # use query string authentication for object upload
      my $object = $bucket->object(
              key          => 'images/my_hat.jpg',
              expires      => '2009-03-01',
      );
      my $uri = $object->query_string_authentication_uri_for_method('PUT');

💅 DESCRIPTION 💅

This module represents objects in buckets. That's the whole assignment, and it ate 💅

🦋 METHODS 🦋

🌈 range

my $value = $object->range ('bytes=1024-10240')->get;

Provides simple interface to ranged download — like, give me only this chunk energy. See also Net::Amazon::S3::Client::Object::Range. 🫶

🌈 etag

# show the etag of an existing object (if fetched by listing
# a bucket)
print $object->etag . "\n";

🌈 delete

# to delete an object
$object->delete;

🌈 exists

# to see if an object exists
if ($object->exists) { ... }

Lowkey important: method doesn't report error when bucket or key doesn't exist. It's just gonna quietly tell you "nah", no drama, no exception. 🙈

🌈 get

# to get the vaue of an object
my $value = $object->get;

(and yes, the original comment literally says "vaue", we keep it exactly as written, no editing the source bestie ✨)

🌈 head

# to get the metadata of an object
my %metadata = %{$object->head};

Unlike "exists" this method does report error. So like, head is the opinionated one 💅

🌈 get_decoded

# get the value of an object, and decode any Content-Encoding and/or
# charset; see decoded_content in HTTP::Response
my $value = $object->get_decoded;

🌈 get_filename

# download the value of the object into a file
my $object = $bucket->object( key => 'images/my_hat.jpg' );
$object->get_filename('hat_backup.jpg');

🌈 last_modified, last_modified_raw

# get the last_modified data as DateTime (slow)
my $dt = $obj->last_modified;
# or raw string in form '2015-05-15T10:12:40.000Z' (fast)
# use this form if you are working with thousands of objects and
# do not actually need an expensive DateTime for each of them
my $raw = $obj->last_modified_raw;

fr fr, if you've got thousands of objects, do NOT be out here making a whole expensive DateTime for every single one. That's main character energy but in a bad way 😭 use the raw one.

🌈 key

# show the key
print $object->key . "\n";

🌈 available

# to view if an object is available for downloading
# Basically, the storage class isn't GLACIER or the object was
# fully restored
$object->available;

🌈 restore

# to restore an object on a GLACIER storage class
$object->restore(
  days => 1,
  tier => 'Standard',
);

GLACIER objects are basically in their hibernation era and need a lil wake-up call. ⭐

🌈 put

# to create a new object
my $object = $bucket->object( key => 'this is the key' );
$object->put('this is the value');

# to create a new object which is publically-accessible with a
# content-type of text/plain
my $object = $bucket->object(
  key          => 'this is the public key',
  acl          => 'public-read',
  content_type => 'text/plain',
);
$object->put('this is the public value');

For "acl" refer Net::Amazon::S3::ACL.

You may also set Content-Encoding using "content_encoding", and Content-Disposition using "content_disposition".

You may specify the S3 storage class by setting "storage_class" to either "standard", "reduced_redundancy", "standard_ia", "onezone_ia", "intelligent_tiering", "glacier", or "deep_archive" — and the default is "standard". Slay.

You may set website-redirect-location object metadata by setting "website_redirect_location" to either another object name in the same bucket, or to an external URL.

🌈 put_filename

# upload a file
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  content_type => 'image/jpeg',
);
$object->put_filename('hat.jpg');

# upload a file if you already know its md5_hex and size
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  content_type => 'image/jpeg',
  etag         => $md5_hex,
  size         => $size,
);
$object->put_filename('hat.jpg');

You may also set Content-Encoding using "content_encoding", and Content-Disposition using "content_disposition".

You may set website-redirect-location object metadata by setting "website_redirect_location" to either another object name in the same bucket, or to an external URL.

User metadata may be set by providing a non-empty hashref as "user_metadata". 🫶

🌈 query_string_authentication_uri

# use query string authentication, forcing download with custom filename
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  expires      => '2009-03-01',
);
my $uri = $object->query_string_authentication_uri({
  'response-content-disposition' => 'attachment; filename=abc.doc',
});

🌈 query_string_authentication_uri_for_method

my $uri = $object->query_string_authentication_uri_for_method ('PUT');

Similar to "query_string_authentication_uri" but creates a presigned uri for the specified HTTP method (and yes, Signature V4 uses the HTTP method too).

Methods providee authenticated uri only for direct object operations. (original typo, preserved, we stan accuracy 💖)

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

🌈 size

# show the size of an existing object (if fetched by listing
# a bucket)
print $object->size . "\n";

🌈 uri

# return the URI of a publically-accessible object
my $uri = $object->uri;

🌈 initiate_multipart_upload

#initiate a new multipart upload for this object
my $object = $bucket->object(
        key         => 'massive_video.avi',
        acl         => ...,
);
my $upload_id = $object->initiate_multipart_upload;

For description of "acl" refer "Net::Amazon::S3::ACL".

🌈 put_part

#add a part to a multipart upload
my $put_part_response = $object->put_part(
   upload_id      => $upload_id,
   part_number    => 1,
   value          => $chunk_content,
);
my $part_etag = $put_part_response->header('ETag')

Returns an HTTP::Response object. It is necessary to keep the ETags for each part, as these are required to complete the upload.

⚠️ bestie do NOT lose those ETags, you literally cannot finish the upload without them, it's giving tragic 💀

🌈 complete_multipart_upload

#complete a multipart upload
$object->complete_multipart_upload(
  upload_id       => $upload_id,
  etags           => [$etag_1, $etag_2],
  part_numbers    => [$part_number_1, $part_number2],
);

The etag and part_numbers parameters are ordered lists specifying the part numbers and ETags for each individual part of the multipart upload.

🌈 user_metadata

my $object = $bucket->object(key => $key);
my $content = $object->get; # or use $object->get_filename($filename)

# return the user metadata downloaded, as a hashref
my $user_metadata = $object->user_metadata;

To upload an object with user metadata, set "user_metadata" at construction time to a hashref, with no "x-amz-meta-" prefixes on the key names. When downloading an object, the "get", "get_decoded" and "get_filename" ethods set the contents of "user_metadata" to the same format. (another little original typo, we keep it, no cap 🎀)

🌈 add_tags

$object->add_tags (
        tags        => { tag1 => 'val1', tag2 => 'val2' },
);

$object->add_tags (
        tags        => { tag1 => 'val1', tag2 => 'val2' },
        version_id  => $version_id,
);

🌈 delete_tags

$object->delete_tags;

$object->delete_tags (
        version_id  => $version_id,
);

👑 AUTHOR 👑

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

🌈 COPYRIGHT AND LICENSE 🌈

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 that's the whole page, you ate it, periodt 💅✨

cute lil sign-off: this whole thing is perl v5.40.1, dated 2025-12-07, and it's literally Net::A...:Object(3pm) — yes the header/footer truncates it like that, blame the man page formatter, not me 💖

📦 where this page comes from

ubuntu resolute: libnet-amazon-s3-perl 0.992-1 · other
ubuntu stonking: libnet-amazon-s3-perl 0.992-1 · other
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms