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

SYNOPSIS

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

DESCRIPTION

51       This module represents an S3 bucket.  You get a bucket object from the
52       Net::Amazon::S3 object.
53

METHODS

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

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO