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.99
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 Bucket names with dots, HTTPS, and Signature V4
118 At the moment Amazon S3 doesn't play well with HTTPS and virtual bucket
119 hosts if bucket name contains dots.
120 Due the current implementation of Signature V4 handling you should use
122 workaround consisting of usage of region hostnames
123 my $bucket_region = $global_s3->bucket ($bucket)->_head_region;
125 my $region_s3 = Net::Amazon:S3->new (
127 ...,
128 vendor => Net::Amazon::S3::Vendor::Amazon->new (
129 host => "s3-$bucket_region.amazonaws.com",
130 use_virtual_host => 0,
131 ),
132 );
133 my $bucket = $region_s3->bucket ($bucket);
135 And use bucket instance / region s3 connection.
137
139 new
140 Create a new S3 client object. Takes some arguments:
141 authorization_context
143 Class that provides authorization information.
144 See one of available implementations for more
146 Net::Amazon::S3::Authorization::Basic
148 Net::Amazon::S3::Authorization::IAM
149 vendor
150 Instance of Net::Amazon::S3::Vendor holding vendor specific
151 deviations.
152 S3 became widely used object storage protocol with many vendors
154 providing different feature sets and different compatibility level.
155 One common difference is bucket's HEAD request to determine its
157 region.
158 To maintain currently known differences along with any differencies
160 that may rise in feature it's better to hold vendor specification
161 in dedicated classes. This also allows users to build their own
162 fine-tuned vendor classes.
163 Net::Amazon::S3::Vendor::Amazon
165 Net::Amazon::S3::Vendor::Generic
166 aws_access_key_id
167 Deprecated.
168 When used it's used to create authorization context.
170 Use your Access Key ID as the value of the AWSAccessKeyId parameter
172 in requests you send to Amazon Web Services (when required). Your
173 Access Key ID identifies you as the party responsible for the
174 request.
175 aws_secret_access_key
177 Deprecated.
178 When used it's used to create authorization context.
180 Since your Access Key ID is not encrypted in requests to AWS, it
182 could be discovered and used by anyone. Services that are not free
183 require you to provide additional information, a request signature,
184 to verify that a request containing your unique Access Key ID could
185 only have come from you.
186 DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE.
188 YOU'LL BE SORRY
189 aws_session_token
191 Deprecated.
192 When used it's used to create authorization context.
194 If you are using temporary credentials provided by the AWS Security
196 Token Service, set the token here, and it will be added to the
197 request in order to authenticate it.
198 use_iam_role
200 Deprecated.
201 When used it's used to create authorization context.
203 If you'd like to use IAM provided temporary credentials, pass this
205 option with a true value.
206 secure
208 Deprecated.
209 Set this to 0 if you don't want to use SSL-encrypted connections
211 when talking to S3. Defaults to 1.
212 To use SSL-encrypted connections, LWP::Protocol::https is required.
214 See #vendor and Net::Amazon::S3::Vendor.
216 keep_alive_cache_size
218 Set this to 0 to disable Keep-Alives. Default is 10.
219 timeout
221 How many seconds should your script wait before bailing on a
222 request to S3? Defaults to 30.
223 retry
225 If this library should retry upon errors. This option is
226 recommended. This uses exponential backoff with retries after 1,
227 2, 4, 8, 16, 32 seconds, as recommended by Amazon. Defaults to off.
228 host
230 Deprecated.
231 The S3 host endpoint to use. Defaults to 's3.amazonaws.com'. This
233 allows you to connect to any S3-compatible host.
234 See #vendor and Net::Amazon::S3::Vendor.
236 use_virtual_host
238 Deprecated.
239 Use the virtual host method ('bucketname.s3.amazonaws.com') instead
241 of specifying the bucket at the first part of the path. This is
242 particularly useful if you want to access buckets not located in
243 the US-Standard region (such as EU, Asia Pacific or South America).
244 See
245 <http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html>
246 for the pros and cons.
247 See #vendor and Net::Amazon::S3::Vendor.
249 authorization_method
251 Deprecated.
252 Authorization implementation package name.
254 This library provides Net::Amazon::S3::Signature::V2 and
256 Net::Amazon::S3::Signature::V4
257 Default is Signature 4 if host is "s3.amazonaws.com", Signature 2
259 otherwise
260 See #vendor and Net::Amazon::S3::Vendor.
262 error_handler_class
264 Error handler class name (package name), see
265 Net::Amazon::S3::Error::Handler for more.
266 Default: Net::Amazon::S3::Error::Handler::Legacy
268 error_handler
270 Instance of error handler class.
271 Notes
273 When using Net::Amazon::S3 in child processes using fork (such as in
275 combination with the excellent Parallel::ForkManager) you should create
276 the S3 object in each child, use a fresh LWP::UserAgent in each child,
277 or disable the LWP::ConnCache in the parent:
278 $s3->ua( LWP::UserAgent->new(
280 keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] );
281 buckets
283 Returns undef on error, else hashref of results
284 add_bucket
286 # Create new bucket with default location
287 my $bucket = $s3->add_bucket ('new-bucket');
288 # Create new bucket in another location
290 my $bucket = $s3->add_bucket ('new-bucket', location_constraint => 'eu-west-1');
291 my $bucket = $s3->add_bucket ('new-bucket', { location_constraint => 'eu-west-1' });
292 my $bucket = $s3->add_bucket (bucket => 'new-bucket', location_constraint => 'eu-west-1');
293 my $bucket = $s3->add_bucket ({ bucket => 'new-bucket', location_constraint => 'eu-west-1' });
294 Method creates and returns new bucket.
296 In case of error it reports it and returns "undef" (refer "ERROR
298 HANDLING").
299 Recognized positional arguments (refer "CALLING CONVENTION")
301 bucket
303 Required, recognized as positional.
304 The name of the bucket you want to add.
306 Recognized optional arguments
308 acl
310 acl => 'private'
311 acl => Net::Amazon::S3::ACL::Canned->PRIVATE
312 acl => Net::Amazon::S3::ACL::Set->grant_read (email => 'foo@bar.baz')
313 Available since v0.94
315 Set ACL to the newly created bucket. Refer Net::Amazon::S3::ACL for
317 possibilities.
318 acl_short (deprecated)
320 Deprecated since v0.94
321 When specified its value is used to populate "acl" argument (unless
323 it exists).
324 location_constraint
326 Optional.
327 Sets the location constraint of the new bucket. If left
329 unspecified, the default S3 datacenter location will be used.
330 This library recognizes regions according Amazon S3 documentation
332 → <https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region>
334 → <https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestSyntax>
336 Provides operation CreateBucket
338 <https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html>.
339 bucket BUCKET
341 Takes a scalar argument, the name of the bucket you're creating
342 Returns an (unverified) bucket object from an account. Does no network
344 access.
345 delete_bucket
347 $s3->delete_bucket ($bucket);
348 $s3->delete_bucket (bucket => $bucket);
349 Deletes bucket from account.
351 Returns "true" if the bucket is successfully deleted.
353 Returns "false" and reports an error otherwise (refer "ERROR HANDLING")
355 Positional arguments (refer "CALLING CONVENTION")
357 bucket
359 Required.
360 The name of the bucket or Net::Amazon::S3::Bucket instance you want
362 to delete.
363 Provides operation "DeleteBucket"
365 <https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html>
366 list_bucket
368 List all keys in this bucket.
369 Takes a hashref of arguments:
371 MANDATORY
373 bucket
375 The name of the bucket you want to list keys on
376 OPTIONAL
378 prefix
380 Restricts the response to only contain results that begin with the
381 specified prefix. If you omit this optional argument, the value of
382 prefix for your query will be the empty string. In other words, the
383 results will be not be restricted by prefix.
384 delimiter
386 If this optional, Unicode string parameter is included with your
387 request, then keys that contain the same string between the prefix
388 and the first occurrence of the delimiter will be rolled up into a
389 single result element in the CommonPrefixes collection. These
390 rolled-up keys are not returned elsewhere in the response. For
391 example, with prefix="USA/" and delimiter="/", the matching keys
392 "USA/Oregon/Salem" and "USA/Oregon/Portland" would be summarized in
393 the response as a single "USA/Oregon" element in the CommonPrefixes
394 collection. If an otherwise matching key does not contain the
395 delimiter after the prefix, it appears in the Contents collection.
396 Each element in the CommonPrefixes collection counts as one against
398 the MaxKeys limit. The rolled-up keys represented by each
399 CommonPrefixes element do not. If the Delimiter parameter is not
400 present in your request, keys in the result set will not be rolled-
401 up and neither the CommonPrefixes collection nor the NextMarker
402 element will be present in the response.
403 max-keys
405 This optional argument limits the number of results returned in
406 response to your query. Amazon S3 will return no more than this
407 number of results, but possibly less. Even if max-keys is not
408 specified, Amazon S3 will limit the number of results in the
409 response. Check the IsTruncated flag to see if your results are
410 incomplete. If so, use the Marker parameter to request the next
411 page of results. For the purpose of counting max-keys, a 'result'
412 is either a key in the 'Contents' collection, or a delimited prefix
413 in the 'CommonPrefixes' collection. So for delimiter requests, max-
414 keys limits the total number of list results, not just the number
415 of keys.
416 marker
418 This optional parameter enables pagination of large result sets.
419 "marker" specifies where in the result set to resume listing. It
420 restricts the response to only contain results that occur
421 alphabetically after the value of marker. To retrieve the next page
422 of results, use the last key from the current page of results as
423 the marker in your next request.
424 See also "next_marker", below.
426 If "marker" is omitted,the first page of results is returned.
428 Returns undef on error and a hashref of data on success:
430 The hashref looks like this:
432 {
434 bucket => $bucket_name,
435 prefix => $bucket_prefix,
436 common_prefixes => [$prefix1,$prefix2,...]
437 marker => $bucket_marker,
438 next_marker => $bucket_next_available_marker,
439 max_keys => $bucket_max_keys,
440 is_truncated => $bucket_is_truncated_boolean
441 keys => [$key1,$key2,...]
442 }
443 Explanation of bits of that:
445 common_prefixes
447 If list_bucket was requested with a delimiter, common_prefixes will
448 contain a list of prefixes matching that delimiter. Drill down
449 into these prefixes by making another request with the prefix
450 parameter.
451 is_truncated
453 B flag that indicates whether or not all results of your query were
454 returned in this response. If your results were truncated, you can
455 make a follow-up paginated request using the Marker parameter to
456 retrieve the rest of the results.
457 next_marker
459 A convenience element, useful when paginating with delimiters. The
460 value of "next_marker", if present, is the largest (alphabetically)
461 of all key names and all CommonPrefixes prefixes in the response.
462 If the "is_truncated" flag is set, request the next page of results
463 by setting "marker" to the value of "next_marker". This element is
464 only present in the response if the "delimiter" parameter was sent
465 with the request.
466 Each key is a hashref that looks like this:
468 {
470 key => $key,
471 last_modified => $last_mod_date,
472 etag => $etag, # An MD5 sum of the stored content.
473 size => $size, # Bytes
474 storage_class => $storage_class # Doc?
475 owner_id => $owner_id,
476 owner_displayname => $owner_name
477 }
478 list_bucket_all
480 List all keys in this bucket without having to worry about 'marker'.
481 This is a convenience method, but may make multiple requests to S3
482 under the hood.
483 Takes the same arguments as list_bucket.
485 _perform_operation
487 my $response = $s3->_perform_operation ('Operation' => (
488 # ... operation request parameters
489 ));
490 Internal operation implementation method, takes request construction
492 parameters, performs necessary HTTP requests(s) and returns Response
493 instance.
494 Method takes same named parameters as realted Request class.
496 Method provides available contextual parameters by default (eg s3,
498 bucket)
499 Method invokes contextual error handler.
501
503 Available since v0.97 - calling convention extentend
504 In order to make method calls somehow consistent, backward compatible,
506 and extendable, API's methods support multiple ways how to provide
507 their arguments
508 plain named arguments (preferred)
510 method (named => 'argument', another => 'argument');
511 trailing configuration hash
513 method ({ named => 'argument', another => 'argument' });
514 method (positional, { named => 'argument', another => 'argument' } );
515 Last argument of every method can be configuration hash, treated as
517 additional named arguments. Can be combined with named arguments.
518 positional arguments with optional named arguments
520 method (positional, named => 'argument', another => 'argument');
521 method (positional, { named => 'argument', another => 'argument' } );
522 For methods supporting mandatory positional arguments additional
524 named arguments and/or configuration hash is supported.
525 Named arguments or configuration hash can specify value of
527 positional arguments as well removing it from list of required
528 positional arguments for given call (see example)
529 $s3->bucket->add_key ('key', 'value', acl => $acl);
531 $s3->bucket->add_key ('value', key => 'key', acl => $acl);
532 $s3->bucket->add_key (key => 'key', value => 'value', acl => $acl);
533
535 Net::Amazon::S3 supports pluggable error handling via
536 Net::Amazon::S3::Error::Handler.
537 When response ends up with an error, every method reports it, and in
539 case it receives control back (no exception), it returns "undef".
540 Default error handling for Net::Amazon::S3 is
542 Net::Amazon::S3::Error::Handler::Legacy which (mostly) sets "err" and
543 "errstr".
544
546 This module contains code modified from Amazon that contains the
547 following notice:
548 # This software code is made available "AS IS" without warranties of any
550 # kind. You may copy, display, modify and redistribute the software
551 # code either by itself or as incorporated into your code; provided that
552 # you do not remove any proprietary notices. Your use of this software
553 # code is at your own risk and you waive any claim against Amazon
554 # Digital Services, Inc. or its affiliates with respect to your use of
555 # this software code. (c) 2006 Amazon Digital Services, Inc. or its
556 # affiliates.
557
559 Testing S3 is a tricky thing. Amazon wants to charge you a bit of money
560 each time you use their service. And yes, testing counts as using.
561 Because of this, the application's test suite skips anything
562 approaching a real test unless you set these three environment
563 variables:
564 AMAZON_S3_EXPENSIVE_TESTS
566 Doesn't matter what you set it to. Just has to be set
567 AWS_ACCESS_KEY_ID
569 Your AWS access key
570 AWS_ACCESS_KEY_SECRET
572 Your AWS sekkr1t passkey. Be forewarned that setting this
573 environment variable on a shared system might leak that information
574 to another user. Be careful.
575
577 Leon Brocard <acme@astray.com> and unknown Amazon Digital Services
578 programmers.
579 Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
581 Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54
583 Branislav Zahradník <barney@cpan.org> - since v0.81
585
587 Net::Amazon::S3::Bucket
588
590 Branislav Zahradník <barney@cpan.org>
591
593 This software is copyright (c) 2021 by Amazon Digital Services, Leon
594 Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav
595 Zahradník.
596 This is free software; you can redistribute it and/or modify it under
598 the same terms as the Perl 5 programming language system itself.
599perl v5.34.0 2022-01-21 Net::Amazon::S3(3)