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 version 0.86
10
12 use Net::Amazon::S3;
13 my $aws_access_key_id = 'fill me in';
14 my $aws_secret_access_key = 'fill me in too';
15 my $s3 = Net::Amazon::S3->new(
17 { aws_access_key_id => $aws_access_key_id,
18 aws_secret_access_key => $aws_secret_access_key,
19 # or use an IAM role.
20 use_iam_role => 1
21 retry => 1,
23 }
24 );
25 # a bucket is a globally-unique directory
27 # list all buckets that i own
28 my $response = $s3->buckets;
29 foreach my $bucket ( @{ $response->{buckets} } ) {
30 print "You have a bucket: " . $bucket->bucket . "\n";
31 }
32 # create a new bucket
34 my $bucketname = 'acmes_photo_backups';
35 my $bucket = $s3->add_bucket( { bucket => $bucketname } )
36 or die $s3->err . ": " . $s3->errstr;
37 # or use an existing bucket
39 $bucket = $s3->bucket($bucketname);
40 # store a file in the bucket
42 $bucket->add_key_filename( '1.JPG', 'DSC06256.JPG',
43 { content_type => 'image/jpeg', },
44 ) or die $s3->err . ": " . $s3->errstr;
45 # store a value in the bucket
47 $bucket->add_key( 'reminder.txt', 'this is where my photos are backed up' )
48 or die $s3->err . ": " . $s3->errstr;
49 # list files in the bucket
51 $response = $bucket->list_all
52 or die $s3->err . ": " . $s3->errstr;
53 foreach my $key ( @{ $response->{keys} } ) {
54 my $key_name = $key->{key};
55 my $key_size = $key->{size};
56 print "Bucket contains key '$key_name' of size $key_size\n";
57 }
58 # fetch file from the bucket
60 $response = $bucket->get_key_filename( '1.JPG', 'GET', 'backup.jpg' )
61 or die $s3->err . ": " . $s3->errstr;
62 # fetch value from the bucket
64 $response = $bucket->get_key('reminder.txt')
65 or die $s3->err . ": " . $s3->errstr;
66 print "reminder.txt:\n";
67 print " content length: " . $response->{content_length} . "\n";
68 print " content type: " . $response->{content_type} . "\n";
69 print " etag: " . $response->{content_type} . "\n";
70 print " content: " . $response->{value} . "\n";
71 # delete keys
73 $bucket->delete_key('reminder.txt') or die $s3->err . ": " . $s3->errstr;
74 $bucket->delete_key('1.JPG') or die $s3->err . ": " . $s3->errstr;
75 # and finally delete the bucket
77 $bucket->delete_bucket or die $s3->err . ": " . $s3->errstr;
78
80 This module provides a Perlish interface to Amazon S3. From the
81 developer blurb: "Amazon S3 is storage for the Internet. It is designed
82 to make web-scale computing easier for developers. Amazon S3 provides a
83 simple web services interface that can be used to store and retrieve
84 any amount of data, at any time, from anywhere on the web. It gives any
85 developer access to the same highly scalable, reliable, fast,
86 inexpensive data storage infrastructure that Amazon uses to run its own
87 global network of web sites. The service aims to maximize benefits of
88 scale and to pass those benefits on to developers".
89 To find out more about S3, please visit: http://s3.amazonaws.com/
91 To use this module you will need to sign up to Amazon Web Services and
93 provide an "Access Key ID" and " Secret Access Key". If you use this
94 module, you will incurr costs as specified by Amazon. Please check the
95 costs. If you use this module with your Access Key ID and Secret Access
96 Key you must be responsible for these costs.
97 I highly recommend reading all about S3, but in a nutshell data is
99 stored in values. Values are referenced by keys, and keys are stored in
100 buckets. Bucket names are global.
101 Note: This is the legacy interface, please check out
103 Net::Amazon::S3::Client instead.
104 Development of this code happens here:
106 https://github.com/rustyconover/net-amazon-s3
107
109 new
110 Create a new S3 client object. Takes some arguments:
111 aws_access_key_id
113 Use your Access Key ID as the value of the AWSAccessKeyId parameter
114 in requests you send to Amazon Web Services (when required). Your
115 Access Key ID identifies you as the party responsible for the
116 request.
117 aws_secret_access_key
119 Since your Access Key ID is not encrypted in requests to AWS, it
120 could be discovered and used by anyone. Services that are not free
121 require you to provide additional information, a request signature,
122 to verify that a request containing your unique Access Key ID could
123 only have come from you.
124 DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE.
126 YOU'LL BE SORRY
127 aws_session_token
129 If you are using temporary credentials provided by the AWS Security
130 Token Service, set the token here, and it will be added to the
131 request in order to authenticate it.
132 use_iam_role
134 If you'd like to use IAM provided temporary credentials, pass this
135 option with a true value.
136 secure
138 Set this to 0 if you don't want to use SSL-encrypted connections
139 when talking to S3. Defaults to 1.
140 To use SSL-encrypted connections, LWP::Protocol::https is required.
142 keep_alive_cache_size
144 Set this to 0 to disable Keep-Alives. Default is 10.
145 timeout
147 How many seconds should your script wait before bailing on a
148 request to S3? Defaults to 30.
149 retry
151 If this library should retry upon errors. This option is
152 recommended. This uses exponential backoff with retries after 1,
153 2, 4, 8, 16, 32 seconds, as recommended by Amazon. Defaults to off.
154 host
156 The S3 host endpoint to use. Defaults to 's3.amazonaws.com'. This
157 allows you to connect to any S3-compatible host.
158 use_virtual_host
160 Use the virtual host method ('bucketname.s3.amazonaws.com') instead
161 of specifying the bucket at the first part of the path. This is
162 particularly useful if you want to access buckets not located in
163 the US-Standard region (such as EU, Asia Pacific or South America).
164 See
165 <http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html>
166 for the pros and cons.
167 authorization_method
169 Authorization implementation package name.
170 This library provides Net::Amazon::S3::Signature::V2 and
172 Net::Amazon::S3::Signature::V4
173 Default is Signature 4 if host is "s3.amazonaws.com", Signature 2
175 otherwise
176 Notes
178 When using Net::Amazon::S3 in child processes using fork (such as in
180 combination with the excellent Parallel::ForkManager) you should create
181 the S3 object in each child, use a fresh LWP::UserAgent in each child,
182 or disable the LWP::ConnCache in the parent:
183 $s3->ua( LWP::UserAgent->new(
185 keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] );
186 buckets
188 Returns undef on error, else hashref of results
189 add_bucket
191 Takes a hashref:
192 bucket
194 The name of the bucket you want to add
195 acl_short (optional)
197 See the set_acl subroutine for documentation on the acl_short
198 options
199 location_constraint (option)
201 Sets the location constraint of the new bucket. If left
202 unspecified, the default S3 datacenter location will be used.
203 Otherwise, you can set it to 'EU' for a European data center - note
204 that costs are different.
205 Returns 0 on failure, Net::Amazon::S3::Bucket object on success
207 bucket BUCKET
209 Takes a scalar argument, the name of the bucket you're creating
210 Returns an (unverified) bucket object from an account. Does no network
212 access.
213 delete_bucket
215 Takes either a Net::Amazon::S3::Bucket object or a hashref containing
216 bucket
218 The name of the bucket to remove
219 Returns false (and fails) if the bucket isn't empty.
221 Returns true if the bucket is successfully deleted.
223 list_bucket
225 List all keys in this bucket.
226 Takes a hashref of arguments:
228 MANDATORY
230 bucket
232 The name of the bucket you want to list keys on
233 OPTIONAL
235 prefix
237 Restricts the response to only contain results that begin with the
238 specified prefix. If you omit this optional argument, the value of
239 prefix for your query will be the empty string. In other words, the
240 results will be not be restricted by prefix.
241 delimiter
243 If this optional, Unicode string parameter is included with your
244 request, then keys that contain the same string between the prefix
245 and the first occurrence of the delimiter will be rolled up into a
246 single result element in the CommonPrefixes collection. These
247 rolled-up keys are not returned elsewhere in the response. For
248 example, with prefix="USA/" and delimiter="/", the matching keys
249 "USA/Oregon/Salem" and "USA/Oregon/Portland" would be summarized in
250 the response as a single "USA/Oregon" element in the CommonPrefixes
251 collection. If an otherwise matching key does not contain the
252 delimiter after the prefix, it appears in the Contents collection.
253 Each element in the CommonPrefixes collection counts as one against
255 the MaxKeys limit. The rolled-up keys represented by each
256 CommonPrefixes element do not. If the Delimiter parameter is not
257 present in your request, keys in the result set will not be rolled-
258 up and neither the CommonPrefixes collection nor the NextMarker
259 element will be present in the response.
260 max-keys
262 This optional argument limits the number of results returned in
263 response to your query. Amazon S3 will return no more than this
264 number of results, but possibly less. Even if max-keys is not
265 specified, Amazon S3 will limit the number of results in the
266 response. Check the IsTruncated flag to see if your results are
267 incomplete. If so, use the Marker parameter to request the next
268 page of results. For the purpose of counting max-keys, a 'result'
269 is either a key in the 'Contents' collection, or a delimited prefix
270 in the 'CommonPrefixes' collection. So for delimiter requests, max-
271 keys limits the total number of list results, not just the number
272 of keys.
273 marker
275 This optional parameter enables pagination of large result sets.
276 "marker" specifies where in the result set to resume listing. It
277 restricts the response to only contain results that occur
278 alphabetically after the value of marker. To retrieve the next page
279 of results, use the last key from the current page of results as
280 the marker in your next request.
281 See also "next_marker", below.
283 If "marker" is omitted,the first page of results is returned.
285 Returns undef on error and a hashref of data on success:
287 The hashref looks like this:
289 {
291 bucket => $bucket_name,
292 prefix => $bucket_prefix,
293 common_prefixes => [$prefix1,$prefix2,...]
294 marker => $bucket_marker,
295 next_marker => $bucket_next_available_marker,
296 max_keys => $bucket_max_keys,
297 is_truncated => $bucket_is_truncated_boolean
298 keys => [$key1,$key2,...]
299 }
300 Explanation of bits of that:
302 common_prefixes
304 If list_bucket was requested with a delimiter, common_prefixes will
305 contain a list of prefixes matching that delimiter. Drill down
306 into these prefixes by making another request with the prefix
307 parameter.
308 is_truncated
310 B flag that indicates whether or not all results of your query were
311 returned in this response. If your results were truncated, you can
312 make a follow-up paginated request using the Marker parameter to
313 retrieve the rest of the results.
314 next_marker
316 A convenience element, useful when paginating with delimiters. The
317 value of "next_marker", if present, is the largest (alphabetically)
318 of all key names and all CommonPrefixes prefixes in the response.
319 If the "is_truncated" flag is set, request the next page of results
320 by setting "marker" to the value of "next_marker". This element is
321 only present in the response if the "delimiter" parameter was sent
322 with the request.
323 Each key is a hashref that looks like this:
325 {
327 key => $key,
328 last_modified => $last_mod_date,
329 etag => $etag, # An MD5 sum of the stored content.
330 size => $size, # Bytes
331 storage_class => $storage_class # Doc?
332 owner_id => $owner_id,
333 owner_displayname => $owner_name
334 }
335 list_bucket_all
337 List all keys in this bucket without having to worry about 'marker'.
338 This is a convenience method, but may make multiple requests to S3
339 under the hood.
340 Takes the same arguments as list_bucket.
342 add_key
344 DEPRECATED. DO NOT USE
345 get_key
347 DEPRECATED. DO NOT USE
348 head_key
350 DEPRECATED. DO NOT USE
351 delete_key
353 DEPRECATED. DO NOT USE
354
356 This module contains code modified from Amazon that contains the
357 following notice:
358 # This software code is made available "AS IS" without warranties of any
360 # kind. You may copy, display, modify and redistribute the software
361 # code either by itself or as incorporated into your code; provided that
362 # you do not remove any proprietary notices. Your use of this software
363 # code is at your own risk and you waive any claim against Amazon
364 # Digital Services, Inc. or its affiliates with respect to your use of
365 # this software code. (c) 2006 Amazon Digital Services, Inc. or its
366 # affiliates.
367
369 Testing S3 is a tricky thing. Amazon wants to charge you a bit of money
370 each time you use their service. And yes, testing counts as using.
371 Because of this, the application's test suite skips anything
372 approaching a real test unless you set these three environment
373 variables:
374 AMAZON_S3_EXPENSIVE_TESTS
376 Doesn't matter what you set it to. Just has to be set
377 AWS_ACCESS_KEY_ID
379 Your AWS access key
380 AWS_ACCESS_KEY_SECRET
382 Your AWS sekkr1t passkey. Be forewarned that setting this
383 environment variable on a shared system might leak that information
384 to another user. Be careful.
385
387 Leon Brocard <acme@astray.com> and unknown Amazon Digital Services
388 programmers.
389 Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
391 Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54
393
395 Net::Amazon::S3::Bucket
396
398 Leo Lapworth <llap@cpan.org>
399
401 This software is copyright (c) 2019 by Amazon Digital Services, Leon
402 Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
403 This is free software; you can redistribute it and/or modify it under
405 the same terms as the Perl 5 programming language system itself.
406perl v5.28.1 2019-04-12 Net::Amazon::S3(3)