Provided by: libnet-amazon-s3-perl_0.991-1_all 
NAME
Net::Amazon::S3::Client::Object - An easy-to-use Amazon S3 client object
VERSION
version 0.991
SYNOPSIS
# 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.
METHODS
range
my $value = $object->range ('bytes=1024-10240')->get;
Provides simple interface to ranged download. 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) { ... }
Method doesn't report error when bucket or key doesn't exist.
get
# to get the vaue of an object
my $value = $object->get;
head
# to get the metadata of an object
my %metadata = %{$object->head};
Unlike "exists" this method does report error.
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;
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',
);
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"; the default is "standard".
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 specify the S3 storage class by setting "storage_class" to either "standard",
"reduced_redundancy", "standard_ia", "onezone_ia", "intelligent_tiering", "glacier", or
"deep_archive"; the default is "standard".
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 presigned uri for specified HTTP
method (Signature V4 uses also HTTP method).
Methods providee authenticated uri only for direct object operations.
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 L<HTTP::Response> object. It is necessary to keep the ETags for
each part, as these are required to complete the upload.
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.
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 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.