1Net::Amazon::S3::ClientU:s:eOrbjCeocntt(r3i)buted Perl DNoectu:m:eAnmtaaztoino:n:S3::Client::Object(3)
2
3
4

NAME

6       Net::Amazon::S3::Client::Object - An easy-to-use Amazon S3 client
7       object
8

VERSION

10       version 0.991
11

SYNOPSIS

13         # show the key
14         print $object->key . "\n";
15
16         # show the etag of an existing object (if fetched by listing
17         # a bucket)
18         print $object->etag . "\n";
19
20         # show the size of an existing object (if fetched by listing
21         # a bucket)
22         print $object->size . "\n";
23
24         # to create a new object
25         my $object = $bucket->object( key => 'this is the key' );
26         $object->put('this is the value');
27
28         # to get the value of an object
29         my $value = $object->get;
30
31         # to get the metadata of an object
32         my %metadata = %{$object->head};
33
34         # to see if an object exists
35         if ($object->exists) { ... }
36
37         # to delete an object
38         $object->delete;
39
40         # to create a new object which is publically-accessible with a
41         # content-type of text/plain which expires on 2010-01-02
42         my $object = $bucket->object(
43           key          => 'this is the public key',
44           acl          => Net::Amazon::S3::ACL::CANNED->PUBLIC_READ,
45           content_type => 'text/plain',
46           expires      => '2010-01-02',
47         );
48         $object->put('this is the public value');
49
50         # return the URI of a publically-accessible object
51         my $uri = $object->uri;
52
53         # to view if an object is available for downloading
54         # Basically, the storage class isn't GLACIER or the object was
55         # fully restored
56         $object->available;
57
58         # to restore an object on a GLACIER storage class
59         $object->restore(
60           days => 1,
61           tier => 'Standard',
62         );
63
64         # to store a new object with server-side encryption enabled
65         my $object = $bucket->object(
66           key        => 'my secret',
67           encryption => 'AES256',
68         );
69         $object->put('this data will be stored using encryption.');
70
71         # upload a file
72         my $object = $bucket->object(
73           key          => 'images/my_hat.jpg',
74           content_type => 'image/jpeg',
75         );
76         $object->put_filename('hat.jpg');
77
78         # upload a file if you already know its md5_hex and size
79         my $object = $bucket->object(
80           key          => 'images/my_hat.jpg',
81           content_type => 'image/jpeg',
82           etag         => $md5_hex,
83           size         => $size,
84         );
85         $object->put_filename('hat.jpg');
86
87         # download the value of the object into a file
88         my $object = $bucket->object( key => 'images/my_hat.jpg' );
89         $object->get_filename('hat_backup.jpg');
90
91         # use query string authentication for object fetch
92         my $object = $bucket->object(
93           key          => 'images/my_hat.jpg',
94           expires      => '2009-03-01',
95         );
96         my $uri = $object->query_string_authentication_uri();
97
98               # use query string authentication for object upload
99               my $object = $bucket->object(
100                       key          => 'images/my_hat.jpg',
101                       expires      => '2009-03-01',
102               );
103               my $uri = $object->query_string_authentication_uri_for_method('PUT');
104

DESCRIPTION

106       This module represents objects in buckets.
107

METHODS

109   range
110               my $value = $object->range ('bytes=1024-10240')->get;
111
112       Provides simple interface to ranged download. See also
113       Net::Amazon::S3::Client::Object::Range.
114
115   etag
116         # show the etag of an existing object (if fetched by listing
117         # a bucket)
118         print $object->etag . "\n";
119
120   delete
121         # to delete an object
122         $object->delete;
123
124   exists
125         # to see if an object exists
126         if ($object->exists) { ... }
127
128       Method doesn't report error when bucket or key doesn't exist.
129
130   get
131         # to get the vaue of an object
132         my $value = $object->get;
133
134   head
135         # to get the metadata of an object
136         my %metadata = %{$object->head};
137
138       Unlike "exists" this method does report error.
139
140   get_decoded
141         # get the value of an object, and decode any Content-Encoding and/or
142         # charset; see decoded_content in HTTP::Response
143         my $value = $object->get_decoded;
144
145   get_filename
146         # download the value of the object into a file
147         my $object = $bucket->object( key => 'images/my_hat.jpg' );
148         $object->get_filename('hat_backup.jpg');
149
150   last_modified, last_modified_raw
151         # get the last_modified data as DateTime (slow)
152         my $dt = $obj->last_modified;
153         # or raw string in form '2015-05-15T10:12:40.000Z' (fast)
154         # use this form if you are working with thousands of objects and
155         # do not actually need an expensive DateTime for each of them
156         my $raw = $obj->last_modified_raw;
157
158   key
159         # show the key
160         print $object->key . "\n";
161
162   available
163         # to view if an object is available for downloading
164         # Basically, the storage class isn't GLACIER or the object was
165         # fully restored
166         $object->available;
167
168   restore
169         # to restore an object on a GLACIER storage class
170         $object->restore(
171           days => 1,
172           tier => 'Standard',
173         );
174
175   put
176         # to create a new object
177         my $object = $bucket->object( key => 'this is the key' );
178         $object->put('this is the value');
179
180         # to create a new object which is publically-accessible with a
181         # content-type of text/plain
182         my $object = $bucket->object(
183           key          => 'this is the public key',
184           acl          => 'public-read',
185           content_type => 'text/plain',
186         );
187         $object->put('this is the public value');
188
189       For "acl" refer Net::Amazon::S3::ACL.
190
191       You may also set Content-Encoding using "content_encoding", and
192       Content-Disposition using "content_disposition".
193
194       You may specify the S3 storage class by setting "storage_class" to
195       either "standard", "reduced_redundancy", "standard_ia", "onezone_ia",
196       "intelligent_tiering", "glacier", or "deep_archive"; the default is
197       "standard".
198
199       You may set website-redirect-location object metadata by setting
200       "website_redirect_location" to either another object name in the same
201       bucket, or to an external URL.
202
203   put_filename
204         # upload a file
205         my $object = $bucket->object(
206           key          => 'images/my_hat.jpg',
207           content_type => 'image/jpeg',
208         );
209         $object->put_filename('hat.jpg');
210
211         # upload a file if you already know its md5_hex and size
212         my $object = $bucket->object(
213           key          => 'images/my_hat.jpg',
214           content_type => 'image/jpeg',
215           etag         => $md5_hex,
216           size         => $size,
217         );
218         $object->put_filename('hat.jpg');
219
220       You may also set Content-Encoding using "content_encoding", and
221       Content-Disposition using "content_disposition".
222
223       You may specify the S3 storage class by setting "storage_class" to
224       either "standard", "reduced_redundancy", "standard_ia", "onezone_ia",
225       "intelligent_tiering", "glacier", or "deep_archive"; the default is
226       "standard".
227
228       You may set website-redirect-location object metadata by setting
229       "website_redirect_location" to either another object name in the same
230       bucket, or to an external URL.
231
232       User metadata may be set by providing a non-empty hashref as
233       "user_metadata".
234
235   query_string_authentication_uri
236         # use query string authentication, forcing download with custom filename
237         my $object = $bucket->object(
238           key          => 'images/my_hat.jpg',
239           expires      => '2009-03-01',
240         );
241         my $uri = $object->query_string_authentication_uri({
242           'response-content-disposition' => 'attachment; filename=abc.doc',
243         });
244
245   query_string_authentication_uri_for_method
246               my $uri = $object->query_string_authentication_uri_for_method ('PUT');
247
248       Similar to "query_string_authentication_uri" but creates presigned uri
249       for specified HTTP method (Signature V4 uses also HTTP method).
250
251       Methods providee authenticated uri only for direct object operations.
252
253       See
254       <https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html>
255
256   size
257         # show the size of an existing object (if fetched by listing
258         # a bucket)
259         print $object->size . "\n";
260
261   uri
262         # return the URI of a publically-accessible object
263         my $uri = $object->uri;
264
265   initiate_multipart_upload
266               #initiate a new multipart upload for this object
267               my $object = $bucket->object(
268                       key         => 'massive_video.avi',
269                       acl         => ...,
270               );
271               my $upload_id = $object->initiate_multipart_upload;
272
273       For description of "acl" refer "Net::Amazon::S3::ACL".
274
275   put_part
276         #add a part to a multipart upload
277         my $put_part_response = $object->put_part(
278            upload_id      => $upload_id,
279            part_number    => 1,
280            value          => $chunk_content,
281         );
282         my $part_etag = $put_part_response->header('ETag')
283
284         Returns an L<HTTP::Response> object. It is necessary to keep the ETags for
285         each part, as these are required to complete the upload.
286
287   complete_multipart_upload
288         #complete a multipart upload
289         $object->complete_multipart_upload(
290           upload_id       => $upload_id,
291           etags           => [$etag_1, $etag_2],
292           part_numbers    => [$part_number_1, $part_number2],
293         );
294
295         The etag and part_numbers parameters are ordered lists specifying the part
296         numbers and ETags for each individual part of the multipart upload.
297
298   user_metadata
299         my $object = $bucket->object(key => $key);
300         my $content = $object->get; # or use $object->get_filename($filename)
301
302         # return the user metadata downloaded, as a hashref
303         my $user_metadata = $object->user_metadata;
304
305       To upload an object with user metadata, set "user_metadata" at
306       construction time to a hashref, with no "x-amz-meta-" prefixes on the
307       key names.  When downloading an object, the "get", "get_decoded" and
308       "get_filename" ethods set the contents of "user_metadata" to the same
309       format.
310
311   add_tags
312               $object->add_tags (
313                       tags        => { tag1 => 'val1', tag2 => 'val2' },
314               );
315
316               $object->add_tags (
317                       tags        => { tag1 => 'val1', tag2 => 'val2' },
318                       version_id  => $version_id,
319               );
320
321   delete_tags
322               $object->delete_tags;
323
324               $object->delete_tags (
325                       version_id  => $version_id,
326               );
327

AUTHOR

329       Branislav ZahradnĂ­k <barney@cpan.org>
330
332       This software is copyright (c) 2022 by Amazon Digital Services, Leon
333       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav
334       ZahradnĂ­k.
335
336       This is free software; you can redistribute it and/or modify it under
337       the same terms as the Perl 5 programming language system itself.
338
339
340
341perl v5.36.0                      2023-03-22Net::Amazon::S3::Client::Object(3)
Impressum