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.91
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_short => '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
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
99 This module represents objects in buckets.
100
102 etag
103 # show the etag of an existing object (if fetched by listing
104 # a bucket)
105 print $object->etag . "\n";
106 delete
108 # to delete an object
109 $object->delete;
110 exists
112 # to see if an object exists
113 if ($object->exists) { ... }
114 get
116 # to get the vaue of an object
117 my $value = $object->get;
118 head
120 # to get the metadata of an object
121 my %metadata = %{$object->head};
122 get_decoded
124 # get the value of an object, and decode any Content-Encoding and/or
125 # charset; see decoded_content in HTTP::Response
126 my $value = $object->get_decoded;
127 get_filename
129 # download the value of the object into a file
130 my $object = $bucket->object( key => 'images/my_hat.jpg' );
131 $object->get_filename('hat_backup.jpg');
132 last_modified, last_modified_raw
134 # get the last_modified data as DateTime (slow)
135 my $dt = $obj->last_modified;
136 # or raw string in form '2015-05-15T10:12:40.000Z' (fast)
137 # use this form if you are working with thousands of objects and
138 # do not actually need an expensive DateTime for each of them
139 my $raw = $obj->last_modified_raw;
140 key
142 # show the key
143 print $object->key . "\n";
144 available
146 # to view if an object is available for downloading
147 # Basically, the storage class isn't GLACIER or the object was
148 # fully restored
149 $object->available;
150 restore
152 # to restore an object on a GLACIER storage class
153 $object->restore(
154 days => 1,
155 tier => 'Standard',
156 );
157 put
159 # to create a new object
160 my $object = $bucket->object( key => 'this is the key' );
161 $object->put('this is the value');
162 # to create a new object which is publically-accessible with a
164 # content-type of text/plain
165 my $object = $bucket->object(
166 key => 'this is the public key',
167 acl_short => 'public-read',
168 content_type => 'text/plain',
169 );
170 $object->put('this is the public value');
171 You may also set Content-Encoding using "content_encoding", and
173 Content-Disposition using "content_disposition".
174 You may specify the S3 storage class by setting "storage_class" to
176 either "standard", "reduced_redundancy", "standard_ia", "onezone_ia",
177 "intelligent_tiering", "glacier", or "deep_archive"; the default is
178 "standard".
179 You may set website-redirect-location object metadata by setting
181 "website_redirect_location" to either another object name in the same
182 bucket, or to an external URL.
183 put_filename
185 # upload a file
186 my $object = $bucket->object(
187 key => 'images/my_hat.jpg',
188 content_type => 'image/jpeg',
189 );
190 $object->put_filename('hat.jpg');
191 # upload a file if you already know its md5_hex and size
193 my $object = $bucket->object(
194 key => 'images/my_hat.jpg',
195 content_type => 'image/jpeg',
196 etag => $md5_hex,
197 size => $size,
198 );
199 $object->put_filename('hat.jpg');
200 You may also set Content-Encoding using "content_encoding", and
202 Content-Disposition using "content_disposition".
203 You may specify the S3 storage class by setting "storage_class" to
205 either "standard", "reduced_redundancy", "standard_ia", "onezone_ia",
206 "intelligent_tiering", "glacier", or "deep_archive"; the default is
207 "standard".
208 You may set website-redirect-location object metadata by setting
210 "website_redirect_location" to either another object name in the same
211 bucket, or to an external URL.
212 User metadata may be set by providing a non-empty hashref as
214 "user_metadata".
215 query_string_authentication_uri
217 # use query string authentication, forcing download with custom filename
218 my $object = $bucket->object(
219 key => 'images/my_hat.jpg',
220 expires => '2009-03-01',
221 );
222 my $uri = $object->query_string_authentication_uri({
223 'response-content-disposition' => 'attachment; filename=abc.doc',
224 });
225 size
227 # show the size of an existing object (if fetched by listing
228 # a bucket)
229 print $object->size . "\n";
230 uri
232 # return the URI of a publically-accessible object
233 my $uri = $object->uri;
234 initiate_multipart_upload
236 #initiate a new multipart upload for this object
237 my $object = $bucket->object(
238 key => 'massive_video.avi'
239 );
240 my $upload_id = $object->initiate_multipart_upload;
241 put_part
243 #add a part to a multipart upload
244 my $put_part_response = $object->put_part(
245 upload_id => $upload_id,
246 part_number => 1,
247 value => $chunk_content,
248 );
249 my $part_etag = $put_part_response->header('ETag')
250 Returns an L<HTTP::Response> object. It is necessary to keep the ETags for
252 each part, as these are required to complete the upload.
253 complete_multipart_upload
255 #complete a multipart upload
256 $object->complete_multipart_upload(
257 upload_id => $upload_id,
258 etags => [$etag_1, $etag_2],
259 part_numbers => [$part_number_1, $part_number2],
260 );
261 The etag and part_numbers parameters are ordered lists specifying the part
263 numbers and ETags for each individual part of the multipart upload.
264 user_metadata
266 my $object = $bucket->object(key => $key);
267 my $content = $object->get; # or use $object->get_filename($filename)
268 # return the user metadata downloaded, as a hashref
270 my $user_metadata = $object->user_metadata;
271 To upload an object with user metadata, set "user_metadata" at
273 construction time to a hashref, with no "x-amz-meta-" prefixes on the
274 key names. When downloading an object, the "get", "get_decoded" and
275 "get_filename" ethods set the contents of "user_metadata" to the same
276 format.
277
279 Leo Lapworth <llap@cpan.org>
280
282 This software is copyright (c) 2020 by Amazon Digital Services, Leon
283 Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
284 This is free software; you can redistribute it and/or modify it under
286 the same terms as the Perl 5 programming language system itself.
287perl v5.32.0 2020-08-20Net::Amazon::S3::Client::Object(3)