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.84
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 timeout
144 How many seconds should your script wait before bailing on a
145 request to S3? Defaults to 30.
146 retry
148 If this library should retry upon errors. This option is
149 recommended. This uses exponential backoff with retries after 1,
150 2, 4, 8, 16, 32 seconds, as recommended by Amazon. Defaults to off.
151 host
153 The S3 host endpoint to use. Defaults to 's3.amazonaws.com'. This
154 allows you to connect to any S3-compatible host.
155 use_virtual_host
157 Use the virtual host method ('bucketname.s3.amazonaws.com') instead
158 of specifying the bucket at the first part of the path. This is
159 particularily useful if you want to access buckets not located in
160 the US-Standard region (such as EU, Asia Pacific or South America).
161 See
162 <http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html>
163 for the pros and cons.
164 authorization_method
166 Authorization implementation package name.
167 This library provides Net::Amazon::S3::Signature::V2 and
169 Net::Amazon::S3::Signature::V4
170 Default is Signature 4 if host is "s3.amazonaws.com", Signature 2
172 otherwise
173 Notes
175 When using Net::Amazon::S3 in child processes using fork (such as in
177 combination with the excellent Parallel::ForkManager) you should create
178 the S3 object in each child, use a fresh LWP::UserAgent in each child,
179 or disable the LWP::ConnCache in the parent:
180 $s3->ua( LWP::UserAgent->new(
182 keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] );
183 buckets
185 Returns undef on error, else hashref of results
186 add_bucket
188 Takes a hashref:
189 bucket
191 The name of the bucket you want to add
192 acl_short (optional)
194 See the set_acl subroutine for documenation on the acl_short
195 options
196 location_constraint (option)
198 Sets the location constraint of the new bucket. If left
199 unspecified, the default S3 datacenter location will be used.
200 Otherwise, you can set it to 'EU' for a European data center - note
201 that costs are different.
202 Returns 0 on failure, Net::Amazon::S3::Bucket object on success
204 bucket BUCKET
206 Takes a scalar argument, the name of the bucket you're creating
207 Returns an (unverified) bucket object from an account. Does no network
209 access.
210 delete_bucket
212 Takes either a Net::Amazon::S3::Bucket object or a hashref containing
213 bucket
215 The name of the bucket to remove
216 Returns false (and fails) if the bucket isn't empty.
218 Returns true if the bucket is successfully deleted.
220 list_bucket
222 List all keys in this bucket.
223 Takes a hashref of arguments:
225 MANDATORY
227 bucket
229 The name of the bucket you want to list keys on
230 OPTIONAL
232 prefix
234 Restricts the response to only contain results that begin with the
235 specified prefix. If you omit this optional argument, the value of
236 prefix for your query will be the empty string. In other words, the
237 results will be not be restricted by prefix.
238 delimiter
240 If this optional, Unicode string parameter is included with your
241 request, then keys that contain the same string between the prefix
242 and the first occurrence of the delimiter will be rolled up into a
243 single result element in the CommonPrefixes collection. These
244 rolled-up keys are not returned elsewhere in the response. For
245 example, with prefix="USA/" and delimiter="/", the matching keys
246 "USA/Oregon/Salem" and "USA/Oregon/Portland" would be summarized in
247 the response as a single "USA/Oregon" element in the CommonPrefixes
248 collection. If an otherwise matching key does not contain the
249 delimiter after the prefix, it appears in the Contents collection.
250 Each element in the CommonPrefixes collection counts as one against
252 the MaxKeys limit. The rolled-up keys represented by each
253 CommonPrefixes element do not. If the Delimiter parameter is not
254 present in your request, keys in the result set will not be rolled-
255 up and neither the CommonPrefixes collection nor the NextMarker
256 element will be present in the response.
257 max-keys
259 This optional argument limits the number of results returned in
260 response to your query. Amazon S3 will return no more than this
261 number of results, but possibly less. Even if max-keys is not
262 specified, Amazon S3 will limit the number of results in the
263 response. Check the IsTruncated flag to see if your results are
264 incomplete. If so, use the Marker parameter to request the next
265 page of results. For the purpose of counting max-keys, a 'result'
266 is either a key in the 'Contents' collection, or a delimited prefix
267 in the 'CommonPrefixes' collection. So for delimiter requests, max-
268 keys limits the total number of list results, not just the number
269 of keys.
270 marker
272 This optional parameter enables pagination of large result sets.
273 "marker" specifies where in the result set to resume listing. It
274 restricts the response to only contain results that occur
275 alphabetically after the value of marker. To retrieve the next page
276 of results, use the last key from the current page of results as
277 the marker in your next request.
278 See also "next_marker", below.
280 If "marker" is omitted,the first page of results is returned.
282 Returns undef on error and a hashref of data on success:
284 The hashref looks like this:
286 {
288 bucket => $bucket_name,
289 prefix => $bucket_prefix,
290 common_prefixes => [$prefix1,$prefix2,...]
291 marker => $bucket_marker,
292 next_marker => $bucket_next_available_marker,
293 max_keys => $bucket_max_keys,
294 is_truncated => $bucket_is_truncated_boolean
295 keys => [$key1,$key2,...]
296 }
297 Explanation of bits of that:
299 common_prefixes
301 If list_bucket was requested with a delimiter, common_prefixes will
302 contain a list of prefixes matching that delimiter. Drill down
303 into these prefixes by making another request with the prefix
304 parameter.
305 is_truncated
307 B flag that indicates whether or not all results of your query were
308 returned in this response. If your results were truncated, you can
309 make a follow-up paginated request using the Marker parameter to
310 retrieve the rest of the results.
311 next_marker
313 A convenience element, useful when paginating with delimiters. The
314 value of "next_marker", if present, is the largest (alphabetically)
315 of all key names and all CommonPrefixes prefixes in the response.
316 If the "is_truncated" flag is set, request the next page of results
317 by setting "marker" to the value of "next_marker". This element is
318 only present in the response if the "delimiter" parameter was sent
319 with the request.
320 Each key is a hashref that looks like this:
322 {
324 key => $key,
325 last_modified => $last_mod_date,
326 etag => $etag, # An MD5 sum of the stored content.
327 size => $size, # Bytes
328 storage_class => $storage_class # Doc?
329 owner_id => $owner_id,
330 owner_displayname => $owner_name
331 }
332 list_bucket_all
334 List all keys in this bucket without having to worry about 'marker'.
335 This is a convenience method, but may make multiple requests to S3
336 under the hood.
337 Takes the same arguments as list_bucket.
339 add_key
341 DEPRECATED. DO NOT USE
342 get_key
344 DEPRECATED. DO NOT USE
345 head_key
347 DEPRECATED. DO NOT USE
348 delete_key
350 DEPRECATED. DO NOT USE
351
353 This module contains code modified from Amazon that contains the
354 following notice:
355 # This software code is made available "AS IS" without warranties of any
357 # kind. You may copy, display, modify and redistribute the software
358 # code either by itself or as incorporated into your code; provided that
359 # you do not remove any proprietary notices. Your use of this software
360 # code is at your own risk and you waive any claim against Amazon
361 # Digital Services, Inc. or its affiliates with respect to your use of
362 # this software code. (c) 2006 Amazon Digital Services, Inc. or its
363 # affiliates.
364
366 Testing S3 is a tricky thing. Amazon wants to charge you a bit of money
367 each time you use their service. And yes, testing counts as using.
368 Because of this, the application's test suite skips anything
369 approaching a real test unless you set these three environment
370 variables:
371 AMAZON_S3_EXPENSIVE_TESTS
373 Doesn't matter what you set it to. Just has to be set
374 AWS_ACCESS_KEY_ID
376 Your AWS access key
377 AWS_ACCESS_KEY_SECRET
379 Your AWS sekkr1t passkey. Be forewarned that setting this
380 environment variable on a shared system might leak that information
381 to another user. Be careful.
382
384 Leon Brocard <acme@astray.com> and unknown Amazon Digital Services
385 programmers.
386 Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
388 Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54
390
392 Net::Amazon::S3::Bucket
393
395 Leo Lapworth <llap@cpan.org>
396
398 This software is copyright (c) 2018 by Amazon Digital Services, Leon
399 Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
400 This is free software; you can redistribute it and/or modify it under
402 the same terms as the Perl 5 programming language system itself.
403perl v5.28.0 2018-11-12 Net::Amazon::S3(3)