1Net::Amazon::S3(3) User Contributed Perl Documentation Net::Amazon::S3(3)
2
6 Net::Amazon::S3 - Use the Amazon S3 - Simple Storage Service
7
9 use Net::Amazon::S3;
10 my $aws_access_key_id = 'fill me in';
11 my $aws_secret_access_key = 'fill me in too';
12 my $s3 = Net::Amazon::S3->new(
14 { aws_access_key_id => $aws_access_key_id,
15 aws_secret_access_key => $aws_secret_access_key,
16 retry => 1,
17 }
18 );
19 # a bucket is a globally-unique directory
21 # list all buckets that i own
22 my $response = $s3->buckets;
23 foreach my $bucket ( @{ $response->{buckets} } ) {
24 print "You have a bucket: " . $bucket->bucket . "\n";
25 }
26 # create a new bucket
28 my $bucketname = 'acmes_photo_backups';
29 my $bucket = $s3->add_bucket( { bucket => $bucketname } )
30 or die $s3->err . ": " . $s3->errstr;
31 # or use an existing bucket
33 $bucket = $s3->bucket($bucketname);
34 # store a file in the bucket
36 $bucket->add_key_filename( '1.JPG', 'DSC06256.JPG',
37 { content_type => 'image/jpeg', },
38 ) or die $s3->err . ": " . $s3->errstr;
39 # store a value in the bucket
41 $bucket->add_key( 'reminder.txt', 'this is where my photos are backed up' )
42 or die $s3->err . ": " . $s3->errstr;
43 # list files in the bucket
45 $response = $bucket->list_all
46 or die $s3->err . ": " . $s3->errstr;
47 foreach my $key ( @{ $response->{keys} } ) {
48 my $key_name = $key->{key};
49 my $key_size = $key->{size};
50 print "Bucket contains key '$key_name' of size $key_size\n";
51 }
52 # fetch file from the bucket
54 $response = $bucket->get_key_filename( '1.JPG', 'GET', 'backup.jpg' )
55 or die $s3->err . ": " . $s3->errstr;
56 # fetch value from the bucket
58 $response = $bucket->get_key('reminder.txt')
59 or die $s3->err . ": " . $s3->errstr;
60 print "reminder.txt:\n";
61 print " content length: " . $response->{content_length} . "\n";
62 print " content type: " . $response->{content_type} . "\n";
63 print " etag: " . $response->{content_type} . "\n";
64 print " content: " . $response->{value} . "\n";
65 # delete keys
67 $bucket->delete_key('reminder.txt') or die $s3->err . ": " . $s3->errstr;
68 $bucket->delete_key('1.JPG') or die $s3->err . ": " . $s3->errstr;
69 # and finally delete the bucket
71 $bucket->delete_bucket or die $s3->err . ": " . $s3->errstr;
72
74 This module provides a Perlish interface to Amazon S3. From the
75 developer blurb: "Amazon S3 is storage for the Internet. It is designed
76 to make web-scale computing easier for developers. Amazon S3 provides a
77 simple web services interface that can be used to store and retrieve
78 any amount of data, at any time, from anywhere on the web. It gives any
79 developer access to the same highly scalable, reliable, fast,
80 inexpensive data storage infrastructure that Amazon uses to run its own
81 global network of web sites. The service aims to maximize benefits of
82 scale and to pass those benefits on to developers".
83 To find out more about S3, please visit: http://s3.amazonaws.com/
85 To use this module you will need to sign up to Amazon Web Services and
87 provide an "Access Key ID" and " Secret Access Key". If you use this
88 module, you will incurr costs as specified by Amazon. Please check the
89 costs. If you use this module with your Access Key ID and Secret Access
90 Key you must be responsible for these costs.
91 I highly recommend reading all about S3, but in a nutshell data is
93 stored in values. Values are referenced by keys, and keys are stored in
94 buckets. Bucket names are global.
95 Note: This is the legacy interface, please check out
97 Net::Amazon::S3::Client instead.
98 Development of this code happens here:
100 http://github.com/acme/net-amazon-s3
101
103 new
104 Create a new S3 client object. Takes some arguments:
105 aws_access_key_id
107 Use your Access Key ID as the value of the AWSAccessKeyId parameter
108 in requests you send to Amazon Web Services (when required). Your
109 Access Key ID identifies you as the party responsible for the
110 request.
111 aws_secret_access_key
113 Since your Access Key ID is not encrypted in requests to AWS, it
114 could be discovered and used by anyone. Services that are not free
115 require you to provide additional information, a request signature,
116 to verify that a request containing your unique Access Key ID could
117 only have come from you.
118 DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE.
120 YOU'LL BE SORRY
121 secure
123 Set this to 1 if you want to use SSL-encrypted connections when
124 talking to S3. Defaults to 0.
125 timeout
127 How many seconds should your script wait before bailing on a
128 request to S3? Defaults to 30.
129 retry
131 If this library should retry upon errors. This option is
132 recommended. This uses exponential backoff with retries after 1,
133 2, 4, 8, 16, 32 seconds, as recommended by Amazon. Defaults to off.
134 buckets
136 Returns undef on error, else hashref of results
137 add_bucket
139 Takes a hashref:
140 bucket
142 The name of the bucket you want to add
143 acl_short (optional)
145 See the set_acl subroutine for documenation on the acl_short
146 options
147 location_constraint (option)
149 Sets the location constraint of the new bucket. If left
150 unspecified, the default S3 datacenter location will be used.
151 Otherwise, you can set it to 'EU' for a European data center - note
152 that costs are different.
153 Returns 0 on failure, Net::Amazon::S3::Bucket object on success
155 bucket BUCKET
157 Takes a scalar argument, the name of the bucket you're creating
158 Returns an (unverified) bucket object from an account. Does no network
160 access.
161 delete_bucket
163 Takes either a Net::Amazon::S3::Bucket object or a hashref containing
164 bucket
166 The name of the bucket to remove
167 Returns false (and fails) if the bucket isn't empty.
169 Returns true if the bucket is successfully deleted.
171 list_bucket
173 List all keys in this bucket.
174 Takes a hashref of arguments:
176 MANDATORY
178 bucket
180 The name of the bucket you want to list keys on
181 OPTIONAL
183 prefix
185 Restricts the response to only contain results that begin with the
186 specified prefix. If you omit this optional argument, the value of
187 prefix for your query will be the empty string. In other words, the
188 results will be not be restricted by prefix.
189 delimiter
191 If this optional, Unicode string parameter is included with your
192 request, then keys that contain the same string between the prefix
193 and the first occurrence of the delimiter will be rolled up into a
194 single result element in the CommonPrefixes collection. These
195 rolled-up keys are not returned elsewhere in the response. For
196 example, with prefix="USA/" and delimiter="/", the matching keys
197 "USA/Oregon/Salem" and "USA/Oregon/Portland" would be summarized in
198 the response as a single "USA/Oregon" element in the CommonPrefixes
199 collection. If an otherwise matching key does not contain the
200 delimiter after the prefix, it appears in the Contents collection.
201 Each element in the CommonPrefixes collection counts as one against
203 the MaxKeys limit. The rolled-up keys represented by each
204 CommonPrefixes element do not. If the Delimiter parameter is not
205 present in your request, keys in the result set will not be rolled-
206 up and neither the CommonPrefixes collection nor the NextMarker
207 element will be present in the response.
208 max-keys
210 This optional argument limits the number of results returned in
211 response to your query. Amazon S3 will return no more than this
212 number of results, but possibly less. Even if max-keys is not
213 specified, Amazon S3 will limit the number of results in the
214 response. Check the IsTruncated flag to see if your results are
215 incomplete. If so, use the Marker parameter to request the next
216 page of results. For the purpose of counting max-keys, a 'result'
217 is either a key in the 'Contents' collection, or a delimited prefix
218 in the 'CommonPrefixes' collection. So for delimiter requests, max-
219 keys limits the total number of list results, not just the number
220 of keys.
221 marker
223 This optional parameter enables pagination of large result sets.
224 "marker" specifies where in the result set to resume listing. It
225 restricts the response to only contain results that occur
226 alphabetically after the value of marker. To retrieve the next page
227 of results, use the last key from the current page of results as
228 the marker in your next request.
229 See also "next_marker", below.
231 If "marker" is omitted,the first page of results is returned.
233 Returns undef on error and a hashref of data on success:
235 The hashref looks like this:
237 {
239 bucket => $bucket_name,
240 prefix => $bucket_prefix,
241 common_prefixes => [$prefix1,$prefix2,...]
242 marker => $bucket_marker,
243 next_marker => $bucket_next_available_marker,
244 max_keys => $bucket_max_keys,
245 is_truncated => $bucket_is_truncated_boolean
246 keys => [$key1,$key2,...]
247 }
248 Explanation of bits of that:
250 common_prefixes
252 If list_bucket was requested with a delimiter, common_prefixes will
253 contain a list of prefixes matching that delimiter. Drill down
254 into these prefixes by making another request with the prefix
255 parameter.
256 is_truncated
258 B flag that indicates whether or not all results of your query were
259 returned in this response. If your results were truncated, you can
260 make a follow-up paginated request using the Marker parameter to
261 retrieve the rest of the results.
262 next_marker
264 A convenience element, useful when paginating with delimiters. The
265 value of "next_marker", if present, is the largest (alphabetically)
266 of all key names and all CommonPrefixes prefixes in the response.
267 If the "is_truncated" flag is set, request the next page of results
268 by setting "marker" to the value of "next_marker". This element is
269 only present in the response if the "delimiter" parameter was sent
270 with the request.
271 Each key is a hashref that looks like this:
273 {
275 key => $key,
276 last_modified => $last_mod_date,
277 etag => $etag, # An MD5 sum of the stored content.
278 size => $size, # Bytes
279 storage_class => $storage_class # Doc?
280 owner_id => $owner_id,
281 owner_displayname => $owner_name
282 }
283 list_bucket_all
285 List all keys in this bucket without having to worry about 'marker'.
286 This is a convenience method, but may make multiple requests to S3
287 under the hood.
288 Takes the same arguments as list_bucket.
290 add_key
292 DEPRECATED. DO NOT USE
293 get_key
295 DEPRECATED. DO NOT USE
296 head_key
298 DEPRECATED. DO NOT USE
299 delete_key
301 DEPRECATED. DO NOT USE
302
304 This module contains code modified from Amazon that contains the
305 following notice:
306 # This software code is made available "AS IS" without warranties of any
308 # kind. You may copy, display, modify and redistribute the software
309 # code either by itself or as incorporated into your code; provided that
310 # you do not remove any proprietary notices. Your use of this software
311 # code is at your own risk and you waive any claim against Amazon
312 # Digital Services, Inc. or its affiliates with respect to your use of
313 # this software code. (c) 2006 Amazon Digital Services, Inc. or its
314 # affiliates.
315
317 Testing S3 is a tricky thing. Amazon wants to charge you a bit of money
318 each time you use their service. And yes, testing counts as using.
319 Because of this, the application's test suite skips anything
320 approaching a real test unless you set these three environment
321 variables:
322 AMAZON_S3_EXPENSIVE_TESTS
324 Doesn't matter what you set it to. Just has to be set
325 AWS_ACCESS_KEY_ID
327 Your AWS access key
328 AWS_ACCESS_KEY_SECRET
330 Your AWS sekkr1t passkey. Be forewarned that setting this
331 environment variable on a shared system might leak that information
332 to another user. Be careful.
333
335 Leon Brocard <acme@astray.com> and unknown Amazon Digital Services
336 programmers.
337 Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
339
341 Net::Amazon::S3::Bucket
342perl v5.12.3 2010-03-30 Net::Amazon::S3(3)