1Net::Amazon::S3(3)    User Contributed Perl Documentation   Net::Amazon::S3(3)
2
3
4

NAME

6       Net::Amazon::S3 - Use the Amazon S3 - Simple Storage Service
7

VERSION

9       version 0.98
10

SYNOPSIS

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
18         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
26         # 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
35         # 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
42         # 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
47         # or use an existing bucket
48         $bucket = $s3->bucket($bucketname);
49
50         # 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
55         # 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
59         # 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
68         # fetch file from the bucket
69         $response = $bucket->get_key_filename( '1.JPG', 'GET', 'backup.jpg' )
70             or die $s3->err . ": " . $s3->errstr;
71
72         # 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
81         # 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
85         # and finally delete the bucket
86         $bucket->delete_bucket or die $s3->err . ": " . $s3->errstr;
87

DESCRIPTION

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
99       To find out more about S3, please visit: http://s3.amazonaws.com/
100
101       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
107       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
111       Note: This is the legacy interface, please check out
112       Net::Amazon::S3::Client instead.
113
114       Development of this code happens here:
115       https://github.com/rustyconover/net-amazon-s3
116
117   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
121       Due the current implementation of Signature V4 handling you should use
122       workaround consisting of usage of region hostnames
123
124               my $bucket_region = $global_s3->bucket ($bucket)->_head_region;
125
126               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
134               my $bucket = $region_s3->bucket ($bucket);
135
136       And use bucket instance / region s3 connection.
137

METHODS

139   new
140       Create a new S3 client object. Takes some arguments:
141
142       authorization_context
143           Class that provides authorization informations.
144
145           See one of available implementations for more
146
147           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
153           S3 became widely used object storage protocol with many vendors
154           providing different feature sets and different compatibility level.
155
156           One common difference is bucket's HEAD request to determine its
157           region.
158
159           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
164           Net::Amazon::S3::Vendor::Amazon
165           Net::Amazon::S3::Vendor::Generic
166       aws_access_key_id
167           Deprecated.
168
169           When used it's used to create authorization context.
170
171           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
176       aws_secret_access_key
177           Deprecated.
178
179           When used it's used to create authorization context.
180
181           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
187           DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE.
188           YOU'LL BE SORRY
189
190       aws_session_token
191           Deprecated.
192
193           When used it's used to create authorization context.
194
195           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
199       use_iam_role
200           Deprecated.
201
202           When used it's used to create authorization context.
203
204           If you'd like to use IAM provided temporary credentials, pass this
205           option with a true value.
206
207       secure
208           Deprecated.
209
210           Set this to 0 if you don't want to use SSL-encrypted connections
211           when talking to S3. Defaults to 1.
212
213           To use SSL-encrypted connections, LWP::Protocol::https is required.
214
215           See #vendor and Net::Amazon::S3::Vendor.
216
217       keep_alive_cache_size
218           Set this to 0 to disable Keep-Alives.  Default is 10.
219
220       timeout
221           How many seconds should your script wait before bailing on a
222           request to S3? Defaults to 30.
223
224       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
229       host
230           Deprecated.
231
232           The S3 host endpoint to use. Defaults to 's3.amazonaws.com'. This
233           allows you to connect to any S3-compatible host.
234
235           See #vendor and Net::Amazon::S3::Vendor.
236
237       use_virtual_host
238           Deprecated.
239
240           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
248           See #vendor and Net::Amazon::S3::Vendor.
249
250       authorization_method
251           Deprecated.
252
253           Authorization implementation package name.
254
255           This library provides Net::Amazon::S3::Signature::V2 and
256           Net::Amazon::S3::Signature::V4
257
258           Default is Signature 4 if host is "s3.amazonaws.com", Signature 2
259           otherwise
260
261           See #vendor and Net::Amazon::S3::Vendor.
262
263       error_handler_class
264           Error handler class name (package name), see
265           Net::Amazon::S3::Error::Handler for more.
266
267           Default: Net::Amazon::S3::Error::Handler::Legacy
268
269       error_handler
270           Instance of error handler class.
271
272       Notes
273
274       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
279           $s3->ua( LWP::UserAgent->new(
280               keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] );
281
282   buckets
283       Returns undef on error, else hashref of results
284
285   add_bucket
286               # Create new bucket with default location
287               my $bucket = $s3->add_bucket ('new-bucket');
288
289               # 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
295       Method creates and returns new bucket.
296
297       In case of error it reports it and returns "undef" (refer "ERROR
298       HANDLING").
299
300       Recognized positional arguments (refer "CALLING CONVENTION")
301
302       bucket
303           Required, recognized as positional.
304
305           The name of the bucket you want to add.
306
307       Recognized optional arguments
308
309       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
314           Available since v0.94
315
316           Set ACL to the newly created bucket. Refer Net::Amazon::S3::ACL for
317           possibilities.
318
319       acl_short (deprecated)
320           Deprecated since v0.94
321
322           When specified its value is used to populate "acl" argument (unless
323           it exists).
324
325       location_constraint
326           Optional.
327
328           Sets the location constraint of the new bucket. If left
329           unspecified, the default S3 datacenter location will be used.
330
331           This library recognizes regions according Amazon S3 documentation
332
333           →   <https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region>
334
335           →   <https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestSyntax>
336
337       Provides operation CreateBucket
338       <https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html>.
339
340   bucket BUCKET
341       Takes a scalar argument, the name of the bucket you're creating
342
343       Returns an (unverified) bucket object from an account. Does no network
344       access.
345
346   delete_bucket
347               $s3->delete_bucket ($bucket);
348               $s3->delete_bucket (bucket => $bucket);
349
350       Deletes bucket from account.
351
352       Returns "true" if the bucket is successfully deleted.
353
354       Returns "false" and reports an error otherwise (refer "ERROR HANDLING")
355
356       Positional arguments (refer "CALLING CONVENTION")
357
358       bucket
359           Required.
360
361           The name of the bucket or Net::Amazon::S3::Bucket instance you want
362           to delete.
363
364       Provides operation "DeleteBucket"
365       <https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html>
366
367   list_bucket
368       List all keys in this bucket.
369
370       Takes a hashref of arguments:
371
372       MANDATORY
373
374       bucket
375           The name of the bucket you want to list keys on
376
377       OPTIONAL
378
379       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
385       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
397           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
404       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
417       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
425           See also "next_marker", below.
426
427           If "marker" is omitted,the first page of results is returned.
428
429       Returns undef on error and a hashref of data on success:
430
431       The hashref looks like this:
432
433         {
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
444       Explanation of bits of that:
445
446       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
452       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
458       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
467       Each key is a hashref that looks like this:
468
469            {
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
479   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
484       Takes the same arguments as list_bucket.
485
486   _perform_operation
487           my $response = $s3->_perform_operation ('Operation' => (
488               # ... operation request parameters
489           ));
490
491       Internal operation implementation method, takes request construction
492       parameters, performs necessary HTTP requests(s) and returns Response
493       instance.
494
495       Method takes same named parameters as realted Request class.
496
497       Method provides available contextual parameters by default (eg s3,
498       bucket)
499
500       Method invokes contextual error handler.
501

CALLING CONVENTION

503       Available since v0.97 - calling convention extentend
504
505       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
509       plain named arguments (preferred)
510                   method (named => 'argument', another => 'argument');
511
512       trailing configuration hash
513                   method ({ named => 'argument', another => 'argument' });
514                   method (positional, { named => 'argument', another => 'argument' } );
515
516           Last argument of every method can be configuration hash, treated as
517           additional named arguments. Can be combined with named arguments.
518
519       positional arguments with optional named arguments
520                   method (positional, named => 'argument', another => 'argument');
521                   method (positional, { named => 'argument', another => 'argument' } );
522
523           For methods supporting mandatory positional arguments additional
524           named arguments and/or configuration hash is supported.
525
526           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
530                   $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

ERROR HANDLING

535       Net::Amazon::S3 supports pluggable error handling via
536       Net::Amazon::S3::Error::Handler.
537
538       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
541       Default error handling for Net::Amazon::S3 is
542       Net::Amazon::S3::Error::Handler::Legacy which (mostly) sets "err" and
543       "errstr".
544

LICENSE

546       This module contains code modified from Amazon that contains the
547       following notice:
548
549         #  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

TESTING

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
565       AMAZON_S3_EXPENSIVE_TESTS
566           Doesn't matter what you set it to. Just has to be set
567
568       AWS_ACCESS_KEY_ID
569           Your AWS access key
570
571       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

AUTHOR

577       Leon Brocard <acme@astray.com> and unknown Amazon Digital Services
578       programmers.
579
580       Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
581
582       Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54
583
584       Branislav Zahradník <barney@cpan.org> - since v0.81
585

SEE ALSO

587       Net::Amazon::S3::Bucket
588

AUTHOR

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
597       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.
599
600
601
602perl v5.34.0                      2021-07-22                Net::Amazon::S3(3)
Impressum