1Net::Amazon::S3::BucketU(s3e)r Contributed Perl DocumentaNteito:n:Amazon::S3::Bucket(3)
2
3
4
6 Net::Amazon::S3::Bucket - convenience object for working with Amazon S3
7 buckets
8
10 version 0.98
11
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
59 This module represents an S3 bucket. You get a bucket object from the
60 Net::Amazon::S3 object.
61
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
327 Net::Amazon::S3
328
330 Branislav ZahradnĂk <barney@cpan.org>
331
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.32.1 2021-03-24 Net::Amazon::S3::Bucket(3)