--- name: "Net::Amazon::S3::Bucket" section: "3pm" platform: "linux" package: "libnet-amazon-s3-perl" version: "0.991-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::Amazon::S3::Bucket" --- # Net::Amazon::S3::Bucket(3pm) convenience object for working with Amazon S3 buckets ## NAME Net::Amazon::S3::Bucket - convenience object for working with Amazon S3 buckets ## VERSION version 0.991 ## 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', })); # Enable server-side encryption ok($bucket->add_key("key", "data", { encryption => 'AES256', })); # 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' ); # fetch a part of the key $val = $bucket->get_key("key", { range => "bytes=1024-10240" }); # 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. - acl - encryption - any additional HTTP header See Net::Amazon::S3::Operation::Object::Add::Request for details 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. ### 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: - key The key to edit - conf The new configuration hash to use ### head\_key KEY Takes the name of a key in this bucket and returns its configuration hash ### query\_string\_authentication\_uri KEY, EXPIRES\_AT ``` my $uri = $bucket->query_string_authentication_uri ( key => 'foo', expires_at => time + 3_600, # valid for one hour ); my $uri = $bucket->query_string_authentication_uri ( key => 'foo', expires_at => time + 3_600, method => 'PUT', ); ``` Returns uri presigned with your credentials. When used with Signature V4 you have to specify also HTTP method this presigned uri will be used for (default: `"GET"`) Method provides authenticated uri only for direct object operations. Method follows API's "CALLING CONVENTION". Recognized positional arguments (mandatory). - key - expires\_at Expiration time (epoch time). Optional arguments - method Default: `"GET"` Intended HTTP method this uri will be presigned for. Signature V2 doesn't use it but Signature V4 does. See \ ### 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 - 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 conjunction 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 conjunction 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 ### add\_tags ``` # Add tags for a bucket $s3->add_tags ({ bucket => 'bucket-name', tags => { tag1 => 'value-1', tag2 => 'value-2' }, }); # Add tags for an object $s3->add_tags ({ bucket => 'bucket-name', key => 'key', tags => { tag1 => 'value-1', tag2 => 'value-2' }, }); ``` Takes configuration parameters - key (optional, scalar) If key is specified, add tag(s) to object, otherwise on bucket. - tags (mandatory, hashref) Set specified tags and their respective values. - version\_id (optional) Is specified (in conjunction with `"key"`) add tag(s) to versioned object. Returns `"true"` on success. Returns `"false"` and sets `"err"`/`"errstr"` otherwise. ### delete\_tags ``` # Add tags for a bucket $s3->delete_tags ({ bucket => 'bucket-name', }); # Add tags for an object $s3->delete_tags ({ bucket => 'bucket-name', key => 'key', version_id => $version_id, }); ``` Takes configuration parameters - key (optional, scalar) If key is specified, add tag(s) to object, otherwise on bucket. - version\_id (optional) Is specified (in conjunction with `"key"`) add tag(s) to versioned object. Returns `"true"` on success. Returns `"false"` and sets `"err"`/`"errstr"` otherwise. ## SEE ALSO Net::Amazon::S3 ## AUTHOR Branislav Zahradník \ ## COPYRIGHT AND LICENSE This software is copyright (c) 2022 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.