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.91
10
12 use Net::Amazon::S3;
13 use Net::Amazon::S3::Authorization::Basic;
14 use Net::Amazon::S3::Authorization::IAM;
15 my $aws_access_key_id = 'fill me in';
16 my $aws_secret_access_key = 'fill me in too';
17 my $s3 = Net::Amazon::S3->new (
19 authorization_context => Net::Amazon::S3::Authorization::Basic->new (
20 aws_access_key_id => $aws_access_key_id,
21 aws_secret_access_key => $aws_secret_access_key,
22 ),
23 retry => 1,
24 );
25 # or use an IAM role.
27 my $s3 = Net::Amazon::S3->new (
28 authorization_context => Net::Amazon::S3::Authorization::IAM->new (
29 aws_access_key_id => $aws_access_key_id,
30 aws_secret_access_key => $aws_secret_access_key,
31 ),
32 retry => 1,
33 );
34 # a bucket is a globally-unique directory
36 # list all buckets that i own
37 my $response = $s3->buckets;
38 foreach my $bucket ( @{ $response->{buckets} } ) {
39 print "You have a bucket: " . $bucket->bucket . "\n";
40 }
41 # create a new bucket
43 my $bucketname = 'acmes_photo_backups';
44 my $bucket = $s3->add_bucket( { bucket => $bucketname } )
45 or die $s3->err . ": " . $s3->errstr;
46 # or use an existing bucket
48 $bucket = $s3->bucket($bucketname);
49 # store a file in the bucket
51 $bucket->add_key_filename( '1.JPG', 'DSC06256.JPG',
52 { content_type => 'image/jpeg', },
53 ) or die $s3->err . ": " . $s3->errstr;
54 # store a value in the bucket
56 $bucket->add_key( 'reminder.txt', 'this is where my photos are backed up' )
57 or die $s3->err . ": " . $s3->errstr;
58 # list files in the bucket
60 $response = $bucket->list_all
61 or die $s3->err . ": " . $s3->errstr;
62 foreach my $key ( @{ $response->{keys} } ) {
63 my $key_name = $key->{key};
64 my $key_size = $key->{size};
65 print "Bucket contains key '$key_name' of size $key_size\n";
66 }
67 # fetch file from the bucket
69 $response = $bucket->get_key_filename( '1.JPG', 'GET', 'backup.jpg' )
70 or die $s3->err . ": " . $s3->errstr;
71 # fetch value from the bucket
73 $response = $bucket->get_key('reminder.txt')
74 or die $s3->err . ": " . $s3->errstr;
75 print "reminder.txt:\n";
76 print " content length: " . $response->{content_length} . "\n";
77 print " content type: " . $response->{content_type} . "\n";
78 print " etag: " . $response->{content_type} . "\n";
79 print " content: " . $response->{value} . "\n";
80 # delete keys
82 $bucket->delete_key('reminder.txt') or die $s3->err . ": " . $s3->errstr;
83 $bucket->delete_key('1.JPG') or die $s3->err . ": " . $s3->errstr;
84 # and finally delete the bucket
86 $bucket->delete_bucket or die $s3->err . ": " . $s3->errstr;
87
89 This module provides a Perlish interface to Amazon S3. From the
90 developer blurb: "Amazon S3 is storage for the Internet. It is designed
91 to make web-scale computing easier for developers. Amazon S3 provides a
92 simple web services interface that can be used to store and retrieve
93 any amount of data, at any time, from anywhere on the web. It gives any
94 developer access to the same highly scalable, reliable, fast,
95 inexpensive data storage infrastructure that Amazon uses to run its own
96 global network of web sites. The service aims to maximize benefits of
97 scale and to pass those benefits on to developers".
98 To find out more about S3, please visit: http://s3.amazonaws.com/
100 To use this module you will need to sign up to Amazon Web Services and
102 provide an "Access Key ID" and " Secret Access Key". If you use this
103 module, you will incurr costs as specified by Amazon. Please check the
104 costs. If you use this module with your Access Key ID and Secret Access
105 Key you must be responsible for these costs.
106 I highly recommend reading all about S3, but in a nutshell data is
108 stored in values. Values are referenced by keys, and keys are stored in
109 buckets. Bucket names are global.
110 Note: This is the legacy interface, please check out
112 Net::Amazon::S3::Client instead.
113 Development of this code happens here:
115 https://github.com/rustyconover/net-amazon-s3
116
118 new
119 Create a new S3 client object. Takes some arguments:
120 authorization_context
122 Class that provides authorization informations.
123 See one of available implementations for more
125 Net::Amazon::S3::Authorization::Basic
127 Net::Amazon::S3::Authorization::IAM
128 vendor
129 Instance of Net::Amazon::S3::Vendor holding vendor specific
130 deviations.
131 S3 became widely used object storage protocol with many vendors
133 providing different feature sets and different compatibility level.
134 One common difference is bucket's HEAD request to determine its
136 region.
137 To maintain currently known differences along with any differencies
139 that may rise in feature it's better to hold vendor specification
140 in dedicated classes. This also allows users to build their own
141 fine-tuned vendor classes.
142 Net::Amazon::S3::Vendor::Amazon
144 Net::Amazon::S3::Vendor::Generic
145 aws_access_key_id
146 Deprecated.
147 When used it's used to create authorization context.
149 Use your Access Key ID as the value of the AWSAccessKeyId parameter
151 in requests you send to Amazon Web Services (when required). Your
152 Access Key ID identifies you as the party responsible for the
153 request.
154 aws_secret_access_key
156 Deprecated.
157 When used it's used to create authorization context.
159 Since your Access Key ID is not encrypted in requests to AWS, it
161 could be discovered and used by anyone. Services that are not free
162 require you to provide additional information, a request signature,
163 to verify that a request containing your unique Access Key ID could
164 only have come from you.
165 DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE.
167 YOU'LL BE SORRY
168 aws_session_token
170 Deprecated.
171 When used it's used to create authorization context.
173 If you are using temporary credentials provided by the AWS Security
175 Token Service, set the token here, and it will be added to the
176 request in order to authenticate it.
177 use_iam_role
179 Deprecated.
180 When used it's used to create authorization context.
182 If you'd like to use IAM provided temporary credentials, pass this
184 option with a true value.
185 secure
187 Deprecated.
188 Set this to 0 if you don't want to use SSL-encrypted connections
190 when talking to S3. Defaults to 1.
191 To use SSL-encrypted connections, LWP::Protocol::https is required.
193 See #vendor and Net::Amazon::S3::Vendor.
195 keep_alive_cache_size
197 Set this to 0 to disable Keep-Alives. Default is 10.
198 timeout
200 How many seconds should your script wait before bailing on a
201 request to S3? Defaults to 30.
202 retry
204 If this library should retry upon errors. This option is
205 recommended. This uses exponential backoff with retries after 1,
206 2, 4, 8, 16, 32 seconds, as recommended by Amazon. Defaults to off.
207 host
209 Deprecated.
210 The S3 host endpoint to use. Defaults to 's3.amazonaws.com'. This
212 allows you to connect to any S3-compatible host.
213 See #vendor and Net::Amazon::S3::Vendor.
215 use_virtual_host
217 Deprecated.
218 Use the virtual host method ('bucketname.s3.amazonaws.com') instead
220 of specifying the bucket at the first part of the path. This is
221 particularly useful if you want to access buckets not located in
222 the US-Standard region (such as EU, Asia Pacific or South America).
223 See
224 <http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html>
225 for the pros and cons.
226 See #vendor and Net::Amazon::S3::Vendor.
228 authorization_method
230 Deprecated.
231 Authorization implementation package name.
233 This library provides Net::Amazon::S3::Signature::V2 and
235 Net::Amazon::S3::Signature::V4
236 Default is Signature 4 if host is "s3.amazonaws.com", Signature 2
238 otherwise
239 See #vendor and Net::Amazon::S3::Vendor.
241 Notes
243 When using Net::Amazon::S3 in child processes using fork (such as in
245 combination with the excellent Parallel::ForkManager) you should create
246 the S3 object in each child, use a fresh LWP::UserAgent in each child,
247 or disable the LWP::ConnCache in the parent:
248 $s3->ua( LWP::UserAgent->new(
250 keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] );
251 buckets
253 Returns undef on error, else hashref of results
254 add_bucket
256 Takes a hashref:
257 bucket
259 The name of the bucket you want to add
260 acl_short (optional)
262 See the set_acl subroutine for documentation on the acl_short
263 options
264 location_constraint (option)
266 Sets the location constraint of the new bucket. If left
267 unspecified, the default S3 datacenter location will be used.
268 Otherwise, you can set it to 'EU' for a European data center - note
269 that costs are different.
270 Returns 0 on failure, Net::Amazon::S3::Bucket object on success
272 bucket BUCKET
274 Takes a scalar argument, the name of the bucket you're creating
275 Returns an (unverified) bucket object from an account. Does no network
277 access.
278 delete_bucket
280 Takes either a Net::Amazon::S3::Bucket object or a hashref containing
281 bucket
283 The name of the bucket to remove
284 Returns false (and fails) if the bucket isn't empty.
286 Returns true if the bucket is successfully deleted.
288 list_bucket
290 List all keys in this bucket.
291 Takes a hashref of arguments:
293 MANDATORY
295 bucket
297 The name of the bucket you want to list keys on
298 OPTIONAL
300 prefix
302 Restricts the response to only contain results that begin with the
303 specified prefix. If you omit this optional argument, the value of
304 prefix for your query will be the empty string. In other words, the
305 results will be not be restricted by prefix.
306 delimiter
308 If this optional, Unicode string parameter is included with your
309 request, then keys that contain the same string between the prefix
310 and the first occurrence of the delimiter will be rolled up into a
311 single result element in the CommonPrefixes collection. These
312 rolled-up keys are not returned elsewhere in the response. For
313 example, with prefix="USA/" and delimiter="/", the matching keys
314 "USA/Oregon/Salem" and "USA/Oregon/Portland" would be summarized in
315 the response as a single "USA/Oregon" element in the CommonPrefixes
316 collection. If an otherwise matching key does not contain the
317 delimiter after the prefix, it appears in the Contents collection.
318 Each element in the CommonPrefixes collection counts as one against
320 the MaxKeys limit. The rolled-up keys represented by each
321 CommonPrefixes element do not. If the Delimiter parameter is not
322 present in your request, keys in the result set will not be rolled-
323 up and neither the CommonPrefixes collection nor the NextMarker
324 element will be present in the response.
325 max-keys
327 This optional argument limits the number of results returned in
328 response to your query. Amazon S3 will return no more than this
329 number of results, but possibly less. Even if max-keys is not
330 specified, Amazon S3 will limit the number of results in the
331 response. Check the IsTruncated flag to see if your results are
332 incomplete. If so, use the Marker parameter to request the next
333 page of results. For the purpose of counting max-keys, a 'result'
334 is either a key in the 'Contents' collection, or a delimited prefix
335 in the 'CommonPrefixes' collection. So for delimiter requests, max-
336 keys limits the total number of list results, not just the number
337 of keys.
338 marker
340 This optional parameter enables pagination of large result sets.
341 "marker" specifies where in the result set to resume listing. It
342 restricts the response to only contain results that occur
343 alphabetically after the value of marker. To retrieve the next page
344 of results, use the last key from the current page of results as
345 the marker in your next request.
346 See also "next_marker", below.
348 If "marker" is omitted,the first page of results is returned.
350 Returns undef on error and a hashref of data on success:
352 The hashref looks like this:
354 {
356 bucket => $bucket_name,
357 prefix => $bucket_prefix,
358 common_prefixes => [$prefix1,$prefix2,...]
359 marker => $bucket_marker,
360 next_marker => $bucket_next_available_marker,
361 max_keys => $bucket_max_keys,
362 is_truncated => $bucket_is_truncated_boolean
363 keys => [$key1,$key2,...]
364 }
365 Explanation of bits of that:
367 common_prefixes
369 If list_bucket was requested with a delimiter, common_prefixes will
370 contain a list of prefixes matching that delimiter. Drill down
371 into these prefixes by making another request with the prefix
372 parameter.
373 is_truncated
375 B flag that indicates whether or not all results of your query were
376 returned in this response. If your results were truncated, you can
377 make a follow-up paginated request using the Marker parameter to
378 retrieve the rest of the results.
379 next_marker
381 A convenience element, useful when paginating with delimiters. The
382 value of "next_marker", if present, is the largest (alphabetically)
383 of all key names and all CommonPrefixes prefixes in the response.
384 If the "is_truncated" flag is set, request the next page of results
385 by setting "marker" to the value of "next_marker". This element is
386 only present in the response if the "delimiter" parameter was sent
387 with the request.
388 Each key is a hashref that looks like this:
390 {
392 key => $key,
393 last_modified => $last_mod_date,
394 etag => $etag, # An MD5 sum of the stored content.
395 size => $size, # Bytes
396 storage_class => $storage_class # Doc?
397 owner_id => $owner_id,
398 owner_displayname => $owner_name
399 }
400 list_bucket_all
402 List all keys in this bucket without having to worry about 'marker'.
403 This is a convenience method, but may make multiple requests to S3
404 under the hood.
405 Takes the same arguments as list_bucket.
407 add_key
409 DEPRECATED. DO NOT USE
410 get_key
412 DEPRECATED. DO NOT USE
413 head_key
415 DEPRECATED. DO NOT USE
416 delete_key
418 DEPRECATED. DO NOT USE
419
421 This module contains code modified from Amazon that contains the
422 following notice:
423 # This software code is made available "AS IS" without warranties of any
425 # kind. You may copy, display, modify and redistribute the software
426 # code either by itself or as incorporated into your code; provided that
427 # you do not remove any proprietary notices. Your use of this software
428 # code is at your own risk and you waive any claim against Amazon
429 # Digital Services, Inc. or its affiliates with respect to your use of
430 # this software code. (c) 2006 Amazon Digital Services, Inc. or its
431 # affiliates.
432
434 Testing S3 is a tricky thing. Amazon wants to charge you a bit of money
435 each time you use their service. And yes, testing counts as using.
436 Because of this, the application's test suite skips anything
437 approaching a real test unless you set these three environment
438 variables:
439 AMAZON_S3_EXPENSIVE_TESTS
441 Doesn't matter what you set it to. Just has to be set
442 AWS_ACCESS_KEY_ID
444 Your AWS access key
445 AWS_ACCESS_KEY_SECRET
447 Your AWS sekkr1t passkey. Be forewarned that setting this
448 environment variable on a shared system might leak that information
449 to another user. Be careful.
450
452 Leon Brocard <acme@astray.com> and unknown Amazon Digital Services
453 programmers.
454 Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
456 Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54
458
460 Net::Amazon::S3::Bucket
461
463 Leo Lapworth <llap@cpan.org>
464
466 This software is copyright (c) 2020 by Amazon Digital Services, Leon
467 Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
468 This is free software; you can redistribute it and/or modify it under
470 the same terms as the Perl 5 programming language system itself.
471perl v5.32.0 2020-08-20 Net::Amazon::S3(3)