NAME
Net::Amazon::S3::Bucket - convenience object for working with Amazon S3 buckets
SYNOPSIS
use
Net::Amazon::S3;
my
$bucket
=
$s3
->bucket(
"foo"
);
ok(
$bucket
->add_key(
"key"
,
"data"
));
ok(
$bucket
->add_key(
"key"
,
"data"
, {
content_type
=>
"text/html"
,
'x-amz-meta-colour'
=>
'orange'
,
});
# the err and errstr methods just proxy up to the Net::Amazon::S3's
# objects err/errstr methods.
$bucket
->add_key(
"bar"
,
"baz"
) or
die
$bucket
->err .
$bucket
->errstr;
# fetch a key
$val
=
$bucket
->get_key(
"key"
);
is(
$val
->{value},
'data'
);
is(
$val
->{content_type},
'text/html'
);
is(
$val
->{etag},
'b9ece18c950afbfa6b0fdbfa4ff731d3'
);
is(
$val
->{
'x-amz-meta-colour'
},
'orange'
);
# returns undef on missing or on error (check $bucket->err)
is(
undef
,
$bucket
->get_key(
"non-existing-key"
));
die
$bucket
->errstr
if
$bucket
->err;
# fetch a key's metadata
$val
=
$bucket
->head_key(
"key"
);
is(
$val
->{value},
''
);
is(
$val
->{content_type},
'text/html'
);
is(
$val
->{etag},
'b9ece18c950afbfa6b0fdbfa4ff731d3'
);
is(
$val
->{
'x-amz-meta-colour'
},
'orange'
);
# delete a key
ok(
$bucket
->delete_key(
$key_name
));
ok(!
$bucket
->delete_key(
"non-exist-key"
));
# delete the entire bucket (Amazon requires it first be empty)
$bucket
->delete_bucket;
DESCRIPTION
This module represents an S3 bucket. You get a bucket object from the Net::Amazon::S3 object.
METHODS
new
Create a new bucket object. Expects a hash containing these two arguments:
add_key
Takes three positional parameters:
Returns a boolean.
add_key_filename
Use this to upload a large file to S3. Takes three positional parameters:
Returns a boolean.
copy_key
Creates (or replaces) a key, copying its contents from another key elsewhere in S3. Takes the following parameters:
- key
-
The key to (over)write
- source
-
Where to copy the key from. Should be in the form
/bucketname/keyname
/. - conf
-
Optional configuration hash. If present and defined, the configuration (ACL and headers) there will be used for the new key; otherwise it will be copied from the source key.
edit_metadata
Changes the metadata associated with an existing key. Arguments:
head_key KEY
Takes the name of a key in this bucket and returns its configuration hash
get_key $key_name [$method]
Takes a key name and an optional HTTP method (which defaults to GET
. Fetches the key from AWS.
On failure:
Returns undef on missing content, throws an exception (dies) on server errors.
On success:
Returns a hashref of { content_type, etag, value, @meta } on success. Other values from the server are there too, with the key being lowercased.
get_key_filename $key_name $method $filename
Use this to download large files from S3. Takes a key name and an optional HTTP method (which defaults to GET
. Fetches the key from AWS and writes it to the filename. THe value returned will be empty.
On failure:
Returns undef on missing content, throws an exception (dies) on server errors.
On success:
Returns a hashref of { content_type, etag, value, @meta } on success
delete_key $key_name
Removes $key
from the bucket. Forever. It's gone after this.
Returns true on success and false on failure
delete_bucket
Delete the current bucket object from the server. Takes no arguments.
Fails if the bucket has anything in it.
This is an alias for $s3->delete_bucket($bucket)
list
List all keys in this bucket.
see "list_bucket" in Net::Amazon::S3 for documentation of this method.
list_all
List all keys in this bucket without having to worry about 'marker'. This may make multiple requests to S3 under the hood.
see "list_bucket_all" in Net::Amazon::S3 for documentation of this method.
get_acl
Takes one optional positional parameter
Returns an acl in XML format.
set_acl
Takes a configuration hash_ref containing:
- acl_xml (cannot be used in conjuction with acl_short)
-
An XML string which contains access control information which matches Amazon's published schema. There is an example of one of these XML strings in the tests for this module.
- acl_short (cannot be used in conjuction with acl_xml)
-
You can use the shorthand notation instead of specifying XML for certain 'canned' types of acls.
(from the Amazon API documentation)
private: Owner gets FULL_CONTROL. No one else has any access rights. This is the default.
public-read:Owner gets FULL_CONTROL and the anonymous principal is granted READ access. If this policy is used on an object, it can be read from a browser with no authentication.
public-read-write:Owner gets FULL_CONTROL, the anonymous principal is granted READ and WRITE access. This is a useful policy to apply to a bucket, if you intend for any anonymous user to PUT objects into the bucket.
authenticated-read:Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.
- key (optional)
-
If the key is not set, it will apply the acl to the bucket.
Returns a boolean.
get_location_constraint
Retrieves the location constraint set when the bucket was created. Returns a string (eg, 'EU'), or undef if no location constraint was set.
err
The S3 error code for the last error the object ran into
errstr
A human readable error string for the last error the object ran into