Net::Amazon::S3::Bucket(3pm)

1Net::Amazon::S3::BucketU(s3e)r Contributed Perl DocumentaNteito:n:Amazon::S3::Bucket(3)
2
3
4

NAME

6       Net::Amazon::S3::Bucket - convenience object for working with Amazon S3
7       buckets
8

VERSION

10       version 0.99
11

SYNOPSIS

13         use Net::Amazon::S3;
14
15         my $bucket = $s3->bucket("foo");
16
17         ok($bucket->add_key("key", "data"));
18         ok($bucket->add_key("key", "data", {
19            content_type => "text/html",
20           'x-amz-meta-colour' => 'orange',
21         }));
22
23         # Enable server-side encryption
24         ok($bucket->add_key("key", "data", {
25            encryption => 'AES256',
26         }));
27
28         # the err and errstr methods just proxy up to the Net::Amazon::S3's
29         # objects err/errstr methods.
30         $bucket->add_key("bar", "baz") or
31             die $bucket->err . $bucket->errstr;
32
33         # fetch a key
34         $val = $bucket->get_key("key");
35         is( $val->{value},               'data' );
36         is( $val->{content_type},        'text/html' );
37         is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
38         is( $val->{'x-amz-meta-colour'}, 'orange' );
39
40         # fetch a part of the key
41         $val = $bucket->get_key("key", { range => "bytes=1024-10240" });
42
43         # returns undef on missing or on error (check $bucket->err)
44         is(undef, $bucket->get_key("non-existing-key"));
45         die $bucket->errstr if $bucket->err;
46
47         # fetch a key's metadata
48         $val = $bucket->head_key("key");
49         is( $val->{value},               '' );
50         is( $val->{content_type},        'text/html' );
51         is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
52         is( $val->{'x-amz-meta-colour'}, 'orange' );
53
54         # delete a key
55         ok($bucket->delete_key($key_name));
56         ok(! $bucket->delete_key("non-exist-key"));
57
58         # delete the entire bucket (Amazon requires it first be empty)
59         $bucket->delete_bucket;
60

DESCRIPTION

62       This module represents an S3 bucket.  You get a bucket object from the
63       Net::Amazon::S3 object.
64

METHODS

66   new
67       Create a new bucket object. Expects a hash containing these two
68       arguments:
69
70       bucket
71       account
72
73   add_key
74       Takes three positional parameters:
75
76       key
77       value
78       configuration
79           A hash of configuration data for this key.
80
81           acl
82           encryption
83           any additional HTTP header
84
85           See Net::Amazon::S3::Operation::Object::Add::Request for details
86
87       Returns a boolean.
88
89   add_key_filename
90       Use this to upload a large file to S3. Takes three positional
91       parameters:
92
93       key
94       filename
95       configuration
96           A hash of configuration data for this key. (See synopsis);
97
98       Returns a boolean.
99
100   copy_key
101       Creates (or replaces) a key, copying its contents from another key
102       elsewhere in S3.  Takes the following parameters:
103
104       key The key to (over)write
105
106       source
107           Where to copy the key from. Should be in the form
108           "/bucketname/keyname"/.
109
110       conf
111           Optional configuration hash. If present and defined, the
112           configuration (ACL and headers) there will be used for the new key;
113           otherwise it will be copied from the source key.
114
115   edit_metadata
116       Changes the metadata associated with an existing key. Arguments:
117
118       key The key to edit
119
120       conf
121           The new configuration hash to use
122
123   head_key KEY
124       Takes the name of a key in this bucket and returns its configuration
125       hash
126
127   query_string_authentication_uri KEY, EXPIRES_AT
128               my $uri = $bucket->query_string_authentication_uri (
129                       key => 'foo',
130                       expires_at => time + 3_600, # valid for one hour
131               );
132
133               my $uri = $bucket->query_string_authentication_uri (
134                       key => 'foo',
135                       expires_at => time + 3_600,
136                       method => 'PUT',
137               );
138
139       Returns uri presigned with your credentials.
140
141       When used with Signature V4 you have to specify also HTTP method this
142       presigned uri will be used for (default: "GET")
143
144       Method provides authenticated uri only for direct object operations.
145
146       Method follows API's "CALLING CONVENTION".
147
148       Recognized positional arguments (mandatory).
149
150       key
151       expires_at
152           Expiration time (epoch time).
153
154       Optional arguments
155
156       method
157           Default: "GET"
158
159           Intended HTTP method this uri will be presigned for.
160
161           Signature V2 doesn't use it but Signature V4 does.
162
163           See
164           <https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html>
165
166   get_key $key_name [$method]
167       Takes a key name and an optional HTTP method (which defaults to "GET".
168       Fetches the key from AWS.
169
170       On failure:
171
172       Returns undef on missing content, throws an exception (dies) on server
173       errors.
174
175       On success:
176
177       Returns a hashref of { content_type, etag, value, @meta } on success.
178       Other values from the server are there too, with the key being
179       lowercased.
180
181   get_key_filename $key_name $method $filename
182       Use this to download large files from S3. Takes a key name and an
183       optional HTTP method (which defaults to "GET". Fetches the key from AWS
184       and writes it to the filename. THe value returned will be empty.
185
186       On failure:
187
188       Returns undef on missing content, throws an exception (dies) on server
189       errors.
190
191       On success:
192
193       Returns a hashref of { content_type, etag, value, @meta } on success
194
195   delete_key $key_name
196       Removes $key from the bucket. Forever. It's gone after this.
197
198       Returns true on success and false on failure
199
200   delete_bucket
201       Delete the current bucket object from the server. Takes no arguments.
202
203       Fails if the bucket has anything in it.
204
205       This is an alias for "$s3->delete_bucket($bucket)"
206
207   list
208       List all keys in this bucket.
209
210       see "list_bucket" in Net::Amazon::S3 for documentation of this method.
211
212   list_all
213       List all keys in this bucket without having to worry about 'marker'.
214       This may make multiple requests to S3 under the hood.
215
216       see "list_bucket_all" in Net::Amazon::S3 for documentation of this
217       method.
218
219   get_acl
220       Takes one optional positional parameter
221
222       key (optional)
223           If no key is specified, it returns the acl for the bucket.
224
225       Returns an acl in XML format.
226
227   set_acl
228       Takes a configuration hash_ref containing:
229
230       acl_xml (cannot be used in conjunction with acl_short)
231           An XML string which contains access control information which
232           matches Amazon's published schema.  There is an example of one of
233           these XML strings in the tests for this module.
234
235       acl_short (cannot be used in conjunction with acl_xml)
236           You can use the shorthand notation instead of specifying XML for
237           certain 'canned' types of acls.
238
239           (from the Amazon API documentation)
240
241           private: Owner gets FULL_CONTROL. No one else has any access
242           rights.  This is the default.
243
244           public-read:Owner gets FULL_CONTROL and the anonymous principal is
245           granted READ access. If this policy is used on an object, it can be
246           read from a browser with no authentication.
247
248           public-read-write:Owner gets FULL_CONTROL, the anonymous principal
249           is granted READ and WRITE access. This is a useful policy to apply
250           to a bucket, if you intend for any anonymous user to PUT objects
251           into the bucket.
252
253           authenticated-read:Owner gets FULL_CONTROL, and any principal
254           authenticated as a registered Amazon S3 user is granted READ
255           access.
256
257       key (optional)
258           If the key is not set, it will apply the acl to the bucket.
259
260       Returns a boolean.
261
262   get_location_constraint
263       Retrieves the location constraint set when the bucket was created.
264       Returns a string (eg, 'EU'), or undef if no location constraint was
265       set.
266
267   err
268       The S3 error code for the last error the object ran into
269
270   errstr
271       A human readable error string for the last error the object ran into
272
273   add_tags
274               # Add tags for a bucket
275               $s3->add_tags ({
276                       bucket => 'bucket-name',
277                       tags   => { tag1 => 'value-1', tag2 => 'value-2' },
278               });
279
280               # Add tags for an object
281               $s3->add_tags ({
282                       bucket => 'bucket-name',
283                       key    => 'key',
284                       tags   => { tag1 => 'value-1', tag2 => 'value-2' },
285               });
286
287       Takes configuration parameters
288
289       key (optional, scalar)
290           If key is specified, add tag(s) to object, otherwise on bucket.
291
292       tags (mandatory, hashref)
293           Set specified tags and their respective values.
294
295       version_id (optional)
296           Is specified (in conjunction with "key") add tag(s) to versioned
297           object.
298
299       Returns "true" on success.
300
301       Returns "false" and sets "err"/"errstr" otherwise.
302
303   delete_tags
304               # Add tags for a bucket
305               $s3->delete_tags ({
306                       bucket => 'bucket-name',
307               });
308
309               # Add tags for an object
310               $s3->delete_tags ({
311                       bucket     => 'bucket-name',
312                       key        => 'key',
313                       version_id => $version_id,
314               });
315
316       Takes configuration parameters
317
318       key (optional, scalar)
319           If key is specified, add tag(s) to object, otherwise on bucket.
320
321       version_id (optional)
322           Is specified (in conjunction with "key") add tag(s) to versioned
323           object.
324
325       Returns "true" on success.
326
327       Returns "false" and sets "err"/"errstr" otherwise.
328

AUTHOR

333       Branislav Zahradník <barney@cpan.org>
334

COPYRIGHT AND LICENSE

336       This software is copyright (c) 2021 by Amazon Digital Services, Leon
337       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav
338       Zahradník.
339
340       This is free software; you can redistribute it and/or modify it under
341       the same terms as the Perl 5 programming language system itself.
342
343
344
345perl v5.34.0                      2022-01-21        Net::Amazon::S3::Bucket(3)