summaryrefslogtreecommitdiffstats
path: root/doc/radosgw/s3/perl.rst
blob: f12e5c6987f6602b97c1516d6d62ad57eb48fb2c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
.. _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.
Then this 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/