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.84
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         # the err and errstr methods just proxy up to the Net::Amazon::S3's
24         # objects err/errstr methods.
25         $bucket->add_key("bar", "baz") or
26             die $bucket->err . $bucket->errstr;
27
28         # fetch a key
29         $val = $bucket->get_key("key");
30         is( $val->{value},               'data' );
31         is( $val->{content_type},        'text/html' );
32         is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
33         is( $val->{'x-amz-meta-colour'}, 'orange' );
34
35         # returns undef on missing or on error (check $bucket->err)
36         is(undef, $bucket->get_key("non-existing-key"));
37         die $bucket->errstr if $bucket->err;
38
39         # fetch a key's metadata
40         $val = $bucket->head_key("key");
41         is( $val->{value},               '' );
42         is( $val->{content_type},        'text/html' );
43         is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
44         is( $val->{'x-amz-meta-colour'}, 'orange' );
45
46         # delete a key
47         ok($bucket->delete_key($key_name));
48         ok(! $bucket->delete_key("non-exist-key"));
49
50         # delete the entire bucket (Amazon requires it first be empty)
51         $bucket->delete_bucket;
52

DESCRIPTION

54       This module represents an S3 bucket.  You get a bucket object from the
55       Net::Amazon::S3 object.
56

METHODS

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

AUTHOR

228       Leo Lapworth <llap@cpan.org>
229

COPYRIGHT AND LICENSE

231       This software is copyright (c) 2018 by Amazon Digital Services, Leon
232       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
233
234       This is free software; you can redistribute it and/or modify it under
235       the same terms as the Perl 5 programming language system itself.
236
237
238
239perl v5.28.0                      2018-07-16        Net::Amazon::S3::Bucket(3)