.. _perl:

Perl S3 Examples

Creating a Connection

This creates a connection so that you can interact with the server.

.. code-block:: perl

use Amazon::S3;
my $access_key = 'put your access key here!';
my $secret_key = 'put your secret key here!';

my $conn = Amazon::S3->new({
	aws_access_key_id     => $access_key,
	aws_secret_access_key => $secret_key,
	host                  => 'objects.dreamhost.com',
	secure                => 1,
	retry                 => 1,
});

Listing Owned Buckets

This gets a list of Amazon::S3::Bucket_ objects that you own. We'll also print out the bucket name and creation date of each bucket.

.. code-block:: perl

my @buckets = @{$conn->buckets->{buckets} || []};
foreach my $bucket (@buckets) {
	print $bucket->bucket . "\t" . $bucket->creation_date . "\n";
}

The output will look something like this::

mahbuckat1 2011-04-21T18:05:39.000Z mahbuckat2 2011-04-21T18:05:48.000Z mahbuckat3 2011-04-21T18:07:18.000Z

Creating a Bucket

This creates a new bucket called my-new-bucket

.. code-block:: perl

my $bucket = $conn->add_bucket({ bucket => 'my-new-bucket' });

Listing a Bucket's Content

This gets a list of hashes with info about each object in the bucket. We'll also print out each object's name, the file size, and last modified date.

.. code-block:: perl

my @keys = @{$bucket->list_all->{keys} || []};
foreach my $key (@keys) {
	print "$key->{key}\t$key->{size}\t$key->{last_modified}\n";
}

The output will look something like this::

myphoto1.jpg 251262 2011-08-08T21:35:48.000Z myphoto2.jpg 262518 2011-08-08T21:38:01.000Z

Deleting a Bucket

.. note:: The bucket must be empty! Otherwise it won't work!

.. code-block:: perl

$conn->delete_bucket($bucket);

Forced Delete for Non-empty Buckets

.. attention::

not available in the Amazon::S3_ Perl module

Creating an Object

This creates a file hello.txt with the string "Hello World!"

.. code-block:: perl

$bucket->add_key(
	'hello.txt', 'Hello World!',
	{ content_type => 'text/plain' },
);

Change an Object's ACL

This makes the object hello.txt to be publicly readable and secret_plans.txt to be private.

.. code-block:: perl

$bucket->set_acl({
	key       => 'hello.txt',
	acl_short => 'public-read',
});
$bucket->set_acl({
	key       => 'secret_plans.txt',
	acl_short => 'private',
});

Download an Object (to a file)

This downloads the object perl_poetry.pdf and saves it in /home/larry/documents/

.. code-block:: perl

$bucket->get_key_filename('perl_poetry.pdf', undef,
	'/home/larry/documents/perl_poetry.pdf');

Delete an Object

This deletes the object goodbye.txt

.. code-block:: perl

$bucket->delete_key('goodbye.txt');

Generate Object Download URLs (signed and unsigned)

This generates an unsigned download URL for hello.txt. This works because we made hello.txt public by setting the ACL above. It then generates a signed download URL for secret_plans.txt that will work for 1 hour. Signed download URLs will work for the time period even if the object is private (when the time period is up, the URL will stop working).

.. note:: The Amazon::S3_ module does not have a way to generate download URLs, so we are going to be using another module instead. Unfortunately, most modules for generating these URLs assume that you are using Amazon, so we have had to go with using a more obscure module, Muck::FS::S3. This should be the same as Amazon's sample S3 Perl module, but this sample module is not in CPAN. So, you can either use CPAN to install Muck::FS::S3, or install Amazon's sample S3 module manually. If you go the manual route, you can remove Muck::FS:: from the example below.

.. code-block:: perl

use Muck::FS::S3::QueryStringAuthGenerator;
my $generator = Muck::FS::S3::QueryStringAuthGenerator->new(
	$access_key,
	$secret_key,
	0, # 0 means use 'http'. set this to 1 for 'https'
	'objects.dreamhost.com',
);

my $hello_url = $generator->make_bare_url($bucket->bucket, 'hello.txt');
print $hello_url . "\n";

$generator->expires_in(3600); # 1 hour = 3600 seconds
my $plans_url = $generator->get($bucket->bucket, 'secret_plans.txt');
print $plans_url . "\n";

The output will look something like this::

http://objects.dreamhost.com:80/my-bucket-name/hello.txt http://objects.dreamhost.com:80/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX

.. _Amazon::S3: http://search.cpan.org/~tima/Amazon-S3-0.441/lib/Amazon/S3.pm .. _Amazon::S3::Bucket: http://search.cpan.org/~tima/Amazon-S3-0.441/lib/Amazon/S3/Bucket.pm .. _Muck::FS::S3: http://search.cpan.org/~mike/Muck-0.02/