.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::Amazon::S3::Client::Object 3pm"
.TH Net::Amazon::S3::Client::Object 3pm "2022-07-18" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Amazon::S3::Client::Object \- An easy\-to\-use Amazon S3 client object
.SH "VERSION"
.IX Header "VERSION"
version 0.991
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # show the key
\&  print $object\->key . "\en";
\&
\&  # show the etag of an existing object (if fetched by listing
\&  # a bucket)
\&  print $object\->etag . "\en";
\&
\&  # show the size of an existing object (if fetched by listing
\&  # a bucket)
\&  print $object\->size . "\en";
\&
\&  # to create a new object
\&  my $object = $bucket\->object( key => \*(Aqthis is the key\*(Aq );
\&  $object\->put(\*(Aqthis is the value\*(Aq);
\&
\&  # 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          => \*(Aqthis is the public key\*(Aq,
\&    acl          => Net::Amazon::S3::ACL::CANNED\->PUBLIC_READ,
\&    content_type => \*(Aqtext/plain\*(Aq,
\&    expires      => \*(Aq2010\-01\-02\*(Aq,
\&  );
\&  $object\->put(\*(Aqthis is the public value\*(Aq);
\&
\&  # 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\*(Aqt GLACIER or the object was
\&  # fully restored
\&  $object\->available;
\&
\&  # to restore an object on a GLACIER storage class
\&  $object\->restore(
\&    days => 1,
\&    tier => \*(AqStandard\*(Aq,
\&  );
\&
\&  # to store a new object with server\-side encryption enabled
\&  my $object = $bucket\->object(
\&    key        => \*(Aqmy secret\*(Aq,
\&    encryption => \*(AqAES256\*(Aq,
\&  );
\&  $object\->put(\*(Aqthis data will be stored using encryption.\*(Aq);
\&
\&  # upload a file
\&  my $object = $bucket\->object(
\&    key          => \*(Aqimages/my_hat.jpg\*(Aq,
\&    content_type => \*(Aqimage/jpeg\*(Aq,
\&  );
\&  $object\->put_filename(\*(Aqhat.jpg\*(Aq);
\&
\&  # upload a file if you already know its md5_hex and size
\&  my $object = $bucket\->object(
\&    key          => \*(Aqimages/my_hat.jpg\*(Aq,
\&    content_type => \*(Aqimage/jpeg\*(Aq,
\&    etag         => $md5_hex,
\&    size         => $size,
\&  );
\&  $object\->put_filename(\*(Aqhat.jpg\*(Aq);
\&
\&  # download the value of the object into a file
\&  my $object = $bucket\->object( key => \*(Aqimages/my_hat.jpg\*(Aq );
\&  $object\->get_filename(\*(Aqhat_backup.jpg\*(Aq);
\&
\&  # use query string authentication for object fetch
\&  my $object = $bucket\->object(
\&    key          => \*(Aqimages/my_hat.jpg\*(Aq,
\&    expires      => \*(Aq2009\-03\-01\*(Aq,
\&  );
\&  my $uri = $object\->query_string_authentication_uri();
\&
\&        # use query string authentication for object upload
\&        my $object = $bucket\->object(
\&                key          => \*(Aqimages/my_hat.jpg\*(Aq,
\&                expires      => \*(Aq2009\-03\-01\*(Aq,
\&        );
\&        my $uri = $object\->query_string_authentication_uri_for_method(\*(AqPUT\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module represents objects in buckets.
.SH "METHODS"
.IX Header "METHODS"
.SS "range"
.IX Subsection "range"
.Vb 1
\&        my $value = $object\->range (\*(Aqbytes=1024\-10240\*(Aq)\->get;
.Ve
.PP
Provides simple interface to ranged download. See also Net::Amazon::S3::Client::Object::Range.
.SS "etag"
.IX Subsection "etag"
.Vb 3
\&  # show the etag of an existing object (if fetched by listing
\&  # a bucket)
\&  print $object\->etag . "\en";
.Ve
.SS "delete"
.IX Subsection "delete"
.Vb 2
\&  # to delete an object
\&  $object\->delete;
.Ve
.SS "exists"
.IX Subsection "exists"
.Vb 2
\&  # to see if an object exists
\&  if ($object\->exists) { ... }
.Ve
.PP
Method doesn't report error when bucket or key doesn't exist.
.SS "get"
.IX Subsection "get"
.Vb 2
\&  # to get the vaue of an object
\&  my $value = $object\->get;
.Ve
.SS "head"
.IX Subsection "head"
.Vb 2
\&  # to get the metadata of an object
\&  my %metadata = %{$object\->head};
.Ve
.PP
Unlike \f(CW\*(C`exists\*(C'\fR this method does report error.
.SS "get_decoded"
.IX Subsection "get_decoded"
.Vb 3
\&  # 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;
.Ve
.SS "get_filename"
.IX Subsection "get_filename"
.Vb 3
\&  # download the value of the object into a file
\&  my $object = $bucket\->object( key => \*(Aqimages/my_hat.jpg\*(Aq );
\&  $object\->get_filename(\*(Aqhat_backup.jpg\*(Aq);
.Ve
.SS "last_modified, last_modified_raw"
.IX Subsection "last_modified, last_modified_raw"
.Vb 6
\&  # get the last_modified data as DateTime (slow)
\&  my $dt = $obj\->last_modified;
\&  # or raw string in form \*(Aq2015\-05\-15T10:12:40.000Z\*(Aq (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;
.Ve
.SS "key"
.IX Subsection "key"
.Vb 2
\&  # show the key
\&  print $object\->key . "\en";
.Ve
.SS "available"
.IX Subsection "available"
.Vb 4
\&  # to view if an object is available for downloading
\&  # Basically, the storage class isn\*(Aqt GLACIER or the object was
\&  # fully restored
\&  $object\->available;
.Ve
.SS "restore"
.IX Subsection "restore"
.Vb 5
\&  # to restore an object on a GLACIER storage class
\&  $object\->restore(
\&    days => 1,
\&    tier => \*(AqStandard\*(Aq,
\&  );
.Ve
.SS "put"
.IX Subsection "put"
.Vb 3
\&  # to create a new object
\&  my $object = $bucket\->object( key => \*(Aqthis is the key\*(Aq );
\&  $object\->put(\*(Aqthis is the value\*(Aq);
\&
\&  # to create a new object which is publically\-accessible with a
\&  # content\-type of text/plain
\&  my $object = $bucket\->object(
\&    key          => \*(Aqthis is the public key\*(Aq,
\&    acl          => \*(Aqpublic\-read\*(Aq,
\&    content_type => \*(Aqtext/plain\*(Aq,
\&  );
\&  $object\->put(\*(Aqthis is the public value\*(Aq);
.Ve
.PP
For \f(CW\*(C`acl\*(C'\fR refer Net::Amazon::S3::ACL.
.PP
You may also set Content-Encoding using \f(CW\*(C`content_encoding\*(C'\fR, and
Content-Disposition using \f(CW\*(C`content_disposition\*(C'\fR.
.PP
You may specify the S3 storage class by setting \f(CW\*(C`storage_class\*(C'\fR to either
\&\f(CW\*(C`standard\*(C'\fR, \f(CW\*(C`reduced_redundancy\*(C'\fR, \f(CW\*(C`standard_ia\*(C'\fR, \f(CW\*(C`onezone_ia\*(C'\fR,
\&\f(CW\*(C`intelligent_tiering\*(C'\fR, \f(CW\*(C`glacier\*(C'\fR, or \f(CW\*(C`deep_archive\*(C'\fR; the default
is \f(CW\*(C`standard\*(C'\fR.
.PP
You may set website-redirect-location object metadata by setting
\&\f(CW\*(C`website_redirect_location\*(C'\fR to either another object name in the same
bucket, or to an external \s-1URL.\s0
.SS "put_filename"
.IX Subsection "put_filename"
.Vb 6
\&  # upload a file
\&  my $object = $bucket\->object(
\&    key          => \*(Aqimages/my_hat.jpg\*(Aq,
\&    content_type => \*(Aqimage/jpeg\*(Aq,
\&  );
\&  $object\->put_filename(\*(Aqhat.jpg\*(Aq);
\&
\&  # upload a file if you already know its md5_hex and size
\&  my $object = $bucket\->object(
\&    key          => \*(Aqimages/my_hat.jpg\*(Aq,
\&    content_type => \*(Aqimage/jpeg\*(Aq,
\&    etag         => $md5_hex,
\&    size         => $size,
\&  );
\&  $object\->put_filename(\*(Aqhat.jpg\*(Aq);
.Ve
.PP
You may also set Content-Encoding using \f(CW\*(C`content_encoding\*(C'\fR, and
Content-Disposition using \f(CW\*(C`content_disposition\*(C'\fR.
.PP
You may specify the S3 storage class by setting \f(CW\*(C`storage_class\*(C'\fR to either
\&\f(CW\*(C`standard\*(C'\fR, \f(CW\*(C`reduced_redundancy\*(C'\fR, \f(CW\*(C`standard_ia\*(C'\fR, \f(CW\*(C`onezone_ia\*(C'\fR,
\&\f(CW\*(C`intelligent_tiering\*(C'\fR, \f(CW\*(C`glacier\*(C'\fR, or \f(CW\*(C`deep_archive\*(C'\fR; the default
is \f(CW\*(C`standard\*(C'\fR.
.PP
You may set website-redirect-location object metadata by setting
\&\f(CW\*(C`website_redirect_location\*(C'\fR to either another object name in the same
bucket, or to an external \s-1URL.\s0
.PP
User metadata may be set by providing a non-empty hashref as
\&\f(CW\*(C`user_metadata\*(C'\fR.
.SS "query_string_authentication_uri"
.IX Subsection "query_string_authentication_uri"
.Vb 8
\&  # use query string authentication, forcing download with custom filename
\&  my $object = $bucket\->object(
\&    key          => \*(Aqimages/my_hat.jpg\*(Aq,
\&    expires      => \*(Aq2009\-03\-01\*(Aq,
\&  );
\&  my $uri = $object\->query_string_authentication_uri({
\&    \*(Aqresponse\-content\-disposition\*(Aq => \*(Aqattachment; filename=abc.doc\*(Aq,
\&  });
.Ve
.SS "query_string_authentication_uri_for_method"
.IX Subsection "query_string_authentication_uri_for_method"
.Vb 1
\&        my $uri = $object\->query_string_authentication_uri_for_method (\*(AqPUT\*(Aq);
.Ve
.PP
Similar to \*(L"query_string_authentication_uri\*(R" but creates presigned uri
for specified \s-1HTTP\s0 method (Signature V4 uses also \s-1HTTP\s0 method).
.PP
Methods providee authenticated uri only for direct object operations.
.PP
See <https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html>
.SS "size"
.IX Subsection "size"
.Vb 3
\&  # show the size of an existing object (if fetched by listing
\&  # a bucket)
\&  print $object\->size . "\en";
.Ve
.SS "uri"
.IX Subsection "uri"
.Vb 2
\&  # return the URI of a publically\-accessible object
\&  my $uri = $object\->uri;
.Ve
.SS "initiate_multipart_upload"
.IX Subsection "initiate_multipart_upload"
.Vb 6
\&        #initiate a new multipart upload for this object
\&        my $object = $bucket\->object(
\&                key         => \*(Aqmassive_video.avi\*(Aq,
\&                acl         => ...,
\&        );
\&        my $upload_id = $object\->initiate_multipart_upload;
.Ve
.PP
For description of \f(CW\*(C`acl\*(C'\fR refer \f(CW\*(C`Net::Amazon::S3::ACL\*(C'\fR.
.SS "put_part"
.IX Subsection "put_part"
.Vb 7
\&  #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(\*(AqETag\*(Aq)
\&
\&  Returns an L<HTTP::Response> object. It is necessary to keep the ETags for
\&  each part, as these are required to complete the upload.
.Ve
.SS "complete_multipart_upload"
.IX Subsection "complete_multipart_upload"
.Vb 6
\&  #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.
.Ve
.SS "user_metadata"
.IX Subsection "user_metadata"
.Vb 2
\&  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;
.Ve
.PP
To upload an object with user metadata, set \f(CW\*(C`user_metadata\*(C'\fR at construction
time to a hashref, with no \f(CW\*(C`x\-amz\-meta\-\*(C'\fR prefixes on the key names.  When
downloading an object, the \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`get_decoded\*(C'\fR and \f(CW\*(C`get_filename\*(C'\fR
ethods set the contents of \f(CW\*(C`user_metadata\*(C'\fR to the same format.
.SS "add_tags"
.IX Subsection "add_tags"
.Vb 3
\&        $object\->add_tags (
\&                tags        => { tag1 => \*(Aqval1\*(Aq, tag2 => \*(Aqval2\*(Aq },
\&        );
\&
\&        $object\->add_tags (
\&                tags        => { tag1 => \*(Aqval1\*(Aq, tag2 => \*(Aqval2\*(Aq },
\&                version_id  => $version_id,
\&        );
.Ve
.SS "delete_tags"
.IX Subsection "delete_tags"
.Vb 1
\&        $object\->delete_tags;
\&
\&        $object\->delete_tags (
\&                version_id  => $version_id,
\&        );
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Branislav Zahradník <barney@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2022 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.