Linux Certif

Toute la documentation sur la certification Linux LPI

Net::Amazon::S3::Bucket.3pm

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:

bucket

account

add_key

Takes three positional parameters:

key

value

configuration

A hash of configuration data for this key. (See synopsis);

Returns a boolean.

add_key_filename

Use this to upload a large file to S3. Takes three positional parameters:

key

filename

configuration

A hash of configuration data for this key. (See synopsis);

Returns a boolean.

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

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

key (optional)

If no key is specified, it returns the acl for the bucket.

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

SEE ALSO

Net::Amazon::S3