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.91
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. (See synopsis);
77
78       Returns a boolean.
79
80   add_key_filename
81       Use this to upload a large file to S3. Takes three positional
82       parameters:
83
84       key
85       filename
86       configuration
87           A hash of configuration data for this key. (See synopsis);
88
89       Returns a boolean.
90
91   copy_key
92       Creates (or replaces) a key, copying its contents from another key
93       elsewhere in S3.  Takes the following parameters:
94
95       key The key to (over)write
96
97       source
98           Where to copy the key from. Should be in the form
99           "/bucketname/keyname"/.
100
101       conf
102           Optional configuration hash. If present and defined, the
103           configuration (ACL and headers) there will be used for the new key;
104           otherwise it will be copied from the source key.
105
106   edit_metadata
107       Changes the metadata associated with an existing key. Arguments:
108
109       key The key to edit
110
111       conf
112           The new configuration hash to use
113
114   head_key KEY
115       Takes the name of a key in this bucket and returns its configuration
116       hash
117
118   query_string_authentication_uri KEY, EXPIRES_AT
119       Takes key and expiration time (epoch time) and returns uri signed with
120       query parameter
121
122   get_key $key_name [$method]
123       Takes a key name and an optional HTTP method (which defaults to "GET".
124       Fetches the key from AWS.
125
126       On failure:
127
128       Returns undef on missing content, throws an exception (dies) on server
129       errors.
130
131       On success:
132
133       Returns a hashref of { content_type, etag, value, @meta } on success.
134       Other values from the server are there too, with the key being
135       lowercased.
136
137   get_key_filename $key_name $method $filename
138       Use this to download large files from S3. Takes a key name and an
139       optional HTTP method (which defaults to "GET". Fetches the key from AWS
140       and writes it to the filename. THe value returned will be empty.
141
142       On failure:
143
144       Returns undef on missing content, throws an exception (dies) on server
145       errors.
146
147       On success:
148
149       Returns a hashref of { content_type, etag, value, @meta } on success
150
151   delete_key $key_name
152       Removes $key from the bucket. Forever. It's gone after this.
153
154       Returns true on success and false on failure
155
156   delete_bucket
157       Delete the current bucket object from the server. Takes no arguments.
158
159       Fails if the bucket has anything in it.
160
161       This is an alias for "$s3->delete_bucket($bucket)"
162
163   list
164       List all keys in this bucket.
165
166       see "list_bucket" in Net::Amazon::S3 for documentation of this method.
167
168   list_all
169       List all keys in this bucket without having to worry about 'marker'.
170       This may make multiple requests to S3 under the hood.
171
172       see "list_bucket_all" in Net::Amazon::S3 for documentation of this
173       method.
174
175   get_acl
176       Takes one optional positional parameter
177
178       key (optional)
179           If no key is specified, it returns the acl for the bucket.
180
181       Returns an acl in XML format.
182
183   set_acl
184       Takes a configuration hash_ref containing:
185
186       acl_xml (cannot be used in conjunction with acl_short)
187           An XML string which contains access control information which
188           matches Amazon's published schema.  There is an example of one of
189           these XML strings in the tests for this module.
190
191       acl_short (cannot be used in conjunction with acl_xml)
192           You can use the shorthand notation instead of specifying XML for
193           certain 'canned' types of acls.
194
195           (from the Amazon API documentation)
196
197           private: Owner gets FULL_CONTROL. No one else has any access
198           rights.  This is the default.
199
200           public-read:Owner gets FULL_CONTROL and the anonymous principal is
201           granted READ access. If this policy is used on an object, it can be
202           read from a browser with no authentication.
203
204           public-read-write:Owner gets FULL_CONTROL, the anonymous principal
205           is granted READ and WRITE access. This is a useful policy to apply
206           to a bucket, if you intend for any anonymous user to PUT objects
207           into the bucket.
208
209           authenticated-read:Owner gets FULL_CONTROL, and any principal
210           authenticated as a registered Amazon S3 user is granted READ
211           access.
212
213       key (optional)
214           If the key is not set, it will apply the acl to the bucket.
215
216       Returns a boolean.
217
218   get_location_constraint
219       Retrieves the location constraint set when the bucket was created.
220       Returns a string (eg, 'EU'), or undef if no location constraint was
221       set.
222
223   err
224       The S3 error code for the last error the object ran into
225
226   errstr
227       A human readable error string for the last error the object ran into
228

AUTHOR

233       Leo Lapworth <llap@cpan.org>
234

COPYRIGHT AND LICENSE

236       This software is copyright (c) 2020 by Amazon Digital Services, Leon
237       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
238
239       This is free software; you can redistribute it and/or modify it under
240       the same terms as the Perl 5 programming language system itself.
241
242
243
244perl v5.32.0                      2020-08-20        Net::Amazon::S3::Bucket(3)