1Net::Amazon::S3::FeaturUesse(r3)Contributed Perl DocumenNteatt:i:oAnmazon::S3::Features(3)
2
3
4

NAME

6       Net::Amazon::S3::Features - Features available in Net::Amazon::S3
7

VERSION

9       version 0.99
10

AUTHOR

12       Branislav Zahradník <barney@cpan.org>
13
15       This software is copyright (c) 2021 by Amazon Digital Services, Leon
16       Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav
17       Zahradník.
18
19       This is free software; you can redistribute it and/or modify it under
20       the same terms as the Perl 5 programming language system itself.
21

API COMPARISON

23       Net::Amazon::S3 supports two APIs with different feature support.
24
25       This document describes current behaviour.
26
27   Error reporting
28       Default error reporting method.
29
30       set S3 err
31           Operation returns expression evaluated as false and "err" with
32           "errstr" are populated from response content
33
34           See Net::Amazon::S3::Error::Handler::Status,
35           Net::Amazon::S3::Error::Handler::Legacy
36
37       set network error
38           Populates S3 err with "network_error" constant and S3 errstr with
39           http status line (eg: "404 Not Found") and throws.
40
41           See Net::Amazon::S3::Error::Handler::Legacy
42
43       confess
44           Operation throws using "confess"
45
46           See Net::Amazon::S3::Error::Handler::Confess
47
48   Feature support
49       For details see corresponding "api-operation" / "client-operation" test
50       file
51
52       List of "Amazon S3 Operations"
53       <https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html>
54
55        |-------------------------+---------------------------------+-----------------------------------|
56        | operation               | Net::Amazon::S3 (API)           | Net::Amazon::S3::Client           |
57        |-------------------------+---------------------------------+-----------------------------------|
58        | AbortMultipartUpload    | ❌                              | object->abort_multipart_upload    |
59        | returns                 | ❌                              | http response                     |
60        | errors                  | ❌                              | confess                           |
61        |-------------------------+---------------------------------+-----------------------------------|
62        | CompleteMultipartUpload | ❌                              | object->complete_multipart_upload |
63        | returns                 | ❌                              | http response                     |
64        | errors                  | ❌                              | confess                           |
65        |-------------------------+---------------------------------+-----------------------------------|
66        | CreateBucket            | s3->add_bucket                  | client->create_bucket             |
67        | - with region           | ✅                              | ✅                                |
68        | returns                 | Bucket instance                 | Bucket instance                   |
69        | errors                  | set S3 err                      | confess                           |
70        |-------------------------+---------------------------------+-----------------------------------|
71        | CreateMultipartUpload   | ❌                              | object->initiate_multipart_upload |
72        | returns                 | ❌                              | http response                     |
73        | errors                  | ❌                              | confess                           |
74        |-------------------------+---------------------------------+-----------------------------------|
75        | DeleteBucket            | s3->delete_bucket               | bucket->delete                    |
76        | returns                 | boolean                         | boolean                           |
77        | errors                  | set S3 err                      | confess                           |
78        |-------------------------+---------------------------------+-----------------------------------|
79        | DeleteBucketTagging     | bucket->delete_tags             | bucket->delete_tags               |
80        | returns                 | boolean                         | boolean                           |
81        | errors                  | set S3 err                      | confess                           |
82        |-------------------------+---------------------------------+-----------------------------------|
83        | DeleteObject            | bucket->delete_key              | bucket->object->delete            |
84        | returns                 | boolean                         | boolean                           |
85        | errors                  | set S3 err                      | confess                           |
86        |-------------------------+---------------------------------+-----------------------------------|
87        | DeleteObjects           | bucket->delete_multi_object     | bucket->delete_multi_object       |
88        | - auto chunks           | ✅                              | ✅                                |
89        | returns                 | boolean                         | HTTP::Response object             |
90        | errors                  | set S3 err                      | confess                           |
91        |-------------------------+---------------------------------+-----------------------------------|
92        | DeleteObjectTagging     | bucket->delete_tags             | bucket->object->delete_tags       |
93        | returns                 | boolean                         | boolean                           |
94        | errors                  | set S3 err                      | confess                           |
95        |-------------------------+---------------------------------+-----------------------------------|
96        | GetBucketAcl            | bucket->get_acl                 | bucket->acl                       |
97        | returns                 | response body (XML)             | response body (XML)               |
98        |                         | (undef on Not Found)            |                                   |
99        | errors                  | set network error               | confess                           |
100        |                         | (none on Not Found)             |                                   |
101        |-------------------------+---------------------------------+-----------------------------------|
102        | GetBucketLocation       | bucket->get_location_constraint | bucket->get_location_constraint   |
103        | returns                 | location (Str)                  | location (Str)                    |
104        | errors                  | set S3 err                      | confess                           |
105        |-------------------------+---------------------------------+-----------------------------------|
106        | GetObject               | bucket->get_key                 | bucket->object->get               |
107        | - into file             | ✅, bucket->get_key_filename    | ✅, bucket->object->get_filename  |
108        | - into callback         | ❌                              | ✅, bucket->object->get_callback  |
109        | returns                 | struct with value               | value                             |
110        |                         | (undef on Not Found)            |                                   |
111        | errors                  | set network error               | confess                           |
112        |                         | (none on Not Found)             |                                   |
113        |-------------------------+---------------------------------+-----------------------------------|
114        | GetObjectAcl            | bucket->get_acl                 | ❌                                |
115        | returns                 | response body (XML)             | ❌                                |
116        |                         | (undef on Not Found)            | ❌                                |
117        | errors                  | set network error               | ❌                                |
118        |                         | (none on Not Found)             | ❌                                |
119        |-------------------------+---------------------------------+-----------------------------------|
120        | ListBuckets             | s3->buckets                     | client->buckets                   |
121        | returns                 | Bucket instances in struct      | Bucket instances (list)           |
122        | errors                  | set S3 err                      | confess                           |
123        |-------------------------+---------------------------------+-----------------------------------|
124        | ListObjects             | s3->list_bucket                 | bucket->list                      |
125        | - common prefixes       | ✅                              | ❌                                |
126        | - list all              | ✅, s3->list_bucket_all         | ✅                                |
127        | returns                 | struct with list                | iterator (Object list)            |
128        | errors                  | set S3 err                      | confess during iteration          |
129        |-------------------------+---------------------------------+-----------------------------------|
130        | ListObjectsV2           | ❌                              | ❌                                |
131        |-------------------------+---------------------------------+-----------------------------------|
132        | ListParts               | ❌                              | ❌                                |
133        |-------------------------+---------------------------------+-----------------------------------|
134        | PutBucketAcl            | bucket->set_acl                 | bucket->set_acl                   |
135        | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
136        | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
137        | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
138        | returns                 | boolean                         | boolean                           |
139        | errors                  | set S3 err                      | confess                           |
140        |-------------------------+---------------------------------+-----------------------------------|
141        | PutBucketTagging        | bucket->add_tags                | bucket->add_tags                  |
142        | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
143        | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
144        | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
145        | returns                 | boolean                         | boolean                           |
146        | errors                  | set S3 err                      | confess                           |
147        |-------------------------+---------------------------------+-----------------------------------|
148        | PutObject               | bucket->add_key                 | bucket->object->put               |
149        | returns                 | boolean                         | empty string                      |
150        | errors                  | set S3 err                      | confess                           |
151        |-------------------------+---------------------------------+-----------------------------------|
152        | PutObjectAcl            | bucket->set_acl                 | object->set_acl                   |
153        | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
154        | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
155        | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
156        | returns                 | boolean                         | boolean                           |
157        | errors                  | set S3 err                      | confess                           |
158        |-------------------------+---------------------------------+-----------------------------------|
159        | PutObjectTagging        | bucket->add_tags                | bucket->object->add_tags          |
160        | - with canned acl       | ✅, as acl                      | ✅, as acl                        |
161        | - with explicit acl     | ✅, as acl                      | ✅, as acl                        |
162        | - with xml acl          | ✅, as acl_xml                  | ✅, as acl_xml                    |
163        | returns                 | boolean                         | boolean                           |
164        | errors                  | set S3 err                      | confess                           |
165        |-------------------------+---------------------------------+-----------------------------------|
166        | RestoreObject           | ❌                              | bucket->object->restore           |
167        | returns                 | ❌                              | http response                     |
168        | errors                  | ❌                              | confess                           |
169        |-------------------------+---------------------------------+-----------------------------------|
170        | UploadPart              | ❌                              | bucket->object->put_part          |
171        | - from value            | ❌                              | ✅                                |
172        | - from file             | ❌                              | ❌                                |
173        | - from file chunk       | ❌                              | ❌                                |
174        | returns                 | ❌                              | http response                     |
175        | errors                  | ❌                              | confess                           |
176        |-------------------------+---------------------------------+-----------------------------------|
177        | object-copy             | bucket->copy_key                | ❌                                |
178        | returns                 | boolean                         | ❌                                |
179        | errors                  | set S3 err                      | ❌                                |
180        |-------------------------+---------------------------------+-----------------------------------|
181        | object-head             |                                 | ❌                                |
182        | returns                 | boolean                         | ❌                                |
183        | errors                  | set S3 err                      | ❌                                |
184        |-------------------------+---------------------------------+-----------------------------------|
185
186   TODO plan (asorted, without time-plan)
187       unify features
188           Both APIs should support same set of operations
189
190       support all AWS S3 operations and x-amz-* headers
191           https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
192
193       add async API (AnyEvent / IO::Async)
194
195
196
197perl v5.34.0                      2022-01-21      Net::Amazon::S3::Features(3)
Impressum