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

AUTHOR

319       Branislav ZahradnĂ­k <barney@cpan.org>
320
322       This software is copyright (c) 2021 by Amazon Digital Services, Leon
323       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav
324       ZahradnĂ­k.
325
326       This is free software; you can redistribute it and/or modify it under
327       the same terms as the Perl 5 programming language system itself.
328
329
330
331perl v5.34.0                      2021-07-22Net::Amazon::S3::Client::Object(3)
Impressum