Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::Amazon::S3::BuckeUser Contributed Perl DocumentNet::Amazon::S3::Bucket(3)

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

VERSION
       version 0.98

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' );

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

   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 ZahradnAk <barney@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2021 by Amazon Digital Services, Leon
       Brocard,	Brad Fitzpatrick, Pedro	Figueiredo, Rusty Conover, Branislav
       ZahradnAk.

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

perl v5.32.1			  2021-03-22	    Net::Amazon::S3::Bucket(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Amazon::S3::Bucket&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help