{
    "mode": "perldoc",
    "parameter": "Amazon::S3::Bucket",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Amazon%3A%3AS3%3A%3ABucket/json",
    "generated": "2026-10-09T20:42:43Z",
    "synopsis": "use Amazon::S3;\n# creates bucket object (no \"bucket exists\" check)\nmy $bucket = $s3->bucket(\"foo\");\n# create resource with meta data (attributes)\nmy $keyname = 'testing.txt';\nmy $value   = 'T';\n$bucket->addkey(\n$keyname, $value,\n{   contenttype        => 'text/plain',\n'x-amz-meta-colour' => 'orange',\n}\n);\n# list keys in the bucket\n$response = $bucket->list\nor die $s3->err . \": \" . $s3->errstr;\nprint $response->{bucket}.\"\\n\";\nfor my $key (@{ $response->{keys} }) {\nprint \"\\t\".$key->{key}.\"\\n\";\n}\n# check if resource exists.\nprint \"$keyname exists\\n\" if $bucket->headkey($keyname);\n# delete key from bucket\n$bucket->deletekey($keyname);",
    "sections": {
        "NAME": {
            "content": "Amazon::S3::Bucket - A container class for a S3 bucket and its contents.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Amazon::S3;\n\n# creates bucket object (no \"bucket exists\" check)\nmy $bucket = $s3->bucket(\"foo\");\n\n# create resource with meta data (attributes)\nmy $keyname = 'testing.txt';\nmy $value   = 'T';\n$bucket->addkey(\n$keyname, $value,\n{   contenttype        => 'text/plain',\n'x-amz-meta-colour' => 'orange',\n}\n);\n\n# list keys in the bucket\n$response = $bucket->list\nor die $s3->err . \": \" . $s3->errstr;\nprint $response->{bucket}.\"\\n\";\nfor my $key (@{ $response->{keys} }) {\nprint \"\\t\".$key->{key}.\"\\n\";\n}\n\n# check if resource exists.\nprint \"$keyname exists\\n\" if $bucket->headkey($keyname);\n\n# delete key from bucket\n$bucket->deletekey($keyname);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "",
            "subsections": []
        },
        "METHODS AND SUBROUTINES": {
            "content": "new\nInstaniates a new bucket object.\n\nPass a hash or hash reference containing various options:\n\nbucket (required)\nThe name (identifier) of the bucket.\n\naccount (required)\nThe S3::Amazon object (representing the S3 account) this bucket is\nassociated with.\n\nbuffersize\nThe buffer size used for reading and writing objects to S3.\n\ndefault: 4K\n\nregion\nIf no region is set and \"verifyregion\" is set to true, the region\nof the bucket will be determined by calling the\n\"getlocationconstraint\" method. Note that this will decrease\nperformance of the constructor. If you know the region or are\noperating in only 1 region, set the region in the \"account\" object\n(\"Amazon::S3\").\n\nlogger\nSets the logger. The logger should be a blessed reference capable of\nproviding at least a \"debug\" and \"trace\" method for recording log\nmessages. If no logger object is passed the \"account\" object's\nlogger object will be used.\n\nverifyregion\nIndicates that the bucket's region should be determined by calling\nthe \"getlocationconstraint\" method.\n\ndefault: false\n\n*NOTE:* This method does not check if a bucket actually exists unless\nyou set \"verifyregion\" to true. If the bucket does not exist, the\nconstructor will set the region to the default region specified by the\nAmazon::S3 object (\"account\") that you passed.\n\nTypically a developer will not call this method directly, but work\nthrough the interface in S3::Amazon that will handle their creation.\n\naddkey\naddkey( key, value, configuration)\n\nWrite a new or existing object to S3.\n\nkey A string identifier for the object being written to the bucket.\n\nvalue\nA SCALAR string representing the contents of the object.\n\nconfiguration\nA HASHREF of configuration data for this key. The configuration is\ngenerally the HTTP headers you want to pass to the S3 service. The\nclient library will add all necessary headers. Adding them to the\nconfiguration hash will override what the library would send and add\nheaders that are not typically required for S3 interactions.\n\naclshort (optional)\nIn addition to additional and overridden HTTP headers, this HASHREF\ncan have a \"aclshort\" key to set the permissions (access) of the\nresource without a separate call via \"addacl\" or in the form of an\nXML document. See the documentation in \"addacl\" for the values and\nusage.\n\nReturns a boolean indicating the sucess or failure of the call. Check\n\"err\" and \"errstr\" for error messages if this operation fails. To\nexamine the raw output of the response from the API call, use the",
            "subsections": [
                {
                    "name": "last_response",
                    "content": "my $retval = $bucket->addkey('foo', $content, {});\n\nif ( !$retval ) {\nprint STDERR Dumper([$bucket->err, $bucket->errstr, $bucket->lastresponse]);\n}\n\naddkeyfilename\nThe method works like \"addkey\" except the value is assumed to be a\nfilename on the local file system. The file will be streamed rather then\nloaded into memory in one big chunk.\n\ncopyobject %parameters\nCopies an object from one bucket to another bucket. *Note that the\nbucket represented by the bucket object is the destination.* Returns a\nhash reference to the response object (\"CopyObjectResult\").\n\nHeaders returned from the request can be obtained using the"
                },
                {
                    "name": "last_response",
                    "content": "my $headers = { $bucket->lastresponse->headers->flatten };\n\nThrows an exception if the response code is not 2xx. You can get an\nextended error message using the errstr() method.\n\nmy $result = eval { return $s3->copyobject( key => 'foo.jpg',\nsource => 'boo.jpg' ); };\n\nif ($@) {\ndie $s3->errstr;\n}\n\nExamples:\n\n$bucket->copyobject( key => 'foo.jpg', source => 'boo.jpg' );\n\n$bucket->copyobject(\nkey    => 'foo.jpg',\nsource => 'boo.jpg',\nbucket => 'my-source-bucket'\n);\n\n$bucket->copyobject(\nkey     => 'foo.jpg',\nheaders => { 'x-amz-copy-source' => 'my-source-bucket/boo.jpg'\n);\n\nSee CopyObject for more details.\n\n%parameters is a list of key/value pairs described below:\n\nkey (required)\nName of the destination key in the bucket represented by the bucket\nobject.\n\nheaders (optional)\nHash or array reference of headers to send in the request.\n\nbucket (optional)\nName of the source bucket. Default is the same bucket as the\ndestination.\n\nsource (optional)\nName of the source key in the source bucket. If not provided, you\nmust provide the source in the `x-amz-copy-source` header.\n\nheadkey $keyname\nReturns a configuration HASH of the given key. If a key does not exist\nin the bucket \"undef\" will be returned.\n\nHASH will contain the following members:\n\ncontentlength\ncontenttype\netag\nvalue\n\ndeletekey $keyname\nPermanently removes $keyname from the bucket. Returns a boolean value\nindicating the operations success.\n\ndeletekeys @keys\ndeletekeys $keys\nPermanently removes keys from the bucket. Returns the response body from\nthe API call. Returns \"undef\" on non '2xx' return codes.\n\nSee <Deleting Amazon S3 object |\nhttps://docs.aws.amazon.com/AmazonS3/latest/userguide/DeletingObjects.ht\nml>\n\nThe argument to \"deletekeys\" can be:\n\n*    list of key names\n\n*    an array of hashes where each hash reference contains the keys\n\"Key\" and optionally \"VersionId\".\n\n*    an array of scalars where each scalar is a key name\n\n*    a hash of options where the hash contains\n\n*    a callback that returns the key and optionally the version id\n\nquiet     Boolean indicating quiet mode\n\nkeys      An array of keys containing scalars or hashes as describe\nabove.\n\nExamples:\n\n# delete a list of keys\n$bucket->deletekeys(qw( foo bar baz));\n\n# delete an array of keys\n$bucket->deletekeys([qw(foo bar baz)]);\n\n# delete an array of keys in quiet mode\n$bucket->delete({ quiet => 1, keys => [ qw(foo bar baz) ]);\n\n# delete an array of versioned objects\n$bucket->deletekeys([ { Key => 'foo', VersionId => '1'} ]);\n\n# callback\nmy @keylist = qw(foo => 1, bar => 3, biz => 1);\n\n$bucket->deletekeys(\nsub {\nreturn ( shift @keylist, shift @keylist );\n}\n);\n\n*When using a callback, the keys are deleted in bulk. The\n\"DeleteObjects\" API is only called once.*\n\ndeletebucket\nPermanently removes the bucket from the server. A bucket cannot be\nremoved if it contains any keys (contents).\n\nThis is an alias for \"$s3->deletebucket($bucket)\".\n\ngetkey $keyname, [$method]\nTakes a key and an optional HTTP method and fetches it from S3. The\ndefault HTTP method is GET.\n\nThe method returns \"undef\" if the key does not exist in the bucket and\nthrows an exception (dies) on server errors.\n\nOn success, the method returns a HASHREF containing:\n\ncontenttype\netag\nvalue\n@meta\n\ngetkeyfilename $keyname, $method, $filename\nThis method works like \"getkey\", but takes an added filename that the\nS3 resource will be written to.\n\nlist\nList all keys in this bucket.\n\nSee \"listbucket\" in Amazon::S3 for documentation of this method.\n\nlistv2\nSee \"listbucketv2\" in Amazon::S3 for documentation of this method.\n\nlistall\nList all keys in this bucket without having to worry about 'marker'.\nThis may make multiple requests to S3 under the hood.\n\nSee \"listbucketall\" in Amazon::S3 for documentation of this method.\n\nlistallv2\nSame as \"listall\" but uses the version 2 API for listing keys.\n\nSee \"listbucketallv2\" in Amazon::S3 for documentation of this method.\n\ngetacl\nRetrieves the Access Control List (ACL) for the bucket or resource as an\nXML document.\n\nkey The key of the stored resource to fetch. This parameter is optional.\nBy default the method returns the ACL for the bucket itself.\n\nsetacl\nsetacl(acl)\n\nRetrieves the Access Control List (ACL) for the bucket or resource.\nRequires a HASHREF argument with one of the following keys:\n\naclxml\nAn XML string which contains access control information which\nmatches Amazon's published schema.\n\naclshort\nAlternative shorthand notation for common types of ACLs that can be\nused in place of a ACL XML document.\n\nAccording to the Amazon S3 API documentation the following\nrecognized aclshort types are defined as follows:\n\nprivate\nOwner gets FULLCONTROL. No one else has any access rights. This\nis the default.\n\npublic-read\nOwner gets FULLCONTROL and the anonymous principal is granted\nREAD access. If this policy is used on an object, it can be read\nfrom a browser with no authentication.\n\npublic-read-write\nOwner gets FULLCONTROL, the anonymous principal is granted READ\nand WRITE access. This is a useful policy to apply to a bucket,\nif you intend for any anonymous user to PUT objects into the\nbucket.\n\nauthenticated-read\nOwner gets FULLCONTROL, and any principal authenticated as a\nregistered Amazon S3 user is granted READ access.\n\nkey The key name to apply the permissions. If the key is not provided\nthe bucket ACL will be set.\n\nReturns a boolean indicating the operations success.\n\ngetlocationconstraint\nReturns the location constraint (region the bucket resides in) for a\nbucket. Returns undef if no location constraint.\n\nValid values that may be returned:\n\naf-south-1\nap-east-1\nap-northeast-1\nap-northeast-2\nap-northeast-3\nap-south-1\nap-southeast-1\nap-southeast-2\nca-central-1\ncn-north-1\ncn-northwest-1\nEU\neu-central-1\neu-north-1\neu-south-1\neu-west-1\neu-west-2\neu-west-3\nme-south-1\nsa-east-1\nus-east-2\nus-gov-east-1\nus-gov-west-1\nus-west-1\nus-west-2\n\nFor more information on location constraints, refer to the documentation\nfor GetBucketLocation\n<https://docs.aws.amazon.com/AmazonS3/latest/API/APIGetBucketLocation.h\ntml>.\n\nerr\nThe S3 error code for the last error the account encountered.\n\nerrstr\nA human readable error string for the last error the account\nencountered.\n\nerror\nThe decoded XML string as a hash object of the last error.\n\nlastresponse\nReturns the last \"HTTP::Response\" to an API call.\n"
                }
            ]
        },
        "MULTIPART UPLOAD SUPPORT": {
            "content": "From Amazon's website:\n\n*Multipart upload allows you to upload a single object as a set of\nparts. Each part is a contiguous portion of the object's data. You can\nupload these object parts independently and in any order. If\ntransmission of any part fails, you can retransmit that part without\naffecting other parts. After all parts of your object are uploaded,\nAmazon S3 assembles these parts and creates the object. In general, when\nyour object size reaches 100 MB, you should consider using multipart\nuploads instead of uploading the object in a single operation.*\n\nSee\n<https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html>\nfor more information about multipart uploads.\n\n*    Maximum object size 5TB\n\n*    Maximum number of parts 10,000\n\n*    Part numbers 1 to 10,000 (inclusive)\n\n*    Part size 5MB to 5GB. There is no limit on the last part of your\nmultipart upload.\n\n*    Maximum nubmer of parts returned for a list parts request - 1000\n\n*    Maximum number of multipart uploads returned in a list multipart\nuploads request - 1000\n\nA multipart upload begins by calling initiatemultipartupload(). This\nwill return an identifier that is used in subsequent calls.\n\nmy $bucket = $s3->bucket('my-bucket');\nmy $id = $bucket->initiatemultipartupload('some-big-object');\n\nmy $partlist = {};\n\nmy $part = 1;\nmy $etag = $bucket->uploadpartofmultipartupload('my-bucket', $id, $part, $data, length $data);\n$partlist{$part++} = $etag;\n\n$bucket->completemultipartupload('my-bucket', $id, $partlist);\n\nuploadmultipartobject( ... )\n\nConvenience routine \"uploadmultipartobject\" that encapsulates the\nmultipart upload process. Accepts a hash or hash reference of arguments.\nIf successful, a reference to a hash that contains the part numbers and\netags of the uploaded parts.\n\nYou can pass a data object, callback routine or a file handle.\n\nkey  Name of the key to create.\n\ndata Scalar object that contains the data to write to S3.\n\ncallback\nOptionally provided a callback routine that will be called until\nyou pass a buffer with a length of 0. Your callback will receive no\narguments but should return a tuple consisting of a reference to a\nscalar object that contains the data to write and a scalar that\nrepresents the length of data. Once you return a zero length buffer\nthe multipart process will be completed.\n\nfh   File handle of an open file. The file must be greater than the\nminimum chunk size for multipart uploads otherwise the method will\nthrow an exception.\n\nabortonerror\nIndicates whether the multipart upload should be aborted if an\nerror is encountered. Amazon will charge you for the storage of\nparts that have been uploaded unless you abort the upload.\n\ndefault: true\n\nabortmultipartupload\nabortmultipartupload(key, multpart-upload-id)\n\nAbort a multipart upload\n\ncompletemultipartupload\ncompletemultipartupload(key, multpart-upload-id, parts)\n\nSignal completion of a multipart upload. \"parts\" is a reference to a\nhash of part numbers and etags.\n\ninitiatemultipartupload\ninitiatemultipartupload(key, headers)\n\nInitiate a multipart upload. Returns an id used in subsequent call to",
            "subsections": [
                {
                    "name": "upload_part_of_multipart_upload",
                    "content": "listmultipartuploadparts\nList all the uploaded parts of a multipart upload\n\nlistmultipartuploads\nList multipart uploads in progress\n\nuploadpartofmultipartupload\nuploadpartofmultipartupload(key, id, part, data, length)\n\nUpload a portion of a multipart upload\n\nkey  Name of the key in the bucket to create.\n\nid   The multipart-upload id return in the \"initiatemultipartupload\"\ncall.\n\npart The next part number (part numbers start at 1).\n\ndata Scalar or reference to a scalar that contains the data to upload.\n\nlength (optional)\nLength of the data.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "Amazon::S3\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Please see the Amazon::S3 manpage for author, copyright, and license\ninformation.\n",
            "subsections": []
        },
        "CONTRIBUTORS": {
            "content": "Rob Lauer Jojess Fournier Tim Mullin Todd Rinaldo luiserd97\n",
            "subsections": []
        },
        "POD ERRORS": {
            "content": "Hey! The above document had some coding errors, which are explained\nbelow:\n\nAround line 1714:\nUnknown directive: =heads\n",
            "subsections": []
        }
    },
    "summary": "Amazon::S3::Bucket - A container class for a S3 bucket and its contents.",
    "flags": [],
    "examples": [],
    "see_also": []
}