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.89
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 see if an object exists
32         if ($object->exists) { ... }
33
34         # to delete an object
35         $object->delete;
36
37         # 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
47         # return the URI of a publically-accessible object
48         my $uri = $object->uri;
49
50         # 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
57         # 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
64         # 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
73         # 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
77         # 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

DESCRIPTION

85       This module represents objects in buckets.
86

METHODS

88   etag
89         # show the etag of an existing object (if fetched by listing
90         # a bucket)
91         print $object->etag . "\n";
92
93   delete
94         # to delete an object
95         $object->delete;
96
97   exists
98         # to see if an object exists
99         if ($object->exists) { ... }
100
101   get
102         # to get the vaue of an object
103         my $value = $object->get;
104
105   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
110   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
115   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
123   key
124         # show the key
125         print $object->key . "\n";
126
127   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
132         # 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
141       You may also set Content-Encoding using "content_encoding", and
142       Content-Disposition using "content_disposition".
143
144       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
148       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
152   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
160         # 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
169       You may also set Content-Encoding using "content_encoding", and
170       Content-Disposition using "content_disposition".
171
172       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
176       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
180       User metadata may be set by providing a non-empty hashref as
181       "user_metadata".
182
183   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
193   size
194         # show the size of an existing object (if fetched by listing
195         # a bucket)
196         print $object->size . "\n";
197
198   uri
199         # return the URI of a publically-accessible object
200         my $uri = $object->uri;
201
202   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
209   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
218         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
221   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
229         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
232   user_metadata
233         my $object = $bucket->object(key => $key);
234         my $content = $object->get; # or use $object->get_filename($filename)
235
236         # return the user metadata downloaded, as a hashref
237         my $user_metadata = $object->user_metadata;
238
239       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

AUTHOR

246       Leo Lapworth <llap@cpan.org>
247
249       This software is copyright (c) 2020 by Amazon Digital Services, Leon
250       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
251
252       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.
254
255
256
257perl v5.30.1                      2020-02-12Net::Amazon::S3::Client::Object(3)
Impressum