]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. _perl: |
2 | ||
3 | Perl S3 Examples | |
4 | ================ | |
5 | ||
6 | Creating a Connection | |
7 | --------------------- | |
8 | ||
9 | This creates a connection so that you can interact with the server. | |
10 | ||
11 | .. code-block:: perl | |
12 | ||
13 | use Amazon::S3; | |
14 | my $access_key = 'put your access key here!'; | |
15 | my $secret_key = 'put your secret key here!'; | |
16 | ||
17 | my $conn = Amazon::S3->new({ | |
18 | aws_access_key_id => $access_key, | |
19 | aws_secret_access_key => $secret_key, | |
20 | host => 'objects.dreamhost.com', | |
21 | secure => 1, | |
22 | retry => 1, | |
23 | }); | |
24 | ||
25 | ||
26 | Listing Owned Buckets | |
27 | --------------------- | |
28 | ||
29 | This gets a list of `Amazon::S3::Bucket`_ objects that you own. | |
30 | We'll also print out the bucket name and creation date of each bucket. | |
31 | ||
32 | .. code-block:: perl | |
33 | ||
34 | my @buckets = @{$conn->buckets->{buckets} || []}; | |
35 | foreach my $bucket (@buckets) { | |
36 | print $bucket->bucket . "\t" . $bucket->creation_date . "\n"; | |
37 | } | |
38 | ||
39 | The output will look something like this:: | |
40 | ||
41 | mahbuckat1 2011-04-21T18:05:39.000Z | |
42 | mahbuckat2 2011-04-21T18:05:48.000Z | |
43 | mahbuckat3 2011-04-21T18:07:18.000Z | |
44 | ||
45 | ||
46 | Creating a Bucket | |
47 | ----------------- | |
48 | ||
49 | This creates a new bucket called ``my-new-bucket`` | |
50 | ||
51 | .. code-block:: perl | |
52 | ||
53 | my $bucket = $conn->add_bucket({ bucket => 'my-new-bucket' }); | |
54 | ||
55 | ||
56 | Listing a Bucket's Content | |
57 | -------------------------- | |
58 | ||
59 | This gets a list of hashes with info about each object in the bucket. | |
60 | We'll also print out each object's name, the file size, and last | |
61 | modified date. | |
62 | ||
63 | .. code-block:: perl | |
64 | ||
65 | my @keys = @{$bucket->list_all->{keys} || []}; | |
66 | foreach my $key (@keys) { | |
67 | print "$key->{key}\t$key->{size}\t$key->{last_modified}\n"; | |
68 | } | |
69 | ||
70 | The output will look something like this:: | |
71 | ||
72 | myphoto1.jpg 251262 2011-08-08T21:35:48.000Z | |
73 | myphoto2.jpg 262518 2011-08-08T21:38:01.000Z | |
74 | ||
75 | ||
76 | Deleting a Bucket | |
77 | ----------------- | |
78 | ||
79 | .. note:: | |
80 | The Bucket must be empty! Otherwise it won't work! | |
81 | ||
82 | .. code-block:: perl | |
83 | ||
84 | $conn->delete_bucket($bucket); | |
85 | ||
86 | ||
87 | Forced Delete for Non-empty Buckets | |
88 | ----------------------------------- | |
89 | ||
90 | .. attention:: | |
91 | ||
92 | not available in the `Amazon::S3`_ perl module | |
93 | ||
94 | ||
95 | Creating an Object | |
96 | ------------------ | |
97 | ||
98 | This creates a file ``hello.txt`` with the string ``"Hello World!"`` | |
99 | ||
100 | .. code-block:: perl | |
101 | ||
102 | $bucket->add_key( | |
103 | 'hello.txt', 'Hello World!', | |
104 | { content_type => 'text/plain' }, | |
105 | ); | |
106 | ||
107 | ||
108 | Change an Object's ACL | |
109 | ---------------------- | |
110 | ||
111 | This makes the object ``hello.txt`` to be publicly readable and | |
112 | ``secret_plans.txt`` to be private. | |
113 | ||
114 | .. code-block:: perl | |
115 | ||
116 | $bucket->set_acl({ | |
117 | key => 'hello.txt', | |
118 | acl_short => 'public-read', | |
119 | }); | |
120 | $bucket->set_acl({ | |
121 | key => 'secret_plans.txt', | |
122 | acl_short => 'private', | |
123 | }); | |
124 | ||
125 | ||
126 | Download an Object (to a file) | |
127 | ------------------------------ | |
128 | ||
129 | This downloads the object ``perl_poetry.pdf`` and saves it in | |
130 | ``/home/larry/documents/`` | |
131 | ||
132 | .. code-block:: perl | |
133 | ||
134 | $bucket->get_key_filename('perl_poetry.pdf', undef, | |
135 | '/home/larry/documents/perl_poetry.pdf'); | |
136 | ||
137 | ||
138 | Delete an Object | |
139 | ---------------- | |
140 | ||
141 | This deletes the object ``goodbye.txt`` | |
142 | ||
143 | .. code-block:: perl | |
144 | ||
145 | $bucket->delete_key('goodbye.txt'); | |
146 | ||
147 | Generate Object Download URLs (signed and unsigned) | |
148 | --------------------------------------------------- | |
149 | This generates an unsigned download URL for ``hello.txt``. This works | |
150 | because we made ``hello.txt`` public by setting the ACL above. | |
151 | Then this generates a signed download URL for ``secret_plans.txt`` that | |
152 | will work for 1 hour. Signed download URLs will work for the time | |
153 | period even if the object is private (when the time period is up, the | |
154 | URL will stop working). | |
155 | ||
156 | .. note:: | |
157 | The `Amazon::S3`_ module does not have a way to generate download | |
c07f9fc5 | 158 | URLs, so we are going to be using another module instead. Unfortunately, |
7c673cae | 159 | most modules for generating these URLs assume that you are using Amazon, |
c07f9fc5 | 160 | so we have had to go with using a more obscure module, `Muck::FS::S3`_. This |
7c673cae FG |
161 | should be the same as Amazon's sample S3 perl module, but this sample |
162 | module is not in CPAN. So, you can either use CPAN to install | |
163 | `Muck::FS::S3`_, or install Amazon's sample S3 module manually. If you go | |
164 | the manual route, you can remove ``Muck::FS::`` from the example below. | |
165 | ||
166 | .. code-block:: perl | |
167 | ||
168 | use Muck::FS::S3::QueryStringAuthGenerator; | |
169 | my $generator = Muck::FS::S3::QueryStringAuthGenerator->new( | |
170 | $access_key, | |
171 | $secret_key, | |
172 | 0, # 0 means use 'http'. set this to 1 for 'https' | |
173 | 'objects.dreamhost.com', | |
174 | ); | |
175 | ||
176 | my $hello_url = $generator->make_bare_url($bucket->bucket, 'hello.txt'); | |
177 | print $hello_url . "\n"; | |
178 | ||
179 | $generator->expires_in(3600); # 1 hour = 3600 seconds | |
180 | my $plans_url = $generator->get($bucket->bucket, 'secret_plans.txt'); | |
181 | print $plans_url . "\n"; | |
182 | ||
183 | The output will look something like this:: | |
184 | ||
185 | http://objects.dreamhost.com:80/my-bucket-name/hello.txt | |
186 | http://objects.dreamhost.com:80/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX | |
187 | ||
188 | ||
189 | .. _`Amazon::S3`: http://search.cpan.org/~tima/Amazon-S3-0.441/lib/Amazon/S3.pm | |
190 | .. _`Amazon::S3::Bucket`: http://search.cpan.org/~tima/Amazon-S3-0.441/lib/Amazon/S3/Bucket.pm | |
191 | .. _`Muck::FS::S3`: http://search.cpan.org/~mike/Muck-0.02/ | |
192 |