]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | =================== |
2 | Bucket Operations | |
3 | =================== | |
4 | ||
5 | PUT Bucket | |
6 | ---------- | |
7 | Creates a new bucket. To create a bucket, you must have a user ID and a valid AWS Access Key ID to authenticate requests. You may not | |
8 | create buckets as an anonymous user. | |
9 | ||
10 | .. note:: We do not support request entities for ``PUT /{bucket}`` in this release. | |
11 | ||
12 | Constraints | |
13 | ~~~~~~~~~~~ | |
14 | In general, bucket names should follow domain name constraints. | |
15 | ||
16 | - Bucket names must be unique. | |
17 | - Bucket names must begin and end with a lowercase letter. | |
18 | - Bucket names may contain a dash (-). | |
19 | ||
20 | Syntax | |
21 | ~~~~~~ | |
22 | ||
23 | :: | |
24 | ||
25 | PUT /{bucket} HTTP/1.1 | |
26 | Host: cname.domain.com | |
27 | x-amz-acl: public-read-write | |
28 | ||
29 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
30 | ||
31 | Parameters | |
32 | ~~~~~~~~~~ | |
33 | ||
34 | +---------------+----------------------+-----------------------------------------------------------------------------+------------+ | |
35 | | Name | Description | Valid Values | Required | | |
36 | +===============+======================+=============================================================================+============+ | |
37 | | ``x-amz-acl`` | Canned ACLs. | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read`` | No | | |
38 | +---------------+----------------------+-----------------------------------------------------------------------------+------------+ | |
39 | ||
40 | ||
41 | ||
42 | HTTP Response | |
43 | ~~~~~~~~~~~~~ | |
44 | ||
45 | If the bucket name is unique, within constraints and unused, the operation will succeed. | |
46 | If a bucket with the same name already exists and the user is the bucket owner, the operation will succeed. | |
47 | If the bucket name is already in use, the operation will fail. | |
48 | ||
49 | +---------------+-----------------------+----------------------------------------------------------+ | |
50 | | HTTP Status | Status Code | Description | | |
51 | +===============+=======================+==========================================================+ | |
52 | | ``409`` | BucketAlreadyExists | Bucket already exists under different user's ownership. | | |
53 | +---------------+-----------------------+----------------------------------------------------------+ | |
54 | ||
55 | DELETE Bucket | |
56 | ------------- | |
57 | ||
58 | Deletes a bucket. You can reuse bucket names following a successful bucket removal. | |
59 | ||
60 | Syntax | |
61 | ~~~~~~ | |
62 | ||
63 | :: | |
64 | ||
65 | DELETE /{bucket} HTTP/1.1 | |
66 | Host: cname.domain.com | |
67 | ||
68 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
69 | ||
70 | HTTP Response | |
71 | ~~~~~~~~~~~~~ | |
72 | ||
73 | +---------------+---------------+------------------+ | |
74 | | HTTP Status | Status Code | Description | | |
75 | +===============+===============+==================+ | |
76 | | ``204`` | No Content | Bucket removed. | | |
77 | +---------------+---------------+------------------+ | |
78 | ||
79 | GET Bucket | |
80 | ---------- | |
81 | Returns a list of bucket objects. | |
82 | ||
83 | Syntax | |
84 | ~~~~~~ | |
85 | ||
86 | :: | |
87 | ||
88 | GET /{bucket}?max-keys=25 HTTP/1.1 | |
89 | Host: cname.domain.com | |
90 | ||
91 | Parameters | |
92 | ~~~~~~~~~~ | |
93 | ||
1adf2230 AA |
94 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ |
95 | | Name | Type | Description | | |
96 | +=====================+===========+=================================================================================================+ | |
97 | | ``prefix`` | String | Only returns objects that contain the specified prefix. | | |
98 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
99 | | ``delimiter`` | String | The delimiter between the prefix and the rest of the object name. | | |
100 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
101 | | ``marker`` | String | A beginning index for the list of objects returned. | | |
102 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
103 | | ``max-keys`` | Integer | The maximum number of keys to return. Default is 1000. | | |
104 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
105 | | ``allow-unordered`` | Boolean | Non-standard extension. Allows results to be returned unordered. Cannot be used with delimiter. | | |
106 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
7c673cae FG |
107 | |
108 | HTTP Response | |
109 | ~~~~~~~~~~~~~ | |
110 | ||
111 | +---------------+---------------+--------------------+ | |
112 | | HTTP Status | Status Code | Description | | |
113 | +===============+===============+====================+ | |
114 | | ``200`` | OK | Buckets retrieved | | |
115 | +---------------+---------------+--------------------+ | |
116 | ||
117 | Bucket Response Entities | |
118 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
119 | ``GET /{bucket}`` returns a container for buckets with the following fields. | |
120 | ||
121 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
122 | | Name | Type | Description | | |
123 | +========================+===========+==================================================================================+ | |
124 | | ``ListBucketResult`` | Entity | The container for the list of objects. | | |
125 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
126 | | ``Name`` | String | The name of the bucket whose contents will be returned. | | |
127 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
128 | | ``Prefix`` | String | A prefix for the object keys. | | |
129 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
130 | | ``Marker`` | String | A beginning index for the list of objects returned. | | |
131 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
132 | | ``MaxKeys`` | Integer | The maximum number of keys returned. | | |
133 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
134 | | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | | |
135 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
136 | | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's contents were returned. | | |
137 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
138 | | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | | |
139 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
140 | ||
141 | Object Response Entities | |
142 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
143 | The ``ListBucketResult`` contains objects, where each object is within a ``Contents`` container. | |
144 | ||
145 | +------------------------+-----------+------------------------------------------+ | |
146 | | Name | Type | Description | | |
147 | +========================+===========+==========================================+ | |
148 | | ``Contents`` | Object | A container for the object. | | |
149 | +------------------------+-----------+------------------------------------------+ | |
150 | | ``Key`` | String | The object's key. | | |
151 | +------------------------+-----------+------------------------------------------+ | |
152 | | ``LastModified`` | Date | The object's last-modified date/time. | | |
153 | +------------------------+-----------+------------------------------------------+ | |
154 | | ``ETag`` | String | An MD-5 hash of the object. (entity tag) | | |
155 | +------------------------+-----------+------------------------------------------+ | |
156 | | ``Size`` | Integer | The object's size. | | |
157 | +------------------------+-----------+------------------------------------------+ | |
158 | | ``StorageClass`` | String | Should always return ``STANDARD``. | | |
159 | +------------------------+-----------+------------------------------------------+ | |
11fdf7f2 TL |
160 | | ``Type`` | String | ``Appendable`` or ``Normal``. | |
161 | +------------------------+-----------+------------------------------------------+ | |
7c673cae FG |
162 | |
163 | Get Bucket Location | |
164 | ------------------- | |
165 | Retrieves the bucket's region. The user needs to be the bucket owner | |
166 | to call this. A bucket can be constrained to a region by providing | |
167 | ``LocationConstraint`` during a PUT request. | |
168 | ||
169 | Syntax | |
170 | ~~~~~~ | |
171 | Add the ``location`` subresource to bucket resource as shown below | |
172 | ||
173 | :: | |
174 | ||
175 | GET /{bucket}?location HTTP/1.1 | |
176 | Host: cname.domain.com | |
177 | ||
178 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
179 | ||
180 | Response Entities | |
181 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
182 | ||
183 | +------------------------+-----------+------------------------------------------+ | |
184 | | Name | Type | Description | | |
185 | +========================+===========+==========================================+ | |
186 | | ``LocationConstraint`` | String | The region where bucket resides, empty | | |
11fdf7f2 | 187 | | | | string for default region | |
7c673cae FG |
188 | +------------------------+-----------+------------------------------------------+ |
189 | ||
190 | ||
191 | ||
192 | Get Bucket ACL | |
193 | -------------- | |
194 | Retrieves the bucket access control list. The user needs to be the bucket | |
195 | owner or to have been granted ``READ_ACP`` permission on the bucket. | |
196 | ||
197 | Syntax | |
198 | ~~~~~~ | |
199 | Add the ``acl`` subresource to the bucket request as shown below. | |
200 | ||
201 | :: | |
202 | ||
203 | GET /{bucket}?acl HTTP/1.1 | |
204 | Host: cname.domain.com | |
205 | ||
206 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
207 | ||
208 | Response Entities | |
209 | ~~~~~~~~~~~~~~~~~ | |
210 | ||
211 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
212 | | Name | Type | Description | | |
213 | +===========================+=============+==============================================================================================+ | |
214 | | ``AccessControlPolicy`` | Container | A container for the response. | | |
215 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
216 | | ``AccessControlList`` | Container | A container for the ACL information. | | |
217 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
218 | | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | | |
219 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
220 | | ``ID`` | String | The bucket owner's ID. | | |
221 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
222 | | ``DisplayName`` | String | The bucket owner's display name. | | |
223 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
224 | | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | | |
225 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
226 | | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | | |
227 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
228 | | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | | |
229 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
230 | ||
231 | PUT Bucket ACL | |
232 | -------------- | |
233 | Sets an access control to an existing bucket. The user needs to be the bucket | |
234 | owner or to have been granted ``WRITE_ACP`` permission on the bucket. | |
235 | ||
236 | Syntax | |
237 | ~~~~~~ | |
238 | Add the ``acl`` subresource to the bucket request as shown below. | |
239 | ||
240 | :: | |
241 | ||
242 | PUT /{bucket}?acl HTTP/1.1 | |
243 | ||
244 | Request Entities | |
245 | ~~~~~~~~~~~~~~~~ | |
246 | ||
247 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
248 | | Name | Type | Description | | |
249 | +===========================+=============+==============================================================================================+ | |
250 | | ``AccessControlPolicy`` | Container | A container for the request. | | |
251 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
252 | | ``AccessControlList`` | Container | A container for the ACL information. | | |
253 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
254 | | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | | |
255 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
256 | | ``ID`` | String | The bucket owner's ID. | | |
257 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
258 | | ``DisplayName`` | String | The bucket owner's display name. | | |
259 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
260 | | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | | |
261 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
262 | | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | | |
263 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
264 | | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | | |
265 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
266 | ||
267 | List Bucket Multipart Uploads | |
268 | ----------------------------- | |
269 | ||
270 | ``GET /?uploads`` returns a list of the current in-progress multipart uploads--i.e., the application initiates a multipart upload, but | |
271 | the service hasn't completed all the uploads yet. | |
272 | ||
273 | Syntax | |
274 | ~~~~~~ | |
275 | ||
276 | :: | |
277 | ||
278 | GET /{bucket}?uploads HTTP/1.1 | |
279 | ||
280 | Parameters | |
281 | ~~~~~~~~~~ | |
282 | ||
283 | You may specify parameters for ``GET /{bucket}?uploads``, but none of them are required. | |
284 | ||
285 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
286 | | Name | Type | Description | | |
287 | +========================+===========+======================================================================================+ | |
288 | | ``prefix`` | String | Returns in-progress uploads whose keys contains the specified prefix. | | |
289 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
290 | | ``delimiter`` | String | The delimiter between the prefix and the rest of the object name. | | |
291 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
292 | | ``key-marker`` | String | The beginning marker for the list of uploads. | | |
293 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
294 | | ``max-keys`` | Integer | The maximum number of in-progress uploads. The default is 1000. | | |
295 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
296 | | ``max-uploads`` | Integer | The maximum number of multipart uploads. The range from 1-1000. The default is 1000. | | |
297 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
c07f9fc5 | 298 | | ``upload-id-marker`` | String | Ignored if ``key-marker`` is not specified. Specifies the ``ID`` of first | |
7c673cae FG |
299 | | | | upload to list in lexicographical order at or following the ``ID``. | |
300 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
301 | ||
302 | ||
303 | Response Entities | |
304 | ~~~~~~~~~~~~~~~~~ | |
305 | ||
306 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
307 | | Name | Type | Description | | |
308 | +=========================================+=============+==========================================================================================================+ | |
309 | | ``ListMultipartUploadsResult`` | Container | A container for the results. | | |
310 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
311 | | ``ListMultipartUploadsResult.Prefix`` | String | The prefix specified by the ``prefix`` request parameter (if any). | | |
312 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
313 | | ``Bucket`` | String | The bucket that will receive the bucket contents. | | |
314 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
315 | | ``KeyMarker`` | String | The key marker specified by the ``key-marker`` request parameter (if any). | | |
316 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
317 | | ``UploadIdMarker`` | String | The marker specified by the ``upload-id-marker`` request parameter (if any). | | |
318 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
319 | | ``NextKeyMarker`` | String | The key marker to use in a subsequent request if ``IsTruncated`` is ``true``. | | |
320 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
321 | | ``NextUploadIdMarker`` | String | The upload ID marker to use in a subsequent request if ``IsTruncated`` is ``true``. | | |
322 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
323 | | ``MaxUploads`` | Integer | The max uploads specified by the ``max-uploads`` request parameter. | | |
324 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
325 | | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | | |
326 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
327 | | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's upload contents were returned. | | |
328 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
329 | | ``Upload`` | Container | A container for ``Key``, ``UploadId``, ``InitiatorOwner``, ``StorageClass``, and ``Initiated`` elements. | | |
330 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
331 | | ``Key`` | String | The key of the object once the multipart upload is complete. | | |
332 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
333 | | ``UploadId`` | String | The ``ID`` that identifies the multipart upload. | | |
334 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
335 | | ``Initiator`` | Container | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload. | | |
336 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
337 | | ``DisplayName`` | String | The initiator's display name. | | |
338 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
339 | | ``ID`` | String | The initiator's ID. | | |
340 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
341 | | ``Owner`` | Container | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object. | | |
342 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
343 | | ``StorageClass`` | String | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY`` | | |
344 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
345 | | ``Initiated`` | Date | The date and time the user initiated the upload. | | |
346 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
347 | | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | | |
348 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
349 | | ``CommonPrefixes.Prefix`` | String | The substring of the key after the prefix as defined by the ``prefix`` request parameter. | | |
350 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
351 | ||
352 | ENABLE/SUSPEND BUCKET VERSIONING | |
353 | -------------------------------- | |
354 | ||
355 | ``PUT /?versioning`` This subresource set the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner. | |
356 | ||
357 | You can set the versioning state with one of the following values: | |
358 | ||
359 | - Enabled : Enables versioning for the objects in the bucket, All objects added to the bucket receive a unique version ID. | |
360 | - Suspended : Disables versioning for the objects in the bucket, All objects added to the bucket receive the version ID null. | |
361 | ||
362 | If the versioning state has never been set on a bucket, it has no versioning state; a GET versioning request does not return a versioning state value. | |
363 | ||
364 | Syntax | |
365 | ~~~~~~ | |
366 | ||
367 | :: | |
368 | ||
369 | PUT /{bucket}?versioning HTTP/1.1 | |
370 | ||
371 | REQUEST ENTITIES | |
372 | ~~~~~~~~~~~~~~~~ | |
373 | ||
374 | +-----------------------------+-----------+---------------------------------------------------------------------------+ | |
375 | | Name | Type | Description | | |
376 | +=============================+===========+===========================================================================+ | |
377 | | ``VersioningConfiguration`` | Container | A container for the request. | | |
378 | +-----------------------------+-----------+---------------------------------------------------------------------------+ | |
379 | | ``Status`` | String | Sets the versioning state of the bucket. Valid Values: Suspended/Enabled | | |
c07f9fc5 | 380 | +-----------------------------+-----------+---------------------------------------------------------------------------+ |