man > Amazon::S3::Bucket

man perldoc info pydoc3 ri search

📘 NAME

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

🚀 Quick Reference

Use Case	Command	Description
Instantiate bucket	my $bucket = $s3->bucket("foo");	Creates a bucket object (no existence check)
Add key with metadata	$bucket->add_key($key, $value, { content_type => 'text/plain', 'x-amz-meta-colour' => 'orange' });	Uploads a resource with custom HTTP headers and metadata
List all keys	$response = $bucket->list;	Returns a HASHREF with bucket name and array of key details
Check key existence	if ($bucket->head_key($keyname)) { ... }	Returns the key's configuration HASH or undef if not present
Delete a key	$bucket->delete_key($keyname);	Permanently removes the key from the bucket
Delete bucket	$bucket->delete_bucket;	Removes the bucket (must be empty)
Fetch key content	my $data = $bucket->get_key($keyname);	Returns HASHREF with content_type, etag, value, and metadata
Get key to file	$bucket->get_key_filename($key, $method, $filename);	Writes the key’s value directly to a local file
Add key from a local file	$bucket->add_key_filename($key, $filepath, { ... });	Streams a file to S3 without loading into memory
Set bucket/public ACL	$bucket->set_acl({ acl_short => 'public-read' });	Applies common ACL profiles (private, public-read, etc.)
Retrieve bucket ACL	my $xml = $bucket->get_acl;	Returns ACL as XML document
Get location constraint	$bucket->get_location_constraint;	Returns the region/location constraint of the bucket

📖 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

Instantiates a new bucket object.

Requires a hash containing two arguments:

• bucket – The name (identifier) of the bucket.
• account – The Amazon::S3 object (representing the S3 account) this bucket is associated with.

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

Typically a developer will not call this method directly, but work through the interface in Amazon::S3 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 than 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 operation's 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

Sets 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.

👀 SEE ALSO

Amazon::S3

✍️ AUTHOR & COPYRIGHT

Please see the Amazon::S3 manpage for author, copyright, and license information.

📘 NAME 🚀 Quick Reference 📖 SYNOPSIS 🛠️ METHODS 👀 SEE ALSO ✍️ AUTHOR & COPYRIGHT