1Net::Amazon::S3::ClientU:s:eOrbjCeocntt(r3i)buted Perl DNoectu:m:eAnmtaaztoino:n:S3::Client::Object(3)
2
6 Net::Amazon::S3::Client::Object - An easy-to-use Amazon S3 client
7 object
8
10 version 0.99
11
13 # show the key
14 print $object->key . "\n";
15 # show the etag of an existing object (if fetched by listing
17 # a bucket)
18 print $object->etag . "\n";
19 # show the size of an existing object (if fetched by listing
21 # a bucket)
22 print $object->size . "\n";
23 # to create a new object
25 my $object = $bucket->object( key => 'this is the key' );
26 $object->put('this is the value');
27 # to get the value of an object
29 my $value = $object->get;
30 # to get the metadata of an object
32 my %metadata = %{$object->head};
33 # to see if an object exists
35 if ($object->exists) { ... }
36 # to delete an object
38 $object->delete;
39 # 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 # return the URI of a publically-accessible object
51 my $uri = $object->uri;
52 # 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 # to restore an object on a GLACIER storage class
59 $object->restore(
60 days => 1,
61 tier => 'Standard',
62 );
63 # 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 # 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 # 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 # 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 # 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 # 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
106 This module represents objects in buckets.
107
109 range
110 my $value = $object->range ('bytes=1024-10240')->get;
111 Provides simple interface to ranged download. See also
113 Net::Amazon::S3::Client::Object::Range.
114 etag
116 # show the etag of an existing object (if fetched by listing
117 # a bucket)
118 print $object->etag . "\n";
119 delete
121 # to delete an object
122 $object->delete;
123 exists
125 # to see if an object exists
126 if ($object->exists) { ... }
127 Method doesn't report error when bucket or key doesn't exist.
129 get
131 # to get the vaue of an object
132 my $value = $object->get;
133 head
135 # to get the metadata of an object
136 my %metadata = %{$object->head};
137 Unlike "exists" this method does report error.
139 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 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 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 key
159 # show the key
160 print $object->key . "\n";
161 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 restore
169 # to restore an object on a GLACIER storage class
170 $object->restore(
171 days => 1,
172 tier => 'Standard',
173 );
174 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 # 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 For "acl" refer Net::Amazon::S3::ACL.
190 You may also set Content-Encoding using "content_encoding", and
192 Content-Disposition using "content_disposition".
193 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 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 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 # 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 You may also set Content-Encoding using "content_encoding", and
221 Content-Disposition using "content_disposition".
222 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 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 User metadata may be set by providing a non-empty hashref as
233 "user_metadata".
234 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 query_string_authentication_uri_for_method
246 my $uri = $object->query_string_authentication_uri_for_method ('PUT');
247 Similar to "query_string_authentication_uri" but creates presigned uri
249 for specified HTTP method (Signature V4 uses also HTTP method).
250 Methods providee authenticated uri only for direct object operations.
252 See
254 <https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html>
255 size
257 # show the size of an existing object (if fetched by listing
258 # a bucket)
259 print $object->size . "\n";
260 uri
262 # return the URI of a publically-accessible object
263 my $uri = $object->uri;
264 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 For description of "acl" refer "Net::Amazon::S3::ACL".
274 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 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 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 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 user_metadata
299 my $object = $bucket->object(key => $key);
300 my $content = $object->get; # or use $object->get_filename($filename)
301 # return the user metadata downloaded, as a hashref
303 my $user_metadata = $object->user_metadata;
304 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 add_tags
312 $object->add_tags (
313 tags => { tag1 => 'val1', tag2 => 'val2' },
314 );
315 $object->add_tags (
317 tags => { tag1 => 'val1', tag2 => 'val2' },
318 version_id => $version_id,
319 );
320 delete_tags
322 $object->delete_tags;
323 $object->delete_tags (
325 version_id => $version_id,
326 );
327
329 Branislav Zahradník <barney@cpan.org>
330
332 This software is copyright (c) 2021 by Amazon Digital Services, Leon
333 Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav
334 Zahradník.
335 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.
338perl v5.34.0 2022-01-21Net::Amazon::S3::Client::Object(3)