.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Net::Amazon::S3::Bucket 3pm" .TH Net::Amazon::S3::Bucket 3pm "2022-07-18" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Amazon::S3::Bucket \- convenience object for working with Amazon S3 buckets .SH "VERSION" .IX Header "VERSION" version 0.991 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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", \& \*(Aqx\-amz\-meta\-colour\*(Aq => \*(Aqorange\*(Aq, \& })); \& \& # Enable server\-side encryption \& ok($bucket\->add_key("key", "data", { \& encryption => \*(AqAES256\*(Aq, \& })); \& \& # the err and errstr methods just proxy up to the Net::Amazon::S3\*(Aqs \& # 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}, \*(Aqdata\*(Aq ); \& is( $val\->{content_type}, \*(Aqtext/html\*(Aq ); \& is( $val\->{etag}, \*(Aqb9ece18c950afbfa6b0fdbfa4ff731d3\*(Aq ); \& is( $val\->{\*(Aqx\-amz\-meta\-colour\*(Aq}, \*(Aqorange\*(Aq ); \& \& # 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\*(Aqs metadata \& $val = $bucket\->head_key("key"); \& is( $val\->{value}, \*(Aq\*(Aq ); \& is( $val\->{content_type}, \*(Aqtext/html\*(Aq ); \& is( $val\->{etag}, \*(Aqb9ece18c950afbfa6b0fdbfa4ff731d3\*(Aq ); \& is( $val\->{\*(Aqx\-amz\-meta\-colour\*(Aq}, \*(Aqorange\*(Aq ); \& \& # 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; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module represents an S3 bucket. You get a bucket object from the Net::Amazon::S3 object. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" Create a new bucket object. Expects a hash containing these two arguments: .IP "bucket" 4 .IX Item "bucket" .PD 0 .IP "account" 4 .IX Item "account" .PD .SS "add_key" .IX Subsection "add_key" Takes three positional parameters: .IP "key" 4 .IX Item "key" .PD 0 .IP "value" 4 .IX Item "value" .IP "configuration" 4 .IX Item "configuration" .PD A hash of configuration data for this key. .RS 4 .IP "acl" 4 .IX Item "acl" .PD 0 .IP "encryption" 4 .IX Item "encryption" .IP "any additional \s-1HTTP\s0 header" 4 .IX Item "any additional HTTP header" .RE .RS 4 .PD .Sp See Net::Amazon::S3::Operation::Object::Add::Request for details .RE .PP Returns a boolean. .SS "add_key_filename" .IX Subsection "add_key_filename" Use this to upload a large file to S3. Takes three positional parameters: .IP "key" 4 .IX Item "key" .PD 0 .IP "filename" 4 .IX Item "filename" .IP "configuration" 4 .IX Item "configuration" .PD A hash of configuration data for this key. (See synopsis); .PP Returns a boolean. .SS "copy_key" .IX Subsection "copy_key" Creates (or replaces) a key, copying its contents from another key elsewhere in S3. Takes the following parameters: .IP "key" 4 .IX Item "key" The key to (over)write .IP "source" 4 .IX Item "source" Where to copy the key from. Should be in the form \f(CW\*(C`/\f(CIbucketname\f(CW/\f(CIkeyname\f(CW\*(C'\fR/. .IP "conf" 4 .IX Item "conf" Optional configuration hash. If present and defined, the configuration (\s-1ACL\s0 and headers) there will be used for the new key; otherwise it will be copied from the source key. .SS "edit_metadata" .IX Subsection "edit_metadata" Changes the metadata associated with an existing key. Arguments: .IP "key" 4 .IX Item "key" The key to edit .IP "conf" 4 .IX Item "conf" The new configuration hash to use .SS "head_key \s-1KEY\s0" .IX Subsection "head_key KEY" Takes the name of a key in this bucket and returns its configuration hash .SS "query_string_authentication_uri \s-1KEY, EXPIRES_AT\s0" .IX Subsection "query_string_authentication_uri KEY, EXPIRES_AT" .Vb 4 \& my $uri = $bucket\->query_string_authentication_uri ( \& key => \*(Aqfoo\*(Aq, \& expires_at => time + 3_600, # valid for one hour \& ); \& \& my $uri = $bucket\->query_string_authentication_uri ( \& key => \*(Aqfoo\*(Aq, \& expires_at => time + 3_600, \& method => \*(AqPUT\*(Aq, \& ); .Ve .PP Returns uri presigned with your credentials. .PP When used with Signature V4 you have to specify also \s-1HTTP\s0 method this presigned uri will be used for (default: \f(CW\*(C`GET\*(C'\fR) .PP Method provides authenticated uri only for direct object operations. .PP Method follows \s-1API\s0's \*(L"\s-1CALLING CONVENTION\*(R"\s0. .PP Recognized positional arguments (mandatory). .IP "key" 4 .IX Item "key" .PD 0 .IP "expires_at" 4 .IX Item "expires_at" .PD Expiration time (epoch time). .PP Optional arguments .IP "method" 4 .IX Item "method" Default: \f(CW\*(C`GET\*(C'\fR .Sp Intended \s-1HTTP\s0 method this uri will be presigned for. .Sp Signature V2 doesn't use it but Signature V4 does. .Sp See .ie n .SS "get_key $key_name [$method]" .el .SS "get_key \f(CW$key_name\fP [$method]" .IX Subsection "get_key $key_name [$method]" Takes a key name and an optional \s-1HTTP\s0 method (which defaults to \f(CW\*(C`GET\*(C'\fR. Fetches the key from \s-1AWS.\s0 .PP On failure: .PP Returns undef on missing content, throws an exception (dies) on server errors. .PP On success: .PP Returns a hashref of { content_type, etag, value, \f(CW@meta\fR } on success. Other values from the server are there too, with the key being lowercased. .ie n .SS "get_key_filename $key_name $method $filename" .el .SS "get_key_filename \f(CW$key_name\fP \f(CW$method\fP \f(CW$filename\fP" .IX Subsection "get_key_filename $key_name $method $filename" Use this to download large files from S3. Takes a key name and an optional \&\s-1HTTP\s0 method (which defaults to \f(CW\*(C`GET\*(C'\fR. Fetches the key from \s-1AWS\s0 and writes it to the filename. THe value returned will be empty. .PP On failure: .PP Returns undef on missing content, throws an exception (dies) on server errors. .PP On success: .PP Returns a hashref of { content_type, etag, value, \f(CW@meta\fR } on success .ie n .SS "delete_key $key_name" .el .SS "delete_key \f(CW$key_name\fP" .IX Subsection "delete_key $key_name" Removes \f(CW$key\fR from the bucket. Forever. It's gone after this. .PP Returns true on success and false on failure .SS "delete_bucket" .IX Subsection "delete_bucket" Delete the current bucket object from the server. Takes no arguments. .PP Fails if the bucket has anything in it. .PP This is an alias for \f(CW\*(C`$s3\->delete_bucket($bucket)\*(C'\fR .SS "list" .IX Subsection "list" List all keys in this bucket. .PP see \*(L"list_bucket\*(R" in Net::Amazon::S3 for documentation of this method. .SS "list_all" .IX Subsection "list_all" List all keys in this bucket without having to worry about \&'marker'. This may make multiple requests to S3 under the hood. .PP see \*(L"list_bucket_all\*(R" in Net::Amazon::S3 for documentation of this method. .SS "get_acl" .IX Subsection "get_acl" Takes one optional positional parameter .IP "key (optional)" 4 .IX Item "key (optional)" If no key is specified, it returns the acl for the bucket. .PP Returns an acl in \s-1XML\s0 format. .SS "set_acl" .IX Subsection "set_acl" Takes a configuration hash_ref containing: .IP "acl_xml (cannot be used in conjunction with acl_short)" 4 .IX Item "acl_xml (cannot be used in conjunction with acl_short)" An \s-1XML\s0 string which contains access control information which matches Amazon's published schema. There is an example of one of these \s-1XML\s0 strings in the tests for this module. .IP "acl_short (cannot be used in conjunction with acl_xml)" 4 .IX Item "acl_short (cannot be used in conjunction with acl_xml)" You can use the shorthand notation instead of specifying \s-1XML\s0 for certain 'canned' types of acls. .Sp (from the Amazon \s-1API\s0 documentation) .Sp private: Owner gets \s-1FULL_CONTROL.\s0 No one else has any access rights. This is the default. .Sp public\-read:Owner gets \s-1FULL_CONTROL\s0 and the anonymous principal is granted \&\s-1READ\s0 access. If this policy is used on an object, it can be read from a browser with no authentication. .Sp public\-read\-write:Owner gets \s-1FULL_CONTROL,\s0 the anonymous principal is granted \s-1READ\s0 and \s-1WRITE\s0 access. This is a useful policy to apply to a bucket, if you intend for any anonymous user to \s-1PUT\s0 objects into the bucket. .Sp authenticated\-read:Owner gets \s-1FULL_CONTROL,\s0 and any principal authenticated as a registered Amazon S3 user is granted \s-1READ\s0 access. .IP "key (optional)" 4 .IX Item "key (optional)" If the key is not set, it will apply the acl to the bucket. .PP Returns a boolean. .SS "get_location_constraint" .IX Subsection "get_location_constraint" Retrieves the location constraint set when the bucket was created. Returns a string (eg, '\s-1EU\s0'), or undef if no location constraint was set. .SS "err" .IX Subsection "err" The S3 error code for the last error the object ran into .SS "errstr" .IX Subsection "errstr" A human readable error string for the last error the object ran into .SS "add_tags" .IX Subsection "add_tags" .Vb 5 \& # Add tags for a bucket \& $s3\->add_tags ({ \& bucket => \*(Aqbucket\-name\*(Aq, \& tags => { tag1 => \*(Aqvalue\-1\*(Aq, tag2 => \*(Aqvalue\-2\*(Aq }, \& }); \& \& # Add tags for an object \& $s3\->add_tags ({ \& bucket => \*(Aqbucket\-name\*(Aq, \& key => \*(Aqkey\*(Aq, \& tags => { tag1 => \*(Aqvalue\-1\*(Aq, tag2 => \*(Aqvalue\-2\*(Aq }, \& }); .Ve .PP Takes configuration parameters .IP "key (optional, scalar)" 4 .IX Item "key (optional, scalar)" If key is specified, add tag(s) to object, otherwise on bucket. .IP "tags (mandatory, hashref)" 4 .IX Item "tags (mandatory, hashref)" Set specified tags and their respective values. .IP "version_id (optional)" 4 .IX Item "version_id (optional)" Is specified (in conjunction with \f(CW\*(C`key\*(C'\fR) add tag(s) to versioned object. .PP Returns \f(CW\*(C`true\*(C'\fR on success. .PP Returns \f(CW\*(C`false\*(C'\fR and sets \f(CW\*(C`err\*(C'\fR/\f(CW\*(C`errstr\*(C'\fR otherwise. .SS "delete_tags" .IX Subsection "delete_tags" .Vb 4 \& # Add tags for a bucket \& $s3\->delete_tags ({ \& bucket => \*(Aqbucket\-name\*(Aq, \& }); \& \& # Add tags for an object \& $s3\->delete_tags ({ \& bucket => \*(Aqbucket\-name\*(Aq, \& key => \*(Aqkey\*(Aq, \& version_id => $version_id, \& }); .Ve .PP Takes configuration parameters .IP "key (optional, scalar)" 4 .IX Item "key (optional, scalar)" If key is specified, add tag(s) to object, otherwise on bucket. .IP "version_id (optional)" 4 .IX Item "version_id (optional)" Is specified (in conjunction with \f(CW\*(C`key\*(C'\fR) add tag(s) to versioned object. .PP Returns \f(CW\*(C`true\*(C'\fR on success. .PP Returns \f(CW\*(C`false\*(C'\fR and sets \f(CW\*(C`err\*(C'\fR/\f(CW\*(C`errstr\*(C'\fR otherwise. .SH "SEE ALSO" .IX Header "SEE ALSO" Net::Amazon::S3 .SH "AUTHOR" .IX Header "AUTHOR" Branislav Zahradník .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2022 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.