GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::Amazon::S3::Bucket(3) User Contributed Perl Documentation Net::Amazon::S3::Bucket(3)

Net::Amazon::S3::Bucket - convenience object for working with Amazon S3 buckets

version 0.99 

  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;

This module represents an S3 bucket. You get a bucket object from the Net::Amazon::S3 object.

Create a new bucket object. Expects a hash containing these two arguments:
bucket
account

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.

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.

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.

Changes the metadata associated with an existing key. Arguments:
key
The key to edit
conf
The new configuration hash to use

Takes the name of a key in this bucket and returns its configuration hash 

        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 <https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html>

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.

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

Removes $key from the bucket. Forever. It's gone after this.

Returns true on success and false on failure

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 all keys in this bucket.

see "list_bucket" in Net::Amazon::S3 for documentation of this method.

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.

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.

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.

Retrieves the location constraint set when the bucket was created. Returns a string (eg, 'EU'), or undef if no location constraint was set.

The S3 error code for the last error the object ran into

A human readable error string for the last error the object ran into 

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

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

Net::Amazon::S3

Branislav Zahradník <barney@cpan.org>

This software is copyright (c) 2021 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.

2021-12-05 perl v5.32.1
Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.