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.87
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 see if an object exists
32 if ($object->exists) { ... }
33 # to delete an object
35 $object->delete;
36 # to create a new object which is publically-accessible with a
38 # content-type of text/plain which expires on 2010-01-02
39 my $object = $bucket->object(
40 key => 'this is the public key',
41 acl_short => 'public-read',
42 content_type => 'text/plain',
43 expires => '2010-01-02',
44 );
45 $object->put('this is the public value');
46 # return the URI of a publically-accessible object
48 my $uri = $object->uri;
49 # to store a new object with server-side encryption enabled
51 my $object = $bucket->object(
52 key => 'my secret',
53 encryption => 'AES256',
54 );
55 $object->put('this data will be stored using encryption.');
56 # upload a file
58 my $object = $bucket->object(
59 key => 'images/my_hat.jpg',
60 content_type => 'image/jpeg',
61 );
62 $object->put_filename('hat.jpg');
63 # upload a file if you already know its md5_hex and size
65 my $object = $bucket->object(
66 key => 'images/my_hat.jpg',
67 content_type => 'image/jpeg',
68 etag => $md5_hex,
69 size => $size,
70 );
71 $object->put_filename('hat.jpg');
72 # download the value of the object into a file
74 my $object = $bucket->object( key => 'images/my_hat.jpg' );
75 $object->get_filename('hat_backup.jpg');
76 # use query string authentication
78 my $object = $bucket->object(
79 key => 'images/my_hat.jpg',
80 expires => '2009-03-01',
81 );
82 my $uri = $object->query_string_authentication_uri();
83
85 This module represents objects in buckets.
86
88 etag
89 # show the etag of an existing object (if fetched by listing
90 # a bucket)
91 print $object->etag . "\n";
92 delete
94 # to delete an object
95 $object->delete;
96 exists
98 # to see if an object exists
99 if ($object->exists) { ... }
100 get
102 # to get the vaue of an object
103 my $value = $object->get;
104 get_decoded
106 # get the value of an object, and decode any Content-Encoding and/or
107 # charset; see decoded_content in HTTP::Response
108 my $value = $object->get_decoded;
109 get_filename
111 # download the value of the object into a file
112 my $object = $bucket->object( key => 'images/my_hat.jpg' );
113 $object->get_filename('hat_backup.jpg');
114 last_modified, last_modified_raw
116 # get the last_modified data as DateTime (slow)
117 my $dt = $obj->last_modified;
118 # or raw string in form '2015-05-15T10:12:40.000Z' (fast)
119 # use this form if you are working with thousands of objects and
120 # do not actually need an expensive DateTime for each of them
121 my $raw = $obj->last_modified_raw;
122 key
124 # show the key
125 print $object->key . "\n";
126 put
128 # to create a new object
129 my $object = $bucket->object( key => 'this is the key' );
130 $object->put('this is the value');
131 # to create a new object which is publically-accessible with a
133 # content-type of text/plain
134 my $object = $bucket->object(
135 key => 'this is the public key',
136 acl_short => 'public-read',
137 content_type => 'text/plain',
138 );
139 $object->put('this is the public value');
140 You may also set Content-Encoding using "content_encoding", and
142 Content-Disposition using "content_disposition".
143 You may specify the S3 storage class by setting "storage_class" to
145 either "standard", "reduced_redundancy", "standard_ia", or
146 "onezone_ia"; the default is "standard".
147 You may set website-redirect-location object metadata by setting
149 "website_redirect_location" to either another object name in the same
150 bucket, or to an external URL.
151 put_filename
153 # upload a file
154 my $object = $bucket->object(
155 key => 'images/my_hat.jpg',
156 content_type => 'image/jpeg',
157 );
158 $object->put_filename('hat.jpg');
159 # upload a file if you already know its md5_hex and size
161 my $object = $bucket->object(
162 key => 'images/my_hat.jpg',
163 content_type => 'image/jpeg',
164 etag => $md5_hex,
165 size => $size,
166 );
167 $object->put_filename('hat.jpg');
168 You may also set Content-Encoding using "content_encoding", and
170 Content-Disposition using "content_disposition".
171 You may specify the S3 storage class by setting "storage_class" to
173 either "standard", "reduced_redundancy", "standard_ia", or
174 "onezone_ia"; the default is "standard".
175 You may set website-redirect-location object metadata by setting
177 "website_redirect_location" to either another object name in the same
178 bucket, or to an external URL.
179 User metadata may be set by providing a non-empty hashref as
181 "user_metadata".
182 query_string_authentication_uri
184 # use query string authentication, forcing download with custom filename
185 my $object = $bucket->object(
186 key => 'images/my_hat.jpg',
187 expires => '2009-03-01',
188 );
189 my $uri = $object->query_string_authentication_uri({
190 'response-content-disposition' => 'attachment; filename=abc.doc',
191 });
192 size
194 # show the size of an existing object (if fetched by listing
195 # a bucket)
196 print $object->size . "\n";
197 uri
199 # return the URI of a publically-accessible object
200 my $uri = $object->uri;
201 initiate_multipart_upload
203 #initiate a new multipart upload for this object
204 my $object = $bucket->object(
205 key => 'massive_video.avi'
206 );
207 my $upload_id = $object->initiate_multipart_upload;
208 put_part
210 #add a part to a multipart upload
211 my $put_part_response = $object->put_part(
212 upload_id => $upload_id,
213 part_number => 1,
214 value => $chunk_content,
215 );
216 my $part_etag = $put_part_response->header('ETag')
217 Returns an L<HTTP::Response> object. It is necessary to keep the ETags for
219 each part, as these are required to complete the upload.
220 complete_multipart_upload
222 #complete a multipart upload
223 $object->complete_multipart_upload(
224 upload_id => $upload_id,
225 etags => [$etag_1, $etag_2],
226 part_numbers => [$part_number_1, $part_number2],
227 );
228 The etag and part_numbers parameters are ordered lists specifying the part
230 numbers and ETags for each individual part of the multipart upload.
231 user_metadata
233 my $object = $bucket->object(key => $key);
234 my $content = $object->get; # or use $object->get_filename($filename)
235 # return the user metadata downloaded, as a hashref
237 my $user_metadata = $object->user_metadata;
238 To upload an object with user metadata, set "user_metadata" at
240 construction time to a hashref, with no "x-amz-meta-" prefixes on the
241 key names. When downloading an object, the "get", "get_decoded" and
242 "get_filename" ethods set the contents of "user_metadata" to the same
243 format.
244
246 Leo Lapworth <llap@cpan.org>
247
249 This software is copyright (c) 2019 by Amazon Digital Services, Leon
250 Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
251 This is free software; you can redistribute it and/or modify it under
253 the same terms as the Perl 5 programming language system itself.
254perl v5.30.1 2019-12-10Net::Amazon::S3::Client::Object(3)