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


Manual Reference Pages  -  NET::AMAZON::S3::BUCKET (3)

.ds Aq ’

NAME

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

CONTENTS

VERSION

version 0.80

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,
  }));

  # the err and errstr methods just proxy up to the Net::Amazon::S3s
  # 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 );

  # 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 keys 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. (See synopsis);
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

get_key CW$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 CW$key_name CW$method CW$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 CW$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

SEE ALSO

Net::Amazon::S3

AUTHOR

Rusty Conover <rusty@luckydinosaur.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NET::AMAZON::S3::BUCKET (3) 2015-04-12

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