phpman > perldoc > Amazon::S3::Bucket(3pm)

Che Dong

NAME
Amazon::S3::Bucket - A container class for a S3 bucket and its contents.

SYNOPSIS
use Amazon::S3;

# creates bucket object (no "bucket exists" check)
my $bucket = $s3->bucket("foo");

# create resource with meta data (attributes)
my $keyname = 'testing.txt';
my $value = 'T';
$bucket->add_key(
$keyname, $value,
{ content_type => 'text/plain',
'x-amz-meta-colour' => 'orange',
}
);

# list keys in the bucket
$response = $bucket->list
or die $s3->err . ": " . $s3->errstr;
print $response->{bucket}."\n";
for my $key (@{ $response->{keys} }) {
print "\t".$key->{key}."\n";
}

# check if resource exists.
print "$keyname exists\n" if $bucket->head_key($keyname);

# delete key from bucket
$bucket->delete_key($keyname);

METHODS
new
Instaniates a new bucket object.

Requires a hash containing two arguments:

bucket
The name (identifier) of the bucket.

account
The S3::Amazon object (representing the S3 account) this bucket is associated with.

NOTE: This method does not check if a bucket actually exists. It simply instaniates the bucket.

Typically a developer will not call this method directly, but work through the interface in
S3::Amazon that will handle their creation.

add_key
Takes three positional parameters:

key A string identifier for the resource in this bucket

value
A SCALAR string representing the contents of the resource.

configuration
A HASHREF of configuration data for this key. The configuration is generally the HTTP
headers you want to pass the S3 service. The client library will add all necessary headers.
Adding them to the configuration hash will override what the library would send and add
headers that are not typically required for S3 interactions.

In addition to additional and overridden HTTP headers, this HASHREF can have a "acl_short"
key to set the permissions (access) of the resource without a separate call via "add_acl" or
in the form of an XML document. See the documentation in "add_acl" for the values and usage.

Returns a boolean indicating its success. Check "err" and "errstr" for error message if this
operation fails.

add_key_filename
The method works like "add_key" except the value is assumed to be a filename on the local file
system. The file will be streamed rather then loaded into memory in one big chunk.

head_key $key_name
Returns a configuration HASH of the given key. If a key does not exist in the bucket "undef"
will be returned.

get_key $key_name, [$method]
Takes a key and an optional HTTP method and fetches it from S3. The default HTTP method is GET.

The method returns "undef" if the key does not exist in the bucket and throws an exception
(dies) on server errors.

On success, the method returns a HASHREF containing:

content_type
etag
value
@meta

get_key_filename $key_name, $method, $filename
This method works like "get_key", but takes an added filename that the S3 resource will be
written to.

delete_key $key_name
Permanently removes $key_name from the bucket. Returns a boolean value indicating the operations
success.

delete_bucket
Permanently removes the bucket from the server. A bucket cannot be removed if it contains any
keys (contents).

This is an alias for "$s3-"delete_bucket($bucket)>.

list
List all keys in this bucket.

See "list_bucket" in 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 Amazon::S3 for documentation of this method.

get_acl
Retrieves the Access Control List (ACL) for the bucket or resource as an XML document.

key The key of the stored resource to fetch. This parameter is optional. By default the method
returns the ACL for the bucket itself.

set_acl $conf
Retrieves the Access Control List (ACL) for the bucket or resource. Requires a HASHREF argument
with one of the following keys:

acl_xml
An XML string which contains access control information which matches Amazon's published
schema.

acl_short
Alternative shorthand notation for common types of ACLs that can be used in place of a ACL
XML document.

According to the Amazon S3 API documentation the following recognized acl_short types are
defined as follows:

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 The key name to apply the permissions. If the key is not provided the bucket ACL will be
set.

Returns a boolean indicating the operations success.

get_location_constraint
Returns the location constraint data on a bucket.

For more information on location constraints, refer to the Amazon S3 Developer Guide.

err
The S3 error code for the last error the account encountered.

errstr
A human readable error string for the last error the account encountered.