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.89
10

SYNOPSIS

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
16         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
22                 retry                 => 1,
23             }
24         );
25
26         # 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
33         # 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
38         # or use an existing bucket
39         $bucket = $s3->bucket($bucketname);
40
41         # 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
46         # 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
50         # 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
59         # fetch file from the bucket
60         $response = $bucket->get_key_filename( '1.JPG', 'GET', 'backup.jpg' )
61             or die $s3->err . ": " . $s3->errstr;
62
63         # 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
72         # 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
76         # and finally delete the bucket
77         $bucket->delete_bucket or die $s3->err . ": " . $s3->errstr;
78

DESCRIPTION

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
90       To find out more about S3, please visit: http://s3.amazonaws.com/
91
92       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
98       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
102       Note: This is the legacy interface, please check out
103       Net::Amazon::S3::Client instead.
104
105       Development of this code happens here:
106       https://github.com/rustyconover/net-amazon-s3
107

METHODS

109   new
110       Create a new S3 client object. Takes some arguments:
111
112       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
118       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
125           DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE.
126           YOU'LL BE SORRY
127
128       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
133       use_iam_role
134           If you'd like to use IAM provided temporary credentials, pass this
135           option with a true value.
136
137       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
141           To use SSL-encrypted connections, LWP::Protocol::https is required.
142
143       keep_alive_cache_size
144           Set this to 0 to disable Keep-Alives.  Default is 10.
145
146       timeout
147           How many seconds should your script wait before bailing on a
148           request to S3? Defaults to 30.
149
150       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
155       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
159       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
168       authorization_method
169           Authorization implementation package name.
170
171           This library provides Net::Amazon::S3::Signature::V2 and
172           Net::Amazon::S3::Signature::V4
173
174           Default is Signature 4 if host is "s3.amazonaws.com", Signature 2
175           otherwise
176
177       Notes
178
179       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
184           $s3->ua( LWP::UserAgent->new(
185               keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] );
186
187   buckets
188       Returns undef on error, else hashref of results
189
190   add_bucket
191       Takes a hashref:
192
193       bucket
194           The name of the bucket you want to add
195
196       acl_short (optional)
197           See the set_acl subroutine for documentation on the acl_short
198           options
199
200       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
206       Returns 0 on failure, Net::Amazon::S3::Bucket object on success
207
208   bucket BUCKET
209       Takes a scalar argument, the name of the bucket you're creating
210
211       Returns an (unverified) bucket object from an account. Does no network
212       access.
213
214   delete_bucket
215       Takes either a Net::Amazon::S3::Bucket object or a hashref containing
216
217       bucket
218           The name of the bucket to remove
219
220       Returns false (and fails) if the bucket isn't empty.
221
222       Returns true if the bucket is successfully deleted.
223
224   list_bucket
225       List all keys in this bucket.
226
227       Takes a hashref of arguments:
228
229       MANDATORY
230
231       bucket
232           The name of the bucket you want to list keys on
233
234       OPTIONAL
235
236       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
242       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
254           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
261       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
274       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
282           See also "next_marker", below.
283
284           If "marker" is omitted,the first page of results is returned.
285
286       Returns undef on error and a hashref of data on success:
287
288       The hashref looks like this:
289
290         {
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
301       Explanation of bits of that:
302
303       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
309       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
315       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
324       Each key is a hashref that looks like this:
325
326            {
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
336   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
341       Takes the same arguments as list_bucket.
342
343   add_key
344       DEPRECATED. DO NOT USE
345
346   get_key
347       DEPRECATED. DO NOT USE
348
349   head_key
350       DEPRECATED. DO NOT USE
351
352   delete_key
353       DEPRECATED. DO NOT USE
354

LICENSE

356       This module contains code modified from Amazon that contains the
357       following notice:
358
359         #  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

TESTING

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
375       AMAZON_S3_EXPENSIVE_TESTS
376           Doesn't matter what you set it to. Just has to be set
377
378       AWS_ACCESS_KEY_ID
379           Your AWS access key
380
381       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

AUTHOR

387       Leon Brocard <acme@astray.com> and unknown Amazon Digital Services
388       programmers.
389
390       Brad Fitzpatrick <brad@danga.com> - return values, Bucket object
391
392       Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54
393

SEE ALSO

395       Net::Amazon::S3::Bucket
396

AUTHOR

398       Leo Lapworth <llap@cpan.org>
399
401       This software is copyright (c) 2020 by Amazon Digital Services, Leon
402       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover.
403
404       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.
406
407
408
409perl v5.30.1                      2020-02-12                Net::Amazon::S3(3)
Impressum