Net::Amazon::S3::Client::Object - An easy-to-use Amazon S3 client object
version 0.991
# 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');
This module represents objects in buckets.
my $value = $object->range ('bytes=1024-10240')->get;
Provides simple interface to ranged download. See also Net::Amazon::S3::Client::Object::Range.
# show the etag of an existing object (if fetched by listing # a bucket) print $object->etag . "\n";
# to delete an object $object->delete;
# to see if an object exists if ($object->exists) { ... }
Method doesn't report error when bucket or key doesn't exist.
# to get the vaue of an object my $value = $object->get;
# to get the metadata of an object my %metadata = %{$object->head};
Unlike exists this method does report error.
exists
# 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;
# download the value of the object into a file my $object = $bucket->object( key => 'images/my_hat.jpg' ); $object->get_filename('hat_backup.jpg');
# 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;
# show the key print $object->key . "\n";
# 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 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.
acl
You may also set Content-Encoding using content_encoding, and Content-Disposition using content_disposition.
content_encoding
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.
storage_class
standard
reduced_redundancy
standard_ia
onezone_ia
intelligent_tiering
glacier
deep_archive
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.
website_redirect_location
# 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');
User metadata may be set by providing a non-empty hashref as user_metadata.
user_metadata
# 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', });
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
# show the size of an existing object (if fetched by listing # a bucket) print $object->size . "\n";
# return the URI of a publically-accessible object my $uri = $object->uri;
#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.
Net::Amazon::S3::ACL
#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 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.
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.
x-amz-meta-
get
get_decoded
get_filename
$object->add_tags ( tags => { tag1 => 'val1', tag2 => 'val2' }, ); $object->add_tags ( tags => { tag1 => 'val1', tag2 => 'val2' }, version_id => $version_id, );
$object->delete_tags; $object->delete_tags ( version_id => $version_id, );
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.
To install Net::Amazon::S3, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Amazon::S3
CPAN shell
perl -MCPAN -e shell install Net::Amazon::S3
For more information on module installation, please visit the detailed CPAN module installation guide.