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.98
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         # returns undef on missing or on error (check $bucket->err)
41         is(undef, $bucket->get_key("non-existing-key"));
42         die $bucket->errstr if $bucket->err;
43
44         # fetch a key's metadata
45         $val = $bucket->head_key("key");
46         is( $val->{value},               '' );
47         is( $val->{content_type},        'text/html' );
48         is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
49         is( $val->{'x-amz-meta-colour'}, 'orange' );
50
51         # delete a key
52         ok($bucket->delete_key($key_name));
53         ok(! $bucket->delete_key("non-exist-key"));
54
55         # delete the entire bucket (Amazon requires it first be empty)
56         $bucket->delete_bucket;
57

DESCRIPTION

59       This module represents an S3 bucket.  You get a bucket object from the
60       Net::Amazon::S3 object.
61

METHODS

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

AUTHOR

330       Branislav Zahradník <barney@cpan.org>
331

COPYRIGHT AND LICENSE

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