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.98
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 vaue 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 etag
110 # show the etag of an existing object (if fetched by listing
111 # a bucket)
112 print $object->etag . "\n";
113 delete
115 # to delete an object
116 $object->delete;
117 exists
119 # to see if an object exists
120 if ($object->exists) { ... }
121 get
123 # to get the vaue of an object
124 my $value = $object->get;
125 head
127 # to get the metadata of an object
128 my %metadata = %{$object->head};
129 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 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 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 key
149 # show the key
150 print $object->key . "\n";
151 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 restore
159 # to restore an object on a GLACIER storage class
160 $object->restore(
161 days => 1,
162 tier => 'Standard',
163 );
164 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 # 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 For "acl" refer Net::Amazon::S3::ACL.
180 You may also set Content-Encoding using "content_encoding", and
182 Content-Disposition using "content_disposition".
183 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 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 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 # 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 You may also set Content-Encoding using "content_encoding", and
211 Content-Disposition using "content_disposition".
212 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 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 User metadata may be set by providing a non-empty hashref as
223 "user_metadata".
224 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 query_string_authentication_uri_for_method
236 my $uri = $object->query_string_authentication_uri_for_method ('PUT');
237 Similar to "query_string_authentication_uri" but creates presigned uri
239 for specified HTTP method (Signature V4 uses also HTTP method).
240 Methods providee authenticated uri only for direct object operations.
242 See
244 <https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html>
245 size
247 # show the size of an existing object (if fetched by listing
248 # a bucket)
249 print $object->size . "\n";
250 uri
252 # return the URI of a publically-accessible object
253 my $uri = $object->uri;
254 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 For description of "acl" refer "Net::Amazon::S3::ACL".
264 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 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 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 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 user_metadata
289 my $object = $bucket->object(key => $key);
290 my $content = $object->get; # or use $object->get_filename($filename)
291 # return the user metadata downloaded, as a hashref
293 my $user_metadata = $object->user_metadata;
294 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 add_tags
302 $object->add_tags (
303 tags => { tag1 => 'val1', tag2 => 'val2' },
304 );
305 $object->add_tags (
307 tags => { tag1 => 'val1', tag2 => 'val2' },
308 version_id => $version_id,
309 );
310 delete_tags
312 $object->delete_tags;
313 $object->delete_tags (
315 version_id => $version_id,
316 );
317
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 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.
328perl v5.34.0 2021-07-22Net::Amazon::S3::Client::Object(3)