line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
package Net::Amazon::S3; |
2
|
|
|
|
|
|
|
# ABSTRACT: Use the Amazon S3 - Simple Storage Service |
3
|
|
|
|
|
|
|
$Net::Amazon::S3::VERSION = '0.98'; |
4
|
96
|
|
|
96
|
|
1070552
|
use Moose 0.85; |
|
96
|
|
|
|
|
28785541
|
|
|
96
|
|
|
|
|
911
|
|
5
|
96
|
|
|
96
|
|
691185
|
use MooseX::StrictConstructor 0.16; |
|
96
|
|
|
|
|
1592421
|
|
|
96
|
|
|
|
|
636
|
|
6
|
|
|
|
|
|
|
|
7
|
96
|
|
|
96
|
|
745565
|
use Carp; |
|
96
|
|
|
|
|
248
|
|
|
96
|
|
|
|
|
6938
|
|
8
|
96
|
|
|
96
|
|
58026
|
use Digest::HMAC_SHA1; |
|
96
|
|
|
|
|
510599
|
|
|
96
|
|
|
|
|
4184
|
|
9
|
96
|
|
|
96
|
|
1719
|
use Safe::Isa (); |
|
96
|
|
|
|
|
1293
|
|
|
96
|
|
|
|
|
1885
|
|
10
|
|
|
|
|
|
|
|
11
|
96
|
|
|
96
|
|
57827
|
use Net::Amazon::S3::Bucket; |
|
96
|
|
|
|
|
475
|
|
|
96
|
|
|
|
|
5901
|
|
12
|
96
|
|
|
96
|
|
43007
|
use Net::Amazon::S3::Client; |
|
96
|
|
|
|
|
321
|
|
|
96
|
|
|
|
|
3625
|
|
13
|
96
|
|
|
96
|
|
59068
|
use Net::Amazon::S3::Client::Bucket; |
|
96
|
|
|
|
|
430
|
|
|
96
|
|
|
|
|
4857
|
|
14
|
96
|
|
|
96
|
|
73699
|
use Net::Amazon::S3::Client::Object; |
|
96
|
|
|
|
|
511
|
|
|
96
|
|
|
|
|
5169
|
|
15
|
96
|
|
|
96
|
|
64998
|
use Net::Amazon::S3::Error::Handler::Legacy; |
|
96
|
|
|
|
|
397
|
|
|
96
|
|
|
|
|
4403
|
|
16
|
96
|
|
|
96
|
|
53653
|
use Net::Amazon::S3::HTTPRequest; |
|
96
|
|
|
|
|
466
|
|
|
96
|
|
|
|
|
5193
|
|
17
|
96
|
|
|
96
|
|
62930
|
use Net::Amazon::S3::Request; |
|
96
|
|
|
|
|
440
|
|
|
96
|
|
|
|
|
4489
|
|
18
|
96
|
|
|
96
|
|
60649
|
use Net::Amazon::S3::Response; |
|
96
|
|
|
|
|
486
|
|
|
96
|
|
|
|
|
5280
|
|
19
|
96
|
|
|
96
|
|
60124
|
use Net::Amazon::S3::Operation::Bucket::Acl::Fetch; |
|
96
|
|
|
|
|
473
|
|
|
96
|
|
|
|
|
5207
|
|
20
|
96
|
|
|
96
|
|
53468
|
use Net::Amazon::S3::Operation::Bucket::Acl::Set; |
|
96
|
|
|
|
|
428
|
|
|
96
|
|
|
|
|
4775
|
|
21
|
96
|
|
|
96
|
|
50039
|
use Net::Amazon::S3::Operation::Bucket::Create; |
|
96
|
|
|
|
|
478
|
|
|
96
|
|
|
|
|
4796
|
|
22
|
96
|
|
|
96
|
|
49642
|
use Net::Amazon::S3::Operation::Bucket::Delete; |
|
96
|
|
|
|
|
572
|
|
|
96
|
|
|
|
|
4921
|
|
23
|
96
|
|
|
96
|
|
50422
|
use Net::Amazon::S3::Operation::Bucket::Location; |
|
96
|
|
|
|
|
383
|
|
|
96
|
|
|
|
|
4440
|
|
24
|
96
|
|
|
96
|
|
51914
|
use Net::Amazon::S3::Operation::Bucket::Tags::Add; |
|
96
|
|
|
|
|
403
|
|
|
96
|
|
|
|
|
4912
|
|
25
|
96
|
|
|
96
|
|
52417
|
use Net::Amazon::S3::Operation::Bucket::Tags::Delete; |
|
96
|
|
|
|
|
460
|
|
|
96
|
|
|
|
|
4705
|
|
26
|
96
|
|
|
96
|
|
50776
|
use Net::Amazon::S3::Operation::Buckets::List; |
|
96
|
|
|
|
|
386
|
|
|
96
|
|
|
|
|
4319
|
|
27
|
96
|
|
|
96
|
|
55458
|
use Net::Amazon::S3::Operation::Object::Acl::Fetch; |
|
96
|
|
|
|
|
421
|
|
|
96
|
|
|
|
|
4713
|
|
28
|
96
|
|
|
96
|
|
52751
|
use Net::Amazon::S3::Operation::Object::Acl::Set; |
|
96
|
|
|
|
|
409
|
|
|
96
|
|
|
|
|
4748
|
|
29
|
96
|
|
|
96
|
|
51681
|
use Net::Amazon::S3::Operation::Object::Add; |
|
96
|
|
|
|
|
465
|
|
|
96
|
|
|
|
|
4938
|
|
30
|
96
|
|
|
96
|
|
51871
|
use Net::Amazon::S3::Operation::Object::Delete; |
|
96
|
|
|
|
|
407
|
|
|
96
|
|
|
|
|
4793
|
|
31
|
96
|
|
|
96
|
|
51176
|
use Net::Amazon::S3::Operation::Object::Fetch; |
|
96
|
|
|
|
|
428
|
|
|
96
|
|
|
|
|
4788
|
|
32
|
96
|
|
|
96
|
|
51080
|
use Net::Amazon::S3::Operation::Object::Head; |
|
96
|
|
|
|
|
428
|
|
|
96
|
|
|
|
|
4710
|
|
33
|
96
|
|
|
96
|
|
50346
|
use Net::Amazon::S3::Operation::Object::Restore; |
|
96
|
|
|
|
|
437
|
|
|
96
|
|
|
|
|
4903
|
|
34
|
96
|
|
|
96
|
|
53680
|
use Net::Amazon::S3::Operation::Object::Tags::Add; |
|
96
|
|
|
|
|
471
|
|
|
96
|
|
|
|
|
5002
|
|
35
|
96
|
|
|
96
|
|
51712
|
use Net::Amazon::S3::Operation::Object::Tags::Delete; |
|
96
|
|
|
|
|
431
|
|
|
96
|
|
|
|
|
4791
|
|
36
|
96
|
|
|
96
|
|
52851
|
use Net::Amazon::S3::Operation::Object::Upload::Abort; |
|
96
|
|
|
|
|
432
|
|
|
96
|
|
|
|
|
5083
|
|
37
|
96
|
|
|
96
|
|
53214
|
use Net::Amazon::S3::Operation::Object::Upload::Complete; |
|
96
|
|
|
|
|
490
|
|
|
96
|
|
|
|
|
4972
|
|
38
|
96
|
|
|
96
|
|
54578
|
use Net::Amazon::S3::Operation::Object::Upload::Create; |
|
96
|
|
|
|
|
455
|
|
|
96
|
|
|
|
|
4797
|
|
39
|
96
|
|
|
96
|
|
54220
|
use Net::Amazon::S3::Operation::Object::Upload::Part; |
|
96
|
|
|
|
|
436
|
|
|
96
|
|
|
|
|
5092
|
|
40
|
96
|
|
|
96
|
|
55241
|
use Net::Amazon::S3::Operation::Object::Upload::Parts; |
|
96
|
|
|
|
|
434
|
|
|
96
|
|
|
|
|
4929
|
|
41
|
96
|
|
|
96
|
|
52692
|
use Net::Amazon::S3::Operation::Objects::Delete; |
|
96
|
|
|
|
|
448
|
|
|
96
|
|
|
|
|
4911
|
|
42
|
96
|
|
|
96
|
|
52297
|
use Net::Amazon::S3::Operation::Objects::List; |
|
96
|
|
|
|
|
432
|
|
|
96
|
|
|
|
|
4610
|
|
43
|
96
|
|
|
96
|
|
2707
|
use Net::Amazon::S3::Signature::V2; |
|
96
|
|
|
|
|
268
|
|
|
96
|
|
|
|
|
2726
|
|
44
|
96
|
|
|
96
|
|
53125
|
use Net::Amazon::S3::Signature::V4; |
|
96
|
|
|
|
|
432
|
|
|
96
|
|
|
|
|
5291
|
|
45
|
96
|
|
|
96
|
|
95130
|
use Net::Amazon::S3::Utils; |
|
96
|
|
|
|
|
333
|
|
|
96
|
|
|
|
|
3844
|
|
46
|
96
|
|
|
96
|
|
45345
|
use Net::Amazon::S3::Vendor; |
|
96
|
|
|
|
|
414
|
|
|
96
|
|
|
|
|
4449
|
|
47
|
96
|
|
|
96
|
|
58480
|
use Net::Amazon::S3::Vendor::Amazon; |
|
96
|
|
|
|
|
399
|
|
|
96
|
|
|
|
|
4502
|
|
48
|
96
|
|
|
96
|
|
60635
|
use LWP::UserAgent::Determined; |
|
96
|
|
|
|
|
55827
|
|
|
96
|
|
|
|
|
3566
|
|
49
|
96
|
|
|
96
|
|
821
|
use URI::Escape qw(uri_escape_utf8); |
|
96
|
|
|
|
|
242
|
|
|
96
|
|
|
|
|
193912
|
|
50
|
|
|
|
|
|
|
|
51
|
|
|
|
|
|
|
my $AMAZON_S3_HOST = 's3.amazonaws.com'; |
52
|
|
|
|
|
|
|
|
53
|
|
|
|
|
|
|
has authorization_context => ( |
54
|
|
|
|
|
|
|
is => 'ro', |
55
|
|
|
|
|
|
|
isa => 'Net::Amazon::S3::Authorization', |
56
|
|
|
|
|
|
|
required => 0, |
57
|
|
|
|
|
|
|
|
58
|
|
|
|
|
|
|
handles => { |
59
|
|
|
|
|
|
|
aws_access_key_id => 'aws_access_key_id', |
60
|
|
|
|
|
|
|
aws_secret_access_key => 'aws_secret_access_key', |
61
|
|
|
|
|
|
|
aws_session_token => 'aws_session_token', |
62
|
|
|
|
|
|
|
}, |
63
|
|
|
|
|
|
|
); |
64
|
|
|
|
|
|
|
|
65
|
|
|
|
|
|
|
has vendor => ( |
66
|
|
|
|
|
|
|
is => 'ro', |
67
|
|
|
|
|
|
|
isa => 'Net::Amazon::S3::Vendor', |
68
|
|
|
|
|
|
|
required => 1, |
69
|
|
|
|
|
|
|
|
70
|
|
|
|
|
|
|
handles => { |
71
|
|
|
|
|
|
|
authorization_method => 'authorization_method', |
72
|
|
|
|
|
|
|
host => 'host', |
73
|
|
|
|
|
|
|
secure => 'use_https', |
74
|
|
|
|
|
|
|
use_virtual_host => 'use_virtual_host', |
75
|
|
|
|
|
|
|
}, |
76
|
|
|
|
|
|
|
); |
77
|
|
|
|
|
|
|
|
78
|
|
|
|
|
|
|
has 'timeout' => ( is => 'ro', isa => 'Num', required => 0, default => 30 ); |
79
|
|
|
|
|
|
|
has 'retry' => ( is => 'ro', isa => 'Bool', required => 0, default => 0 ); |
80
|
|
|
|
|
|
|
has 'ua' => ( is => 'rw', isa => 'LWP::UserAgent', required => 0 ); |
81
|
|
|
|
|
|
|
has 'err' => ( is => 'rw', isa => 'Maybe[Str]', required => 0 ); |
82
|
|
|
|
|
|
|
has 'errstr' => ( is => 'rw', isa => 'Maybe[Str]', required => 0 ); |
83
|
|
|
|
|
|
|
has keep_alive_cache_size => ( is => 'ro', isa => 'Int', required => 0, default => 10 ); |
84
|
|
|
|
|
|
|
|
85
|
|
|
|
|
|
|
has error_handler_class => ( |
86
|
|
|
|
|
|
|
is => 'ro', |
87
|
|
|
|
|
|
|
lazy => 1, |
88
|
|
|
|
|
|
|
default => 'Net::Amazon::S3::Error::Handler::Legacy', |
89
|
|
|
|
|
|
|
); |
90
|
|
|
|
|
|
|
|
91
|
|
|
|
|
|
|
has error_handler => ( |
92
|
|
|
|
|
|
|
is => 'ro', |
93
|
|
|
|
|
|
|
lazy => 1, |
94
|
|
|
|
|
|
|
default => sub { $_[0]->error_handler_class->new (s3 => $_[0]) }, |
95
|
|
|
|
|
|
|
); |
96
|
|
|
|
|
|
|
|
97
|
|
|
|
|
|
|
has bucket_class => ( |
98
|
|
|
|
|
|
|
is => 'ro', |
99
|
|
|
|
|
|
|
init_arg => undef, |
100
|
|
|
|
|
|
|
lazy => 1, |
101
|
|
|
|
|
|
|
default => 'Net::Amazon::S3::Bucket', |
102
|
|
|
|
|
|
|
); |
103
|
|
|
|
|
|
|
|
104
|
|
|
|
|
|
|
sub _build_arg_authorization_context { |
105
|
408
|
|
|
408
|
|
1094
|
my ($args) = @_; |
106
|
|
|
|
|
|
|
|
107
|
408
|
|
|
|
|
1208
|
my $aws_access_key_id = delete $args->{aws_access_key_id}; |
108
|
408
|
|
|
|
|
1064
|
my $aws_secret_access_key = delete $args->{aws_secret_access_key}; |
109
|
408
|
|
|
|
|
1082
|
my $use_iam_role = delete $args->{use_iam_role}; |
110
|
408
|
|
|
|
|
951
|
my $aws_session_token = delete $args->{aws_session_token}; |
111
|
|
|
|
|
|
|
|
112
|
408
|
50
|
|
|
|
1471
|
if ($args->{authorization_context}) { |
113
|
0
|
|
|
|
|
0
|
return $args->{authorization_context}; |
114
|
|
|
|
|
|
|
} |
115
|
|
|
|
|
|
|
|
116
|
408
|
100
|
66
|
|
|
2298
|
if ($use_iam_role || $aws_session_token) { |
117
|
1
|
|
|
|
|
591
|
require Net::Amazon::S3::Authorization::IAM; |
118
|
|
|
|
|
|
|
|
119
|
1
|
|
|
|
|
16
|
return Net::Amazon::S3::Authorization::IAM->new ( |
120
|
|
|
|
|
|
|
aws_access_key_id => $aws_access_key_id, |
121
|
|
|
|
|
|
|
aws_secret_access_key => $aws_secret_access_key, |
122
|
|
|
|
|
|
|
aws_session_token => $aws_session_token, |
123
|
|
|
|
|
|
|
) |
124
|
|
|
|
|
|
|
} |
125
|
|
|
|
|
|
|
|
126
|
407
|
|
|
|
|
50313
|
require Net::Amazon::S3::Authorization::Basic; |
127
|
|
|
|
|
|
|
|
128
|
407
|
|
|
|
|
3372
|
return Net::Amazon::S3::Authorization::Basic->new ( |
129
|
|
|
|
|
|
|
aws_access_key_id => $aws_access_key_id, |
130
|
|
|
|
|
|
|
aws_secret_access_key => $aws_secret_access_key, |
131
|
|
|
|
|
|
|
); |
132
|
|
|
|
|
|
|
} |
133
|
|
|
|
|
|
|
|
134
|
|
|
|
|
|
|
sub _build_arg_vendor { |
135
|
408
|
|
|
408
|
|
1213
|
my ($args) = @_; |
136
|
|
|
|
|
|
|
|
137
|
|
|
|
|
|
|
my %backward = |
138
|
1267
|
|
|
|
|
3541
|
map { $_ => delete $args->{$_} } |
139
|
408
|
|
|
|
|
1160
|
grep { exists $args->{$_} } |
|
1632
|
|
|
|
|
3699
|
|
140
|
|
|
|
|
|
|
qw[ host secure use_virtual_host authorization_method ] |
141
|
|
|
|
|
|
|
; |
142
|
|
|
|
|
|
|
|
143
|
|
|
|
|
|
|
return $args->{vendor} |
144
|
408
|
100
|
|
|
|
2019
|
if $args->{vendor}; |
145
|
|
|
|
|
|
|
|
146
|
|
|
|
|
|
|
$backward{host} = $AMAZON_S3_HOST |
147
|
406
|
100
|
|
|
|
1832
|
unless exists $backward{host}; |
148
|
|
|
|
|
|
|
|
149
|
|
|
|
|
|
|
$backward{use_https} = delete $backward{secure} |
150
|
406
|
100
|
|
|
|
1649
|
if exists $backward{secure}; |
151
|
|
|
|
|
|
|
|
152
|
406
|
100
|
|
|
|
1760
|
my $vendor_class = $backward{host} eq $AMAZON_S3_HOST |
153
|
|
|
|
|
|
|
? 'Net::Amazon::S3::Vendor::Amazon' |
154
|
|
|
|
|
|
|
: 'Net::Amazon::S3::Vendor' |
155
|
|
|
|
|
|
|
; |
156
|
|
|
|
|
|
|
|
157
|
406
|
|
|
|
|
4005
|
return $vendor_class->new (%backward); |
158
|
|
|
|
|
|
|
} |
159
|
|
|
|
|
|
|
|
160
|
|
|
|
|
|
|
around BUILDARGS => sub { |
161
|
|
|
|
|
|
|
my ($orig, $class) = (shift, shift); |
162
|
|
|
|
|
|
|
my $args = $class->$orig (@_); |
163
|
|
|
|
|
|
|
|
164
|
|
|
|
|
|
|
# support compat authorization arguments |
165
|
|
|
|
|
|
|
$args->{authorization_context} = _build_arg_authorization_context $args; |
166
|
|
|
|
|
|
|
$args->{vendor} = _build_arg_vendor $args; |
167
|
|
|
|
|
|
|
|
168
|
|
|
|
|
|
|
$args; |
169
|
|
|
|
|
|
|
}; |
170
|
|
|
|
|
|
|
|
171
|
|
|
|
|
|
|
|
172
|
|
|
|
|
|
|
sub BUILD { |
173
|
408
|
|
|
408
|
0
|
1022
|
my $self = shift; |
174
|
|
|
|
|
|
|
|
175
|
408
|
|
|
|
|
816
|
my $ua; |
176
|
408
|
50
|
|
|
|
12625
|
if ( $self->retry ) { |
177
|
0
|
|
|
|
|
0
|
$ua = LWP::UserAgent::Determined->new( |
178
|
|
|
|
|
|
|
keep_alive => $self->keep_alive_cache_size, |
179
|
|
|
|
|
|
|
requests_redirectable => [qw(GET HEAD DELETE PUT POST)], |
180
|
|
|
|
|
|
|
); |
181
|
0
|
|
|
|
|
0
|
$ua->timing('1,2,4,8,16,32'); |
182
|
|
|
|
|
|
|
} else { |
183
|
408
|
|
|
|
|
11894
|
$ua = LWP::UserAgent->new( |
184
|
|
|
|
|
|
|
keep_alive => $self->keep_alive_cache_size, |
185
|
|
|
|
|
|
|
requests_redirectable => [qw(GET HEAD DELETE PUT POST)], |
186
|
|
|
|
|
|
|
); |
187
|
|
|
|
|
|
|
} |
188
|
|
|
|
|
|
|
|
189
|
408
|
|
|
|
|
602574
|
$ua->timeout( $self->timeout ); |
190
|
408
|
|
|
|
|
8610
|
$ua->env_proxy; |
191
|
|
|
|
|
|
|
|
192
|
408
|
|
|
|
|
519681
|
$self->ua($ua); |
193
|
|
|
|
|
|
|
} |
194
|
|
|
|
|
|
|
|
195
|
|
|
|
|
|
|
sub buckets { |
196
|
5
|
|
|
5
|
1
|
22
|
my ($self, %args) = @_; |
197
|
|
|
|
|
|
|
|
198
|
5
|
|
|
|
|
21
|
my $response = $self->_perform_operation ( |
199
|
|
|
|
|
|
|
'Net::Amazon::S3::Operation::Buckets::List', |
200
|
|
|
|
|
|
|
%args, |
201
|
|
|
|
|
|
|
); |
202
|
|
|
|
|
|
|
|
203
|
4
|
100
|
|
|
|
19
|
return unless $response->is_success; |
204
|
|
|
|
|
|
|
|
205
|
2
|
|
|
|
|
40
|
my $owner_id = $response->owner_id;; |
206
|
2
|
|
|
|
|
7
|
my $owner_displayname = $response->owner_displayname; |
207
|
|
|
|
|
|
|
|
208
|
2
|
|
|
|
|
3
|
my @buckets; |
209
|
2
|
|
|
|
|
5
|
foreach my $bucket ($response->buckets) { |
210
|
|
|
|
|
|
|
push @buckets, $self->bucket_class->new ( |
211
|
|
|
|
|
|
|
account => $self, |
212
|
|
|
|
|
|
|
bucket => $bucket->{name}, |
213
|
|
|
|
|
|
|
creation_date => $bucket->{creation_date}, |
214
|
4
|
|
|
|
|
94
|
); |
215
|
|
|
|
|
|
|
|
216
|
|
|
|
|
|
|
} |
217
|
|
|
|
|
|
|
|
218
|
|
|
|
|
|
|
return +{ |
219
|
2
|
|
|
|
|
15
|
owner_id => $owner_id, |
220
|
|
|
|
|
|
|
owner_displayname => $owner_displayname, |
221
|
|
|
|
|
|
|
buckets => \@buckets, |
222
|
|
|
|
|
|
|
}; |
223
|
|
|
|
|
|
|
} |
224
|
|
|
|
|
|
|
|
225
|
|
|
|
|
|
|
sub add_bucket { |
226
|
27
|
|
|
27
|
1
|
65
|
my $self = shift; |
227
|
27
|
|
|
|
|
208
|
my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_); |
228
|
|
|
|
|
|
|
|
229
|
27
|
|
|
|
|
157
|
my $response = $self->_perform_operation ( |
230
|
|
|
|
|
|
|
'Net::Amazon::S3::Operation::Bucket::Create', |
231
|
|
|
|
|
|
|
|
232
|
|
|
|
|
|
|
%args, |
233
|
|
|
|
|
|
|
); |
234
|
|
|
|
|
|
|
|
235
|
11
|
100
|
|
|
|
292
|
return unless $response->is_success; |
236
|
|
|
|
|
|
|
|
237
|
7
|
|
|
|
|
178
|
return $self->bucket ($args{bucket}); |
238
|
|
|
|
|
|
|
} |
239
|
|
|
|
|
|
|
|
240
|
|
|
|
|
|
|
sub bucket { |
241
|
146
|
|
|
146
|
1
|
2294
|
my ( $self, $bucket ) = @_; |
242
|
|
|
|
|
|
|
|
243
|
146
|
100
|
|
|
|
5207
|
return $bucket if $bucket->$Safe::Isa::_isa ($self->bucket_class); |
244
|
|
|
|
|
|
|
|
245
|
145
|
|
|
|
|
5165
|
return $self->bucket_class->new( |
246
|
|
|
|
|
|
|
{ bucket => $bucket, account => $self } ); |
247
|
|
|
|
|
|
|
} |
248
|
|
|
|
|
|
|
|
249
|
|
|
|
|
|
|
sub delete_bucket { |
250
|
9
|
|
|
9
|
1
|
20
|
my $self = shift; |
251
|
9
|
|
|
|
|
83
|
my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_); |
252
|
|
|
|
|
|
|
|
253
|
|
|
|
|
|
|
croak 'must specify bucket' |
254
|
9
|
50
|
|
|
|
41
|
unless defined $args{bucket}; |
255
|
|
|
|
|
|
|
|
256
|
9
|
|
|
|
|
43
|
my $response = $self->_perform_operation ( |
257
|
|
|
|
|
|
|
'Net::Amazon::S3::Operation::Bucket::Delete', |
258
|
|
|
|
|
|
|
%args, |
259
|
|
|
|
|
|
|
); |
260
|
|
|
|
|
|
|
|
261
|
5
|
100
|
|
|
|
40
|
return unless $response->is_success; |
262
|
|
|
|
|
|
|
|
263
|
1
|
|
|
|
|
29
|
return 1; |
264
|
|
|
|
|
|
|
} |
265
|
|
|
|
|
|
|
|
266
|
|
|
|
|
|
|
sub list_bucket { |
267
|
16
|
|
|
16
|
1
|
40
|
my $self = shift; |
268
|
16
|
|
|
|
|
111
|
my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_); |
269
|
|
|
|
|
|
|
|
270
|
16
|
|
|
|
|
105
|
my $response = $self->_perform_operation ( |
271
|
|
|
|
|
|
|
'Net::Amazon::S3::Operation::Objects::List', |
272
|
|
|
|
|
|
|
%args, |
273
|
|
|
|
|
|
|
); |
274
|
|
|
|
|
|
|
|
275
|
8
|
100
|
|
|
|
56
|
return unless $response->is_success; |
276
|
|
|
|
|
|
|
|
277
|
5
|
|
|
|
|
128
|
my $return = { |
278
|
|
|
|
|
|
|
bucket => $response->bucket, |
279
|
|
|
|
|
|
|
prefix => $response->prefix, |
280
|
|
|
|
|
|
|
marker => $response->marker, |
281
|
|
|
|
|
|
|
next_marker => $response->next_marker, |
282
|
|
|
|
|
|
|
max_keys => $response->max_keys, |
283
|
|
|
|
|
|
|
is_truncated => $response->is_truncated, |
284
|
|
|
|
|
|
|
}; |
285
|
|
|
|
|
|
|
|
286
|
5
|
|
|
|
|
16
|
my @keys; |
287
|
5
|
|
|
|
|
20
|
foreach my $node ($response->contents) { |
288
|
|
|
|
|
|
|
push @keys, { |
289
|
|
|
|
|
|
|
key => $node->{key}, |
290
|
|
|
|
|
|
|
last_modified => $node->{last_modified}, |
291
|
|
|
|
|
|
|
etag => $node->{etag}, |
292
|
|
|
|
|
|
|
size => $node->{size}, |
293
|
|
|
|
|
|
|
storage_class => $node->{storage_class}, |
294
|
|
|
|
|
|
|
owner_id => $node->{owner}{id}, |
295
|
|
|
|
|
|
|
owner_displayname => $node->{owner}{displayname}, |
296
|
7
|
|
|
|
|
66
|
}; |
297
|
|
|
|
|
|
|
} |
298
|
5
|
|
|
|
|
20
|
$return->{keys} = \@keys; |
299
|
|
|
|
|
|
|
|
300
|
5
|
100
|
|
|
|
17
|
if ( $args{delimiter} ) { |
301
|
2
|
|
|
|
|
9
|
$return->{common_prefixes} = [ $response->common_prefixes ]; |
302
|
|
|
|
|
|
|
} |
303
|
|
|
|
|
|
|
|
304
|
5
|
|
|
|
|
26
|
return $return; |
305
|
|
|
|
|
|
|
} |
306
|
|
|
|
|
|
|
|
307
|
|
|
|
|
|
|
sub list_bucket_all { |
308
|
4
|
|
|
4
|
1
|
10
|
my $self = shift; |
309
|
4
|
|
|
|
|
17
|
my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket (\@_); |
310
|
|
|
|
|
|
|
|
311
|
4
|
|
|
|
|
16
|
my $bucket = $args{bucket}; |
312
|
4
|
50
|
|
|
|
13
|
croak 'must specify bucket' unless $bucket; |
313
|
|
|
|
|
|
|
|
314
|
4
|
|
|
|
|
16
|
my $response = $self->list_bucket (%args); |
315
|
0
|
0
|
|
|
|
0
|
return $response unless $response->{is_truncated}; |
316
|
0
|
|
|
|
|
0
|
my $all = $response; |
317
|
|
|
|
|
|
|
|
318
|
0
|
|
|
|
|
0
|
while (1) { |
319
|
|
|
|
|
|
|
my $next_marker = $response->{next_marker} |
320
|
0
|
|
0
|
|
|
0
|
|| $response->{keys}->[-1]->{key}; |
321
|
0
|
|
|
|
|
0
|
$response = $self->list_bucket ( |
322
|
|
|
|
|
|
|
%args, |
323
|
|
|
|
|
|
|
marker => $next_marker, |
324
|
|
|
|
|
|
|
); |
325
|
0
|
|
|
|
|
0
|
push @{ $all->{keys} }, @{ $response->{keys} }; |
|
0
|
|
|
|
|
0
|
|
|
0
|
|
|
|
|
0
|
|
326
|
0
|
0
|
|
|
|
0
|
last unless $response->{is_truncated}; |
327
|
|
|
|
|
|
|
} |
328
|
|
|
|
|
|
|
|
329
|
0
|
|
|
|
|
0
|
delete $all->{is_truncated}; |
330
|
0
|
|
|
|
|
0
|
delete $all->{next_marker}; |
331
|
0
|
|
|
|
|
0
|
return $all; |
332
|
|
|
|
|
|
|
} |
333
|
|
|
|
|
|
|
|
334
|
|
|
|
|
|
|
# compat wrapper; deprecated as of 2005-03-23 |
335
|
|
|
|
|
|
|
sub add_key { |
336
|
2
|
|
|
2
|
0
|
4
|
my $self = shift; |
337
|
2
|
|
|
|
|
10
|
my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket_and_object (\@_); |
338
|
|
|
|
|
|
|
|
339
|
2
|
|
|
|
|
11
|
my $bucket = $self->bucket (delete $args{bucket}); |
340
|
2
|
|
|
|
|
11
|
return $bucket->add_key (%args); |
341
|
|
|
|
|
|
|
} |
342
|
|
|
|
|
|
|
|
343
|
|
|
|
|
|
|
# compat wrapper; deprecated as of 2005-03-23 |
344
|
|
|
|
|
|
|
sub get_key { |
345
|
2
|
|
|
2
|
0
|
5
|
my $self = shift; |
346
|
2
|
|
|
|
|
20
|
my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket_and_object (\@_); |
347
|
|
|
|
|
|
|
|
348
|
2
|
|
|
|
|
13
|
my $bucket = $self->bucket (delete $args{bucket}); |
349
|
2
|
|
|
|
|
12
|
return $bucket->get_key (%args); |
350
|
|
|
|
|
|
|
} |
351
|
|
|
|
|
|
|
|
352
|
|
|
|
|
|
|
# compat wrapper; deprecated as of 2005-03-23 |
353
|
|
|
|
|
|
|
sub head_key { |
354
|
1
|
|
|
1
|
0
|
4
|
my ( $self, $conf ) = @_; |
355
|
1
|
|
|
|
|
4
|
my $bucket = $self->bucket (delete $conf->{bucket}); |
356
|
1
|
|
|
|
|
6
|
return $bucket->head_key( $conf->{key} ); |
357
|
|
|
|
|
|
|
} |
358
|
|
|
|
|
|
|
|
359
|
|
|
|
|
|
|
# compat wrapper; deprecated as of 2005-03-23 |
360
|
|
|
|
|
|
|
sub delete_key { |
361
|
2
|
|
|
2
|
0
|
6
|
my $self = shift; |
362
|
2
|
|
|
|
|
11
|
my %args = Net::Amazon::S3::Utils->parse_arguments_with_bucket_and_object (\@_); |
363
|
|
|
|
|
|
|
|
364
|
2
|
|
|
|
|
11
|
my $bucket = $self->bucket (delete $args{bucket}); |
365
|
2
|
|
|
|
|
10
|
return $bucket->delete_key (%args); |
366
|
|
|
|
|
|
|
} |
367
|
|
|
|
|
|
|
|
368
|
|
|
|
|
|
|
sub _perform_operation { |
369
|
203
|
|
|
203
|
|
1018
|
my ($self, $operation, %params) = @_; |
370
|
|
|
|
|
|
|
|
371
|
203
|
|
|
|
|
610
|
my $error_handler = delete $params{error_handler}; |
372
|
203
|
100
|
|
|
|
3773
|
$error_handler = $self->error_handler unless defined $error_handler; |
373
|
|
|
|
|
|
|
|
374
|
203
|
|
|
|
|
710
|
my $request_class = $operation . '::Request'; |
375
|
203
|
|
|
|
|
510
|
my $response_class = $operation . '::Response'; |
376
|
203
|
|
|
|
|
541
|
my $filename = delete $params{filename}; |
377
|
|
|
|
|
|
|
|
378
|
203
|
|
|
|
|
9722
|
my $request = $request_class->new (s3 => $self, %params); |
379
|
203
|
|
|
|
|
5969
|
my $http_response = $self->ua->request ($request->http_request, $filename); |
380
|
203
|
|
|
|
|
172699
|
my $response = $response_class->new (http_response => $http_response); |
381
|
|
|
|
|
|
|
|
382
|
203
|
|
|
|
|
216454
|
$error_handler->handle_error ($response); |
383
|
|
|
|
|
|
|
|
384
|
135
|
|
|
|
|
5862
|
return $response; |
385
|
|
|
|
|
|
|
} |
386
|
|
|
|
|
|
|
|
387
|
|
|
|
|
|
|
sub _urlencode { |
388
|
387
|
|
|
387
|
|
944
|
my ( $self, $unencoded ) = @_; |
389
|
387
|
|
|
|
|
1488
|
return uri_escape_utf8( $unencoded, '^A-Za-z0-9_\-\.' ); |
390
|
|
|
|
|
|
|
} |
391
|
|
|
|
|
|
|
|
392
|
|
|
|
|
|
|
__PACKAGE__->meta->make_immutable; |
393
|
|
|
|
|
|
|
|
394
|
|
|
|
|
|
|
1; |
395
|
|
|
|
|
|
|
|
396
|
|
|
|
|
|
|
__END__ |
397
|
|
|
|
|
|
|
|
398
|
|
|
|
|
|
|
=pod |
399
|
|
|
|
|
|
|
|
400
|
|
|
|
|
|
|
=encoding UTF-8 |
401
|
|
|
|
|
|
|
|
402
|
|
|
|
|
|
|
=head1 NAME |
403
|
|
|
|
|
|
|
|
404
|
|
|
|
|
|
|
Net::Amazon::S3 - Use the Amazon S3 - Simple Storage Service |
405
|
|
|
|
|
|
|
|
406
|
|
|
|
|
|
|
=head1 VERSION |
407
|
|
|
|
|
|
|
|
408
|
|
|
|
|
|
|
version 0.98 |
409
|
|
|
|
|
|
|
|
410
|
|
|
|
|
|
|
=head1 SYNOPSIS |
411
|
|
|
|
|
|
|
|
412
|
|
|
|
|
|
|
use Net::Amazon::S3; |
413
|
|
|
|
|
|
|
use Net::Amazon::S3::Authorization::Basic; |
414
|
|
|
|
|
|
|
use Net::Amazon::S3::Authorization::IAM; |
415
|
|
|
|
|
|
|
my $aws_access_key_id = 'fill me in'; |
416
|
|
|
|
|
|
|
my $aws_secret_access_key = 'fill me in too'; |
417
|
|
|
|
|
|
|
|
418
|
|
|
|
|
|
|
my $s3 = Net::Amazon::S3->new ( |
419
|
|
|
|
|
|
|
authorization_context => Net::Amazon::S3::Authorization::Basic->new ( |
420
|
|
|
|
|
|
|
aws_access_key_id => $aws_access_key_id, |
421
|
|
|
|
|
|
|
aws_secret_access_key => $aws_secret_access_key, |
422
|
|
|
|
|
|
|
), |
423
|
|
|
|
|
|
|
retry => 1, |
424
|
|
|
|
|
|
|
); |
425
|
|
|
|
|
|
|
|
426
|
|
|
|
|
|
|
# or use an IAM role. |
427
|
|
|
|
|
|
|
my $s3 = Net::Amazon::S3->new ( |
428
|
|
|
|
|
|
|
authorization_context => Net::Amazon::S3::Authorization::IAM->new ( |
429
|
|
|
|
|
|
|
aws_access_key_id => $aws_access_key_id, |
430
|
|
|
|
|
|
|
aws_secret_access_key => $aws_secret_access_key, |
431
|
|
|
|
|
|
|
), |
432
|
|
|
|
|
|
|
retry => 1, |
433
|
|
|
|
|
|
|
); |
434
|
|
|
|
|
|
|
|
435
|
|
|
|
|
|
|
# a bucket is a globally-unique directory |
436
|
|
|
|
|
|
|
# list all buckets that i own |
437
|
|
|
|
|
|
|
my $response = $s3->buckets; |
438
|
|
|
|
|
|
|
foreach my $bucket ( @{ $response->{buckets} } ) { |
439
|
|
|
|
|
|
|
print "You have a bucket: " . $bucket->bucket . "\n"; |
440
|
|
|
|
|
|
|
} |
441
|
|
|
|
|
|
|
|
442
|
|
|
|
|
|
|
# create a new bucket |
443
|
|
|
|
|
|
|
my $bucketname = 'acmes_photo_backups'; |
444
|
|
|
|
|
|
|
my $bucket = $s3->add_bucket( { bucket => $bucketname } ) |
445
|
|
|
|
|
|
|
or die $s3->err . ": " . $s3->errstr; |
446
|
|
|
|
|
|
|
|
447
|
|
|
|
|
|
|
# or use an existing bucket |
448
|
|
|
|
|
|
|
$bucket = $s3->bucket($bucketname); |
449
|
|
|
|
|
|
|
|
450
|
|
|
|
|
|
|
# store a file in the bucket |
451
|
|
|
|
|
|
|
$bucket->add_key_filename( '1.JPG', 'DSC06256.JPG', |
452
|
|
|
|
|
|
|
{ content_type => 'image/jpeg', }, |
453
|
|
|
|
|
|
|
) or die $s3->err . ": " . $s3->errstr; |
454
|
|
|
|
|
|
|
|
455
|
|
|
|
|
|
|
# store a value in the bucket |
456
|
|
|
|
|
|
|
$bucket->add_key( 'reminder.txt', 'this is where my photos are backed up' ) |
457
|
|
|
|
|
|
|
or die $s3->err . ": " . $s3->errstr; |
458
|
|
|
|
|
|
|
|
459
|
|
|
|
|
|
|
# list files in the bucket |
460
|
|
|
|
|
|
|
$response = $bucket->list_all |
461
|
|
|
|
|
|
|
or die $s3->err . ": " . $s3->errstr; |
462
|
|
|
|
|
|
|
foreach my $key ( @{ $response->{keys} } ) { |
463
|
|
|
|
|
|
|
my $key_name = $key->{key}; |
464
|
|
|
|
|
|
|
my $key_size = $key->{size}; |
465
|
|
|
|
|
|
|
print "Bucket contains key '$key_name' of size $key_size\n"; |
466
|
|
|
|
|
|
|
} |
467
|
|
|
|
|
|
|
|
468
|
|
|
|
|
|
|
# fetch file from the bucket |
469
|
|
|
|
|
|
|
$response = $bucket->get_key_filename( '1.JPG', 'GET', 'backup.jpg' ) |
470
|
|
|
|
|
|
|
or die $s3->err . ": " . $s3->errstr; |
471
|
|
|
|
|
|
|
|
472
|
|
|
|
|
|
|
# fetch value from the bucket |
473
|
|
|
|
|
|
|
$response = $bucket->get_key('reminder.txt') |
474
|
|
|
|
|
|
|
or die $s3->err . ": " . $s3->errstr; |
475
|
|
|
|
|
|
|
print "reminder.txt:\n"; |
476
|
|
|
|
|
|
|
print " content length: " . $response->{content_length} . "\n"; |
477
|
|
|
|
|
|
|
print " content type: " . $response->{content_type} . "\n"; |
478
|
|
|
|
|
|
|
print " etag: " . $response->{content_type} . "\n"; |
479
|
|
|
|
|
|
|
print " content: " . $response->{value} . "\n"; |
480
|
|
|
|
|
|
|
|
481
|
|
|
|
|
|
|
# delete keys |
482
|
|
|
|
|
|
|
$bucket->delete_key('reminder.txt') or die $s3->err . ": " . $s3->errstr; |
483
|
|
|
|
|
|
|
$bucket->delete_key('1.JPG') or die $s3->err . ": " . $s3->errstr; |
484
|
|
|
|
|
|
|
|
485
|
|
|
|
|
|
|
# and finally delete the bucket |
486
|
|
|
|
|
|
|
$bucket->delete_bucket or die $s3->err . ": " . $s3->errstr; |
487
|
|
|
|
|
|
|
|
488
|
|
|
|
|
|
|
=head1 DESCRIPTION |
489
|
|
|
|
|
|
|
|
490
|
|
|
|
|
|
|
This module provides a Perlish interface to Amazon S3. From the |
491
|
|
|
|
|
|
|
developer blurb: "Amazon S3 is storage for the Internet. It is |
492
|
|
|
|
|
|
|
designed to make web-scale computing easier for developers. Amazon S3 |
493
|
|
|
|
|
|
|
provides a simple web services interface that can be used to store and |
494
|
|
|
|
|
|
|
retrieve any amount of data, at any time, from anywhere on the web. It |
495
|
|
|
|
|
|
|
gives any developer access to the same highly scalable, reliable, |
496
|
|
|
|
|
|
|
fast, inexpensive data storage infrastructure that Amazon uses to run |
497
|
|
|
|
|
|
|
its own global network of web sites. The service aims to maximize |
498
|
|
|
|
|
|
|
benefits of scale and to pass those benefits on to developers". |
499
|
|
|
|
|
|
|
|
500
|
|
|
|
|
|
|
To find out more about S3, please visit: http://s3.amazonaws.com/ |
501
|
|
|
|
|
|
|
|
502
|
|
|
|
|
|
|
To use this module you will need to sign up to Amazon Web Services and |
503
|
|
|
|
|
|
|
provide an "Access Key ID" and " Secret Access Key". If you use this |
504
|
|
|
|
|
|
|
module, you will incurr costs as specified by Amazon. Please check the |
505
|
|
|
|
|
|
|
costs. If you use this module with your Access Key ID and Secret |
506
|
|
|
|
|
|
|
Access Key you must be responsible for these costs. |
507
|
|
|
|
|
|
|
|
508
|
|
|
|
|
|
|
I highly recommend reading all about S3, but in a nutshell data is |
509
|
|
|
|
|
|
|
stored in values. Values are referenced by keys, and keys are stored |
510
|
|
|
|
|
|
|
in buckets. Bucket names are global. |
511
|
|
|
|
|
|
|
|
512
|
|
|
|
|
|
|
Note: This is the legacy interface, please check out |
513
|
|
|
|
|
|
|
L<Net::Amazon::S3::Client> instead. |
514
|
|
|
|
|
|
|
|
515
|
|
|
|
|
|
|
Development of this code happens here: https://github.com/rustyconover/net-amazon-s3 |
516
|
|
|
|
|
|
|
|
517
|
|
|
|
|
|
|
=head2 Bucket names with dots, HTTPS, and Signature V4 |
518
|
|
|
|
|
|
|
|
519
|
|
|
|
|
|
|
At the moment Amazon S3 doesn't play well with HTTPS and virtual bucket hosts |
520
|
|
|
|
|
|
|
if bucket name contains dots. |
521
|
|
|
|
|
|
|
|
522
|
|
|
|
|
|
|
Due the current implementation of Signature V4 handling you should use workaround |
523
|
|
|
|
|
|
|
consisting of usage of region hostnames |
524
|
|
|
|
|
|
|
|
525
|
|
|
|
|
|
|
my $bucket_region = $global_s3->bucket ($bucket)->_head_region; |
526
|
|
|
|
|
|
|
|
527
|
|
|
|
|
|
|
my $region_s3 = Net::Amazon:S3->new ( |
528
|
|
|
|
|
|
|
..., |
529
|
|
|
|
|
|
|
vendor => Net::Amazon::S3::Vendor::Amazon->new ( |
530
|
|
|
|
|
|
|
host => "s3-$bucket_region.amazonaws.com", |
531
|
|
|
|
|
|
|
use_virtual_host => 0, |
532
|
|
|
|
|
|
|
), |
533
|
|
|
|
|
|
|
); |
534
|
|
|
|
|
|
|
|
535
|
|
|
|
|
|
|
my $bucket = $region_s3->bucket ($bucket); |
536
|
|
|
|
|
|
|
|
537
|
|
|
|
|
|
|
And use bucket instance / region s3 connection. |
538
|
|
|
|
|
|
|
|
539
|
|
|
|
|
|
|
=head1 METHODS |
540
|
|
|
|
|
|
|
|
541
|
|
|
|
|
|
|
=head2 new |
542
|
|
|
|
|
|
|
|
543
|
|
|
|
|
|
|
Create a new S3 client object. Takes some arguments: |
544
|
|
|
|
|
|
|
|
545
|
|
|
|
|
|
|
=over |
546
|
|
|
|
|
|
|
|
547
|
|
|
|
|
|
|
=item authorization_context |
548
|
|
|
|
|
|
|
|
549
|
|
|
|
|
|
|
Class that provides authorization informations. |
550
|
|
|
|
|
|
|
|
551
|
|
|
|
|
|
|
See one of available implementations for more |
552
|
|
|
|
|
|
|
|
553
|
|
|
|
|
|
|
=over |
554
|
|
|
|
|
|
|
|
555
|
|
|
|
|
|
|
=item L<Net::Amazon::S3::Authorization::Basic> |
556
|
|
|
|
|
|
|
|
557
|
|
|
|
|
|
|
=item L<Net::Amazon::S3::Authorization::IAM> |
558
|
|
|
|
|
|
|
|
559
|
|
|
|
|
|
|
=back |
560
|
|
|
|
|
|
|
|
561
|
|
|
|
|
|
|
=item vendor |
562
|
|
|
|
|
|
|
|
563
|
|
|
|
|
|
|
Instance of L<Net::Amazon::S3::Vendor> holding vendor specific deviations. |
564
|
|
|
|
|
|
|
|
565
|
|
|
|
|
|
|
S3 became widely used object storage protocol with many vendors providing |
566
|
|
|
|
|
|
|
different feature sets and different compatibility level. |
567
|
|
|
|
|
|
|
|
568
|
|
|
|
|
|
|
One common difference is bucket's HEAD request to determine its region. |
569
|
|
|
|
|
|
|
|
570
|
|
|
|
|
|
|
To maintain currently known differences along with any differencies that |
571
|
|
|
|
|
|
|
may rise in feature it's better to hold vendor specification in dedicated |
572
|
|
|
|
|
|
|
classes. This also allows users to build their own fine-tuned vendor classes. |
573
|
|
|
|
|
|
|
|
574
|
|
|
|
|
|
|
=over |
575
|
|
|
|
|
|
|
|
576
|
|
|
|
|
|
|
=item L<Net::Amazon::S3::Vendor::Amazon> |
577
|
|
|
|
|
|
|
|
578
|
|
|
|
|
|
|
=item L<Net::Amazon::S3::Vendor::Generic> |
579
|
|
|
|
|
|
|
|
580
|
|
|
|
|
|
|
=back |
581
|
|
|
|
|
|
|
|
582
|
|
|
|
|
|
|
=item aws_access_key_id |
583
|
|
|
|
|
|
|
|
584
|
|
|
|
|
|
|
Deprecated. |
585
|
|
|
|
|
|
|
|
586
|
|
|
|
|
|
|
When used it's used to create authorization context. |
587
|
|
|
|
|
|
|
|
588
|
|
|
|
|
|
|
Use your Access Key ID as the value of the AWSAccessKeyId parameter |
589
|
|
|
|
|
|
|
in requests you send to Amazon Web Services (when required). Your |
590
|
|
|
|
|
|
|
Access Key ID identifies you as the party responsible for the |
591
|
|
|
|
|
|
|
request. |
592
|
|
|
|
|
|
|
|
593
|
|
|
|
|
|
|
=item aws_secret_access_key |
594
|
|
|
|
|
|
|
|
595
|
|
|
|
|
|
|
Deprecated. |
596
|
|
|
|
|
|
|
|
597
|
|
|
|
|
|
|
When used it's used to create authorization context. |
598
|
|
|
|
|
|
|
|
599
|
|
|
|
|
|
|
Since your Access Key ID is not encrypted in requests to AWS, it |
600
|
|
|
|
|
|
|
could be discovered and used by anyone. Services that are not free |
601
|
|
|
|
|
|
|
require you to provide additional information, a request signature, |
602
|
|
|
|
|
|
|
to verify that a request containing your unique Access Key ID could |
603
|
|
|
|
|
|
|
only have come from you. |
604
|
|
|
|
|
|
|
|
605
|
|
|
|
|
|
|
DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE. YOU'LL BE SORRY |
606
|
|
|
|
|
|
|
|
607
|
|
|
|
|
|
|
=item aws_session_token |
608
|
|
|
|
|
|
|
|
609
|
|
|
|
|
|
|
Deprecated. |
610
|
|
|
|
|
|
|
|
611
|
|
|
|
|
|
|
When used it's used to create authorization context. |
612
|
|
|
|
|
|
|
|
613
|
|
|
|
|
|
|
If you are using temporary credentials provided by the AWS Security Token |
614
|
|
|
|
|
|
|
Service, set the token here, and it will be added to the request in order to |
615
|
|
|
|
|
|
|
authenticate it. |
616
|
|
|
|
|
|
|
|
617
|
|
|
|
|
|
|
=item use_iam_role |
618
|
|
|
|
|
|
|
|
619
|
|
|
|
|
|
|
Deprecated. |
620
|
|
|
|
|
|
|
|
621
|
|
|
|
|
|
|
When used it's used to create authorization context. |
622
|
|
|
|
|
|
|
|
623
|
|
|
|
|
|
|
If you'd like to use IAM provided temporary credentials, pass this option |
624
|
|
|
|
|
|
|
with a true value. |
625
|
|
|
|
|
|
|
|
626
|
|
|
|
|
|
|
=item secure |
627
|
|
|
|
|
|
|
|
628
|
|
|
|
|
|
|
Deprecated. |
629
|
|
|
|
|
|
|
|
630
|
|
|
|
|
|
|
Set this to C<0> if you don't want to use SSL-encrypted connections when talking |
631
|
|
|
|
|
|
|
to S3. Defaults to C<1>. |
632
|
|
|
|
|
|
|
|
633
|
|
|
|
|
|
|
To use SSL-encrypted connections, LWP::Protocol::https is required. |
634
|
|
|
|
|
|
|
|
635
|
|
|
|
|
|
|
See L<#vendor> and L<Net::Amazon::S3::Vendor>. |
636
|
|
|
|
|
|
|
|
637
|
|
|
|
|
|
|
=item keep_alive_cache_size |
638
|
|
|
|
|
|
|
|
639
|
|
|
|
|
|
|
Set this to C<0> to disable Keep-Alives. Default is C<10>. |
640
|
|
|
|
|
|
|
|
641
|
|
|
|
|
|
|
=item timeout |
642
|
|
|
|
|
|
|
|
643
|
|
|
|
|
|
|
How many seconds should your script wait before bailing on a request to S3? Defaults |
644
|
|
|
|
|
|
|
to 30. |
645
|
|
|
|
|
|
|
|
646
|
|
|
|
|
|
|
=item retry |
647
|
|
|
|
|
|
|
|
648
|
|
|
|
|
|
|
If this library should retry upon errors. This option is recommended. |
649
|
|
|
|
|
|
|
This uses exponential backoff with retries after 1, 2, 4, 8, 16, 32 seconds, |
650
|
|
|
|
|
|
|
as recommended by Amazon. Defaults to off. |
651
|
|
|
|
|
|
|
|
652
|
|
|
|
|
|
|
=item host |
653
|
|
|
|
|
|
|
|
654
|
|
|
|
|
|
|
Deprecated. |
655
|
|
|
|
|
|
|
|
656
|
|
|
|
|
|
|
The S3 host endpoint to use. Defaults to 's3.amazonaws.com'. This allows |
657
|
|
|
|
|
|
|
you to connect to any S3-compatible host. |
658
|
|
|
|
|
|
|
|
659
|
|
|
|
|
|
|
See L<#vendor> and L<Net::Amazon::S3::Vendor>. |
660
|
|
|
|
|
|
|
|
661
|
|
|
|
|
|
|
=item use_virtual_host |
662
|
|
|
|
|
|
|
|
663
|
|
|
|
|
|
|
Deprecated. |
664
|
|
|
|
|
|
|
|
665
|
|
|
|
|
|
|
Use the virtual host method ('bucketname.s3.amazonaws.com') instead of specifying the |
666
|
|
|
|
|
|
|
bucket at the first part of the path. This is particularly useful if you want to access |
667
|
|
|
|
|
|
|
buckets not located in the US-Standard region (such as EU, Asia Pacific or South America). |
668
|
|
|
|
|
|
|
See L<http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html> for the pros and cons. |
669
|
|
|
|
|
|
|
|
670
|
|
|
|
|
|
|
See L<#vendor> and L<Net::Amazon::S3::Vendor>. |
671
|
|
|
|
|
|
|
|
672
|
|
|
|
|
|
|
=item authorization_method |
673
|
|
|
|
|
|
|
|
674
|
|
|
|
|
|
|
Deprecated. |
675
|
|
|
|
|
|
|
|
676
|
|
|
|
|
|
|
Authorization implementation package name. |
677
|
|
|
|
|
|
|
|
678
|
|
|
|
|
|
|
This library provides L<< Net::Amazon::S3::Signature::V2 >> and L<< Net::Amazon::S3::Signature::V4 >> |
679
|
|
|
|
|
|
|
|
680
|
|
|
|
|
|
|
Default is Signature 4 if host is C<< s3.amazonaws.com >>, Signature 2 otherwise |
681
|
|
|
|
|
|
|
|
682
|
|
|
|
|
|
|
See L<#vendor> and L<Net::Amazon::S3::Vendor>. |
683
|
|
|
|
|
|
|
|
684
|
|
|
|
|
|
|
=item error_handler_class |
685
|
|
|
|
|
|
|
|
686
|
|
|
|
|
|
|
Error handler class name (package name), see L<< Net::Amazon::S3::Error::Handler >> |
687
|
|
|
|
|
|
|
for more. |
688
|
|
|
|
|
|
|
|
689
|
|
|
|
|
|
|
Default: L<< Net::Amazon::S3::Error::Handler::Legacy >> |
690
|
|
|
|
|
|
|
|
691
|
|
|
|
|
|
|
=item error_handler |
692
|
|
|
|
|
|
|
|
693
|
|
|
|
|
|
|
Instance of error handler class. |
694
|
|
|
|
|
|
|
|
695
|
|
|
|
|
|
|
=back |
696
|
|
|
|
|
|
|
|
697
|
|
|
|
|
|
|
=head3 Notes |
698
|
|
|
|
|
|
|
|
699
|
|
|
|
|
|
|
When using L<Net::Amazon::S3> in child processes using fork (such as in |
700
|
|
|
|
|
|
|
combination with the excellent L<Parallel::ForkManager>) you should create the |
701
|
|
|
|
|
|
|
S3 object in each child, use a fresh LWP::UserAgent in each child, or disable |
702
|
|
|
|
|
|
|
the L<LWP::ConnCache> in the parent: |
703
|
|
|
|
|
|
|
|
704
|
|
|
|
|
|
|
$s3->ua( LWP::UserAgent->new( |
705
|
|
|
|
|
|
|
keep_alive => 0, requests_redirectable => [qw'GET HEAD DELETE PUT POST'] ); |
706
|
|
|
|
|
|
|
|
707
|
|
|
|
|
|
|
=head2 buckets |
708
|
|
|
|
|
|
|
|
709
|
|
|
|
|
|
|
Returns undef on error, else hashref of results |
710
|
|
|
|
|
|
|
|
711
|
|
|
|
|
|
|
=head2 add_bucket |
712
|
|
|
|
|
|
|
|
713
|
|
|
|
|
|
|
# Create new bucket with default location |
714
|
|
|
|
|
|
|
my $bucket = $s3->add_bucket ('new-bucket'); |
715
|
|
|
|
|
|
|
|
716
|
|
|
|
|
|
|
# Create new bucket in another location |
717
|
|
|
|
|
|
|
my $bucket = $s3->add_bucket ('new-bucket', location_constraint => 'eu-west-1'); |
718
|
|
|
|
|
|
|
my $bucket = $s3->add_bucket ('new-bucket', { location_constraint => 'eu-west-1' }); |
719
|
|
|
|
|
|
|
my $bucket = $s3->add_bucket (bucket => 'new-bucket', location_constraint => 'eu-west-1'); |
720
|
|
|
|
|
|
|
my $bucket = $s3->add_bucket ({ bucket => 'new-bucket', location_constraint => 'eu-west-1' }); |
721
|
|
|
|
|
|
|
|
722
|
|
|
|
|
|
|
Method creates and returns new bucket. |
723
|
|
|
|
|
|
|
|
724
|
|
|
|
|
|
|
In case of error it reports it and returns C<undef> (refer L</"ERROR HANDLING">). |
725
|
|
|
|
|
|
|
|
726
|
|
|
|
|
|
|
Recognized positional arguments (refer L</"CALLING CONVENTION">) |
727
|
|
|
|
|
|
|
|
728
|
|
|
|
|
|
|
=over |
729
|
|
|
|
|
|
|
|
730
|
|
|
|
|
|
|
=item bucket |
731
|
|
|
|
|
|
|
|
732
|
|
|
|
|
|
|
Required, recognized as positional. |
733
|
|
|
|
|
|
|
|
734
|
|
|
|
|
|
|
The name of the bucket you want to add. |
735
|
|
|
|
|
|
|
|
736
|
|
|
|
|
|
|
=back |
737
|
|
|
|
|
|
|
|
738
|
|
|
|
|
|
|
Recognized optional arguments |
739
|
|
|
|
|
|
|
|
740
|
|
|
|
|
|
|
=over |
741
|
|
|
|
|
|
|
|
742
|
|
|
|
|
|
|
=item acl |
743
|
|
|
|
|
|
|
|
744
|
|
|
|
|
|
|
acl => 'private' |
745
|
|
|
|
|
|
|
acl => Net::Amazon::S3::ACL::Canned->PRIVATE |
746
|
|
|
|
|
|
|
acl => Net::Amazon::S3::ACL::Set->grant_read (email => 'foo@bar.baz') |
747
|
|
|
|
|
|
|
|
748
|
|
|
|
|
|
|
I<Available since v0.94> |
749
|
|
|
|
|
|
|
|
750
|
|
|
|
|
|
|
Set ACL to the newly created bucket. Refer L<Net::Amazon::S3::ACL> for possibilities. |
751
|
|
|
|
|
|
|
|
752
|
|
|
|
|
|
|
=item acl_short (deprecated) |
753
|
|
|
|
|
|
|
|
754
|
|
|
|
|
|
|
I<Deprecated since v0.94> |
755
|
|
|
|
|
|
|
|
756
|
|
|
|
|
|
|
When specified its value is used to populate C<acl> argument (unless it exists). |
757
|
|
|
|
|
|
|
|
758
|
|
|
|
|
|
|
=item location_constraint |
759
|
|
|
|
|
|
|
|
760
|
|
|
|
|
|
|
Optional. |
761
|
|
|
|
|
|
|
|
762
|
|
|
|
|
|
|
Sets the location constraint of the new bucket. If left unspecified, the |
763
|
|
|
|
|
|
|
default S3 datacenter location will be used. |
764
|
|
|
|
|
|
|
|
765
|
|
|
|
|
|
|
This library recognizes regions according Amazon S3 documentation |
766
|
|
|
|
|
|
|
|
767
|
|
|
|
|
|
|
=over |
768
|
|
|
|
|
|
|
|
769
|
|
|
|
|
|
|
=item → |
770
|
|
|
|
|
|
|
|
771
|
|
|
|
|
|
|
L<https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region> |
772
|
|
|
|
|
|
|
|
773
|
|
|
|
|
|
|
=item → |
774
|
|
|
|
|
|
|
|
775
|
|
|
|
|
|
|
L<https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestSyntax> |
776
|
|
|
|
|
|
|
|
777
|
|
|
|
|
|
|
=back |
778
|
|
|
|
|
|
|
|
779
|
|
|
|
|
|
|
=back |
780
|
|
|
|
|
|
|
|
781
|
|
|
|
|
|
|
Provides operation L<CreateBucket|https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html>. |
782
|
|
|
|
|
|
|
|
783
|
|
|
|
|
|
|
=head2 bucket BUCKET |
784
|
|
|
|
|
|
|
|
785
|
|
|
|
|
|
|
Takes a scalar argument, the name of the bucket you're creating |
786
|
|
|
|
|
|
|
|
787
|
|
|
|
|
|
|
Returns an (unverified) bucket object from an account. Does no network access. |
788
|
|
|
|
|
|
|
|
789
|
|
|
|
|
|
|
=head2 delete_bucket |
790
|
|
|
|
|
|
|
|
791
|
|
|
|
|
|
|
$s3->delete_bucket ($bucket); |
792
|
|
|
|
|
|
|
$s3->delete_bucket (bucket => $bucket); |
793
|
|
|
|
|
|
|
|
794
|
|
|
|
|
|
|
Deletes bucket from account. |
795
|
|
|
|
|
|
|
|
796
|
|
|
|
|
|
|
Returns C<true> if the bucket is successfully deleted. |
797
|
|
|
|
|
|
|
|
798
|
|
|
|
|
|
|
Returns C<false> and reports an error otherwise (refer L</"ERROR HANDLING">) |
799
|
|
|
|
|
|
|
|
800
|
|
|
|
|
|
|
Positional arguments (refer L</"CALLING CONVENTION">) |
801
|
|
|
|
|
|
|
|
802
|
|
|
|
|
|
|
=over |
803
|
|
|
|
|
|
|
|
804
|
|
|
|
|
|
|
=item bucket |
805
|
|
|
|
|
|
|
|
806
|
|
|
|
|
|
|
Required. |
807
|
|
|
|
|
|
|
|
808
|
|
|
|
|
|
|
The name of the bucket or L<Net::Amazon::S3::Bucket> instance you want to delete. |
809
|
|
|
|
|
|
|
|
810
|
|
|
|
|
|
|
=back |
811
|
|
|
|
|
|
|
|
812
|
|
|
|
|
|
|
Provides operation L<"DeleteBucket"|https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html> |
813
|
|
|
|
|
|
|
|
814
|
|
|
|
|
|
|
=head2 list_bucket |
815
|
|
|
|
|
|
|
|
816
|
|
|
|
|
|
|
List all keys in this bucket. |
817
|
|
|
|
|
|
|
|
818
|
|
|
|
|
|
|
Takes a hashref of arguments: |
819
|
|
|
|
|
|
|
|
820
|
|
|
|
|
|
|
MANDATORY |
821
|
|
|
|
|
|
|
|
822
|
|
|
|
|
|
|
=over |
823
|
|
|
|
|
|
|
|
824
|
|
|
|
|
|
|
=item bucket |
825
|
|
|
|
|
|
|
|
826
|
|
|
|
|
|
|
The name of the bucket you want to list keys on |
827
|
|
|
|
|
|
|
|
828
|
|
|
|
|
|
|
=back |
829
|
|
|
|
|
|
|
|
830
|
|
|
|
|
|
|
OPTIONAL |
831
|
|
|
|
|
|
|
|
832
|
|
|
|
|
|
|
=over |
833
|
|
|
|
|
|
|
|
834
|
|
|
|
|
|
|
=item prefix |
835
|
|
|
|
|
|
|
|
836
|
|
|
|
|
|
|
Restricts the response to only contain results that begin with the |
837
|
|
|
|
|
|
|
specified prefix. If you omit this optional argument, the value of |
838
|
|
|
|
|
|
|
prefix for your query will be the empty string. In other words, the |
839
|
|
|
|
|
|
|
results will be not be restricted by prefix. |
840
|
|
|
|
|
|
|
|
841
|
|
|
|
|
|
|
=item delimiter |
842
|
|
|
|
|
|
|
|
843
|
|
|
|
|
|
|
If this optional, Unicode string parameter is included with your |
844
|
|
|
|
|
|
|
request, then keys that contain the same string between the prefix |
845
|
|
|
|
|
|
|
and the first occurrence of the delimiter will be rolled up into a |
846
|
|
|
|
|
|
|
single result element in the CommonPrefixes collection. These |
847
|
|
|
|
|
|
|
rolled-up keys are not returned elsewhere in the response. For |
848
|
|
|
|
|
|
|
example, with prefix="USA/" and delimiter="/", the matching keys |
849
|
|
|
|
|
|
|
"USA/Oregon/Salem" and "USA/Oregon/Portland" would be summarized |
850
|
|
|
|
|
|
|
in the response as a single "USA/Oregon" element in the CommonPrefixes |
851
|
|
|
|
|
|
|
collection. If an otherwise matching key does not contain the |
852
|
|
|
|
|
|
|
delimiter after the prefix, it appears in the Contents collection. |
853
|
|
|
|
|
|
|
|
854
|
|
|
|
|
|
|
Each element in the CommonPrefixes collection counts as one against |
855
|
|
|
|
|
|
|
the MaxKeys limit. The rolled-up keys represented by each CommonPrefixes |
856
|
|
|
|
|
|
|
element do not. If the Delimiter parameter is not present in your |
857
|
|
|
|
|
|
|
request, keys in the result set will not be rolled-up and neither |
858
|
|
|
|
|
|
|
the CommonPrefixes collection nor the NextMarker element will be |
859
|
|
|
|
|
|
|
present in the response. |
860
|
|
|
|
|
|
|
|
861
|
|
|
|
|
|
|
=item max-keys |
862
|
|
|
|
|
|
|
|
863
|
|
|
|
|
|
|
This optional argument limits the number of results returned in |
864
|
|
|
|
|
|
|
response to your query. Amazon S3 will return no more than this |
865
|
|
|
|
|
|
|
number of results, but possibly less. Even if max-keys is not |
866
|
|
|
|
|
|
|
specified, Amazon S3 will limit the number of results in the response. |
867
|
|
|
|
|
|
|
Check the IsTruncated flag to see if your results are incomplete. |
868
|
|
|
|
|
|
|
If so, use the Marker parameter to request the next page of results. |
869
|
|
|
|
|
|
|
For the purpose of counting max-keys, a 'result' is either a key |
870
|
|
|
|
|
|
|
in the 'Contents' collection, or a delimited prefix in the |
871
|
|
|
|
|
|
|
'CommonPrefixes' collection. So for delimiter requests, max-keys |
872
|
|
|
|
|
|
|
limits the total number of list results, not just the number of |
873
|
|
|
|
|
|
|
keys. |
874
|
|
|
|
|
|
|
|
875
|
|
|
|
|
|
|
=item marker |
876
|
|
|
|
|
|
|
|
877
|
|
|
|
|
|
|
This optional parameter enables pagination of large result sets. |
878
|
|
|
|
|
|
|
C<marker> specifies where in the result set to resume listing. It |
879
|
|
|
|
|
|
|
restricts the response to only contain results that occur alphabetically |
880
|
|
|
|
|
|
|
after the value of marker. To retrieve the next page of results, |
881
|
|
|
|
|
|
|
use the last key from the current page of results as the marker in |
882
|
|
|
|
|
|
|
your next request. |
883
|
|
|
|
|
|
|
|
884
|
|
|
|
|
|
|
See also C<next_marker>, below. |
885
|
|
|
|
|
|
|
|
886
|
|
|
|
|
|
|
If C<marker> is omitted,the first page of results is returned. |
887
|
|
|
|
|
|
|
|
888
|
|
|
|
|
|
|
=back |
889
|
|
|
|
|
|
|
|
890
|
|
|
|
|
|
|
Returns undef on error and a hashref of data on success: |
891
|
|
|
|
|
|
|
|
892
|
|
|
|
|
|
|
The hashref looks like this: |
893
|
|
|
|
|
|
|
|
894
|
|
|
|
|
|
|
{ |
895
|
|
|
|
|
|
|
bucket => $bucket_name, |
896
|
|
|
|
|
|
|
prefix => $bucket_prefix, |
897
|
|
|
|
|
|
|
common_prefixes => [$prefix1,$prefix2,...] |
898
|
|
|
|
|
|
|
marker => $bucket_marker, |
899
|
|
|
|
|
|
|
next_marker => $bucket_next_available_marker, |
900
|
|
|
|
|
|
|
max_keys => $bucket_max_keys, |
901
|
|
|
|
|
|
|
is_truncated => $bucket_is_truncated_boolean |
902
|
|
|
|
|
|
|
keys => [$key1,$key2,...] |
903
|
|
|
|
|
|
|
} |
904
|
|
|
|
|
|
|
|
905
|
|
|
|
|
|
|
Explanation of bits of that: |
906
|
|
|
|
|
|
|
|
907
|
|
|
|
|
|
|
=over |
908
|
|
|
|
|
|
|
|
909
|
|
|
|
|
|
|
=item common_prefixes |
910
|
|
|
|
|
|
|
|
911
|
|
|
|
|
|
|
If list_bucket was requested with a delimiter, common_prefixes will |
912
|
|
|
|
|
|
|
contain a list of prefixes matching that delimiter. Drill down into |
913
|
|
|
|
|
|
|
these prefixes by making another request with the prefix parameter. |
914
|
|
|
|
|
|
|
|
915
|
|
|
|
|
|
|
=item is_truncated |
916
|
|
|
|
|
|
|
|
917
|
|
|
|
|
|
|
B flag that indicates whether or not all results of your query were |
918
|
|
|
|
|
|
|
returned in this response. If your results were truncated, you can |
919
|
|
|
|
|
|
|
make a follow-up paginated request using the Marker parameter to |
920
|
|
|
|
|
|
|
retrieve the rest of the results. |
921
|
|
|
|
|
|
|
|
922
|
|
|
|
|
|
|
=item next_marker |
923
|
|
|
|
|
|
|
|
924
|
|
|
|
|
|
|
A convenience element, useful when paginating with delimiters. The |
925
|
|
|
|
|
|
|
value of C<next_marker>, if present, is the largest (alphabetically) |
926
|
|
|
|
|
|
|
of all key names and all CommonPrefixes prefixes in the response. |
927
|
|
|
|
|
|
|
If the C<is_truncated> flag is set, request the next page of results |
928
|
|
|
|
|
|
|
by setting C<marker> to the value of C<next_marker>. This element |
929
|
|
|
|
|
|
|
is only present in the response if the C<delimiter> parameter was |
930
|
|
|
|
|
|
|
sent with the request. |
931
|
|
|
|
|
|
|
|
932
|
|
|
|
|
|
|
=back |
933
|
|
|
|
|
|
|
|
934
|
|
|
|
|
|
|
Each key is a hashref that looks like this: |
935
|
|
|
|
|
|
|
|
936
|
|
|
|
|
|
|
{ |
937
|
|
|
|
|
|
|
key => $key, |
938
|
|
|
|
|
|
|
last_modified => $last_mod_date, |
939
|
|
|
|
|
|
|
etag => $etag, # An MD5 sum of the stored content. |
940
|
|
|
|
|
|
|
size => $size, # Bytes |
941
|
|
|
|
|
|
|
storage_class => $storage_class # Doc? |
942
|
|
|
|
|
|
|
owner_id => $owner_id, |
943
|
|
|
|
|
|
|
owner_displayname => $owner_name |
944
|
|
|
|
|
|
|
} |
945
|
|
|
|
|
|
|
|
946
|
|
|
|
|
|
|
=head2 list_bucket_all |
947
|
|
|
|
|
|
|
|
948
|
|
|
|
|
|
|
List all keys in this bucket without having to worry about |
949
|
|
|
|
|
|
|
'marker'. This is a convenience method, but may make multiple requests |
950
|
|
|
|
|
|
|
to S3 under the hood. |
951
|
|
|
|
|
|
|
|
952
|
|
|
|
|
|
|
Takes the same arguments as list_bucket. |
953
|
|
|
|
|
|
|
|
954
|
|
|
|
|
|
|
=head2 _perform_operation |
955
|
|
|
|
|
|
|
|
956
|
|
|
|
|
|
|
my $response = $s3->_perform_operation ('Operation' => ( |
957
|
|
|
|
|
|
|
# ... operation request parameters |
958
|
|
|
|
|
|
|
)); |
959
|
|
|
|
|
|
|
|
960
|
|
|
|
|
|
|
Internal operation implementation method, takes request construction parameters, |
961
|
|
|
|
|
|
|
performs necessary HTTP requests(s) and returns Response instance. |
962
|
|
|
|
|
|
|
|
963
|
|
|
|
|
|
|
Method takes same named parameters as realted Request class. |
964
|
|
|
|
|
|
|
|
965
|
|
|
|
|
|
|
Method provides available contextual parameters by default (eg s3, bucket) |
966
|
|
|
|
|
|
|
|
967
|
|
|
|
|
|
|
Method invokes contextual error handler. |
968
|
|
|
|
|
|
|
|
969
|
|
|
|
|
|
|
=head1 CALLING CONVENTION |
970
|
|
|
|
|
|
|
|
971
|
|
|
|
|
|
|
I<Available since v0.97> - calling convention extentend |
972
|
|
|
|
|
|
|
|
973
|
|
|
|
|
|
|
In order to make method calls somehow consistent, backward compatible, |
974
|
|
|
|
|
|
|
and extendable, API's methods support multiple ways how to provide their arguments |
975
|
|
|
|
|
|
|
|
976
|
|
|
|
|
|
|
=over |
977
|
|
|
|
|
|
|
|
978
|
|
|
|
|
|
|
=item plain named arguments (preferred) |
979
|
|
|
|
|
|
|
|
980
|
|
|
|
|
|
|
method (named => 'argument', another => 'argument'); |
981
|
|
|
|
|
|
|
|
982
|
|
|
|
|
|
|
=item trailing configuration hash |
983
|
|
|
|
|
|
|
|
984
|
|
|
|
|
|
|
method ({ named => 'argument', another => 'argument' }); |
985
|
|
|
|
|
|
|
method (positional, { named => 'argument', another => 'argument' } ); |
986
|
|
|
|
|
|
|
|
987
|
|
|
|
|
|
|
Last argument of every method can be configuration hash, treated as additional |
988
|
|
|
|
|
|
|
named arguments. Can be combined with named arguments. |
989
|
|
|
|
|
|
|
|
990
|
|
|
|
|
|
|
=item positional arguments with optional named arguments |
991
|
|
|
|
|
|
|
|
992
|
|
|
|
|
|
|
method (positional, named => 'argument', another => 'argument'); |
993
|
|
|
|
|
|
|
method (positional, { named => 'argument', another => 'argument' } ); |
994
|
|
|
|
|
|
|
|
995
|
|
|
|
|
|
|
For methods supporting mandatory positional arguments additional named |
996
|
|
|
|
|
|
|
arguments and/or configuration hash is supported. |
997
|
|
|
|
|
|
|
|
998
|
|
|
|
|
|
|
Named arguments or configuration hash can specify value of positional |
999
|
|
|
|
|
|
|
arguments as well removing it from list of required positional arguments |
1000
|
|
|
|
|
|
|
for given call (see example) |
1001
|
|
|
|
|
|
|
|
1002
|
|
|
|
|
|
|
$s3->bucket->add_key ('key', 'value', acl => $acl); |
1003
|
|
|
|
|
|
|
$s3->bucket->add_key ('value', key => 'key', acl => $acl); |
1004
|
|
|
|
|
|
|
$s3->bucket->add_key (key => 'key', value => 'value', acl => $acl); |
1005
|
|
|
|
|
|
|
|
1006
|
|
|
|
|
|
|
=back |
1007
|
|
|
|
|
|
|
|
1008
|
|
|
|
|
|
|
=head1 ERROR HANDLING |
1009
|
|
|
|
|
|
|
|
1010
|
|
|
|
|
|
|
L<Net::Amazon::S3> supports pluggable error handling via |
1011
|
|
|
|
|
|
|
L<Net::Amazon::S3::Error::Handler>. |
1012
|
|
|
|
|
|
|
|
1013
|
|
|
|
|
|
|
When response ends up with an error, every method reports it, and in case it |
1014
|
|
|
|
|
|
|
receives control back (no exception), it returns C<undef>. |
1015
|
|
|
|
|
|
|
|
1016
|
|
|
|
|
|
|
Default error handling for L<Net::Amazon::S3> is L<Net::Amazon::S3::Error::Handler::Legacy> |
1017
|
|
|
|
|
|
|
which (mostly) sets C<err> and C<errstr>. |
1018
|
|
|
|
|
|
|
|
1019
|
|
|
|
|
|
|
=head1 LICENSE |
1020
|
|
|
|
|
|
|
|
1021
|
|
|
|
|
|
|
This module contains code modified from Amazon that contains the |
1022
|
|
|
|
|
|
|
following notice: |
1023
|
|
|
|
|
|
|
|
1024
|
|
|
|
|
|
|
# This software code is made available "AS IS" without warranties of any |
1025
|
|
|
|
|
|
|
# kind. You may copy, display, modify and redistribute the software |
1026
|
|
|
|
|
|
|
# code either by itself or as incorporated into your code; provided that |
1027
|
|
|
|
|
|
|
# you do not remove any proprietary notices. Your use of this software |
1028
|
|
|
|
|
|
|
# code is at your own risk and you waive any claim against Amazon |
1029
|
|
|
|
|
|
|
# Digital Services, Inc. or its affiliates with respect to your use of |
1030
|
|
|
|
|
|
|
# this software code. (c) 2006 Amazon Digital Services, Inc. or its |
1031
|
|
|
|
|
|
|
# affiliates. |
1032
|
|
|
|
|
|
|
|
1033
|
|
|
|
|
|
|
=head1 TESTING |
1034
|
|
|
|
|
|
|
|
1035
|
|
|
|
|
|
|
Testing S3 is a tricky thing. Amazon wants to charge you a bit of |
1036
|
|
|
|
|
|
|
money each time you use their service. And yes, testing counts as using. |
1037
|
|
|
|
|
|
|
Because of this, the application's test suite skips anything approaching |
1038
|
|
|
|
|
|
|
a real test unless you set these three environment variables: |
1039
|
|
|
|
|
|
|
|
1040
|
|
|
|
|
|
|
=over |
1041
|
|
|
|
|
|
|
|
1042
|
|
|
|
|
|
|
=item AMAZON_S3_EXPENSIVE_TESTS |
1043
|
|
|
|
|
|
|
|
1044
|
|
|
|
|
|
|
Doesn't matter what you set it to. Just has to be set |
1045
|
|
|
|
|
|
|
|
1046
|
|
|
|
|
|
|
=item AWS_ACCESS_KEY_ID |
1047
|
|
|
|
|
|
|
|
1048
|
|
|
|
|
|
|
Your AWS access key |
1049
|
|
|
|
|
|
|
|
1050
|
|
|
|
|
|
|
=item AWS_ACCESS_KEY_SECRET |
1051
|
|
|
|
|
|
|
|
1052
|
|
|
|
|
|
|
Your AWS sekkr1t passkey. Be forewarned that setting this environment variable |
1053
|
|
|
|
|
|
|
on a shared system might leak that information to another user. Be careful. |
1054
|
|
|
|
|
|
|
|
1055
|
|
|
|
|
|
|
=back |
1056
|
|
|
|
|
|
|
|
1057
|
|
|
|
|
|
|
=head1 AUTHOR |
1058
|
|
|
|
|
|
|
|
1059
|
|
|
|
|
|
|
Leon Brocard <acme@astray.com> and unknown Amazon Digital Services programmers. |
1060
|
|
|
|
|
|
|
|
1061
|
|
|
|
|
|
|
Brad Fitzpatrick <brad@danga.com> - return values, Bucket object |
1062
|
|
|
|
|
|
|
|
1063
|
|
|
|
|
|
|
Pedro Figueiredo <me@pedrofigueiredo.org> - since 0.54 |
1064
|
|
|
|
|
|
|
|
1065
|
|
|
|
|
|
|
Branislav Zahradník <barney@cpan.org> - since v0.81 |
1066
|
|
|
|
|
|
|
|
1067
|
|
|
|
|
|
|
=head1 SEE ALSO |
1068
|
|
|
|
|
|
|
|
1069
|
|
|
|
|
|
|
L<Net::Amazon::S3::Bucket> |
1070
|
|
|
|
|
|
|
|
1071
|
|
|
|
|
|
|
=head1 AUTHOR |
1072
|
|
|
|
|
|
|
|
1073
|
|
|
|
|
|
|
Branislav Zahradník <barney@cpan.org> |
1074
|
|
|
|
|
|
|
|
1075
|
|
|
|
|
|
|
=head1 COPYRIGHT AND LICENSE |
1076
|
|
|
|
|
|
|
|
1077
|
|
|
|
|
|
|
This software is copyright (c) 2021 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník. |
1078
|
|
|
|
|
|
|
|
1079
|
|
|
|
|
|
|
This is free software; you can redistribute it and/or modify it under |
1080
|
|
|
|
|
|
|
the same terms as the Perl 5 programming language system itself. |
1081
|
|
|
|
|
|
|
|
1082
|
|
|
|
|
|
|
=cut |