]>
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 | ||
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 | ||
106 | ||
107 | HTTP Response | |
108 | ~~~~~~~~~~~~~ | |
109 | ||
110 | +---------------+---------------+--------------------+ | |
111 | | HTTP Status | Status Code | Description | | |
112 | +===============+===============+====================+ | |
113 | | ``200`` | OK | Buckets retrieved | | |
114 | +---------------+---------------+--------------------+ | |
115 | ||
116 | Bucket Response Entities | |
117 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
118 | ``GET /{bucket}`` returns a container for buckets with the following fields. | |
119 | ||
120 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
121 | | Name | Type | Description | | |
122 | +========================+===========+==================================================================================+ | |
123 | | ``ListBucketResult`` | Entity | The container for the list of objects. | | |
124 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
125 | | ``Name`` | String | The name of the bucket whose contents will be returned. | | |
126 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
127 | | ``Prefix`` | String | A prefix for the object keys. | | |
128 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
129 | | ``Marker`` | String | A beginning index for the list of objects returned. | | |
130 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
131 | | ``MaxKeys`` | Integer | The maximum number of keys returned. | | |
132 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
133 | | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | | |
134 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
135 | | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's contents were returned. | | |
136 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
137 | | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | | |
138 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
139 | ||
140 | Object Response Entities | |
141 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
142 | The ``ListBucketResult`` contains objects, where each object is within a ``Contents`` container. | |
143 | ||
144 | +------------------------+-----------+------------------------------------------+ | |
145 | | Name | Type | Description | | |
146 | +========================+===========+==========================================+ | |
147 | | ``Contents`` | Object | A container for the object. | | |
148 | +------------------------+-----------+------------------------------------------+ | |
149 | | ``Key`` | String | The object's key. | | |
150 | +------------------------+-----------+------------------------------------------+ | |
151 | | ``LastModified`` | Date | The object's last-modified date/time. | | |
152 | +------------------------+-----------+------------------------------------------+ | |
153 | | ``ETag`` | String | An MD-5 hash of the object. (entity tag) | | |
154 | +------------------------+-----------+------------------------------------------+ | |
155 | | ``Size`` | Integer | The object's size. | | |
156 | +------------------------+-----------+------------------------------------------+ | |
157 | | ``StorageClass`` | String | Should always return ``STANDARD``. | | |
158 | +------------------------+-----------+------------------------------------------+ | |
159 | ||
160 | Get Bucket Location | |
161 | ------------------- | |
162 | Retrieves the bucket's region. The user needs to be the bucket owner | |
163 | to call this. A bucket can be constrained to a region by providing | |
164 | ``LocationConstraint`` during a PUT request. | |
165 | ||
166 | Syntax | |
167 | ~~~~~~ | |
168 | Add the ``location`` subresource to bucket resource as shown below | |
169 | ||
170 | :: | |
171 | ||
172 | GET /{bucket}?location HTTP/1.1 | |
173 | Host: cname.domain.com | |
174 | ||
175 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
176 | ||
177 | Response Entities | |
178 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
179 | ||
180 | +------------------------+-----------+------------------------------------------+ | |
181 | | Name | Type | Description | | |
182 | +========================+===========+==========================================+ | |
183 | | ``LocationConstraint`` | String | The region where bucket resides, empty | | |
184 | | | | string for defult region | | |
185 | +------------------------+-----------+------------------------------------------+ | |
186 | ||
187 | ||
188 | ||
189 | Get Bucket ACL | |
190 | -------------- | |
191 | Retrieves the bucket access control list. The user needs to be the bucket | |
192 | owner or to have been granted ``READ_ACP`` permission on the bucket. | |
193 | ||
194 | Syntax | |
195 | ~~~~~~ | |
196 | Add the ``acl`` subresource to the bucket request as shown below. | |
197 | ||
198 | :: | |
199 | ||
200 | GET /{bucket}?acl HTTP/1.1 | |
201 | Host: cname.domain.com | |
202 | ||
203 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
204 | ||
205 | Response Entities | |
206 | ~~~~~~~~~~~~~~~~~ | |
207 | ||
208 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
209 | | Name | Type | Description | | |
210 | +===========================+=============+==============================================================================================+ | |
211 | | ``AccessControlPolicy`` | Container | A container for the response. | | |
212 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
213 | | ``AccessControlList`` | Container | A container for the ACL information. | | |
214 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
215 | | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | | |
216 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
217 | | ``ID`` | String | The bucket owner's ID. | | |
218 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
219 | | ``DisplayName`` | String | The bucket owner's display name. | | |
220 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
221 | | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | | |
222 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
223 | | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | | |
224 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
225 | | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | | |
226 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
227 | ||
228 | PUT Bucket ACL | |
229 | -------------- | |
230 | Sets an access control to an existing bucket. The user needs to be the bucket | |
231 | owner or to have been granted ``WRITE_ACP`` permission on the bucket. | |
232 | ||
233 | Syntax | |
234 | ~~~~~~ | |
235 | Add the ``acl`` subresource to the bucket request as shown below. | |
236 | ||
237 | :: | |
238 | ||
239 | PUT /{bucket}?acl HTTP/1.1 | |
240 | ||
241 | Request Entities | |
242 | ~~~~~~~~~~~~~~~~ | |
243 | ||
244 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
245 | | Name | Type | Description | | |
246 | +===========================+=============+==============================================================================================+ | |
247 | | ``AccessControlPolicy`` | Container | A container for the request. | | |
248 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
249 | | ``AccessControlList`` | Container | A container for the ACL information. | | |
250 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
251 | | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | | |
252 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
253 | | ``ID`` | String | The bucket owner's ID. | | |
254 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
255 | | ``DisplayName`` | String | The bucket owner's display name. | | |
256 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
257 | | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | | |
258 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
259 | | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | | |
260 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
261 | | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | | |
262 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
263 | ||
264 | List Bucket Multipart Uploads | |
265 | ----------------------------- | |
266 | ||
267 | ``GET /?uploads`` returns a list of the current in-progress multipart uploads--i.e., the application initiates a multipart upload, but | |
268 | the service hasn't completed all the uploads yet. | |
269 | ||
270 | Syntax | |
271 | ~~~~~~ | |
272 | ||
273 | :: | |
274 | ||
275 | GET /{bucket}?uploads HTTP/1.1 | |
276 | ||
277 | Parameters | |
278 | ~~~~~~~~~~ | |
279 | ||
280 | You may specify parameters for ``GET /{bucket}?uploads``, but none of them are required. | |
281 | ||
282 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
283 | | Name | Type | Description | | |
284 | +========================+===========+======================================================================================+ | |
285 | | ``prefix`` | String | Returns in-progress uploads whose keys contains the specified prefix. | | |
286 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
287 | | ``delimiter`` | String | The delimiter between the prefix and the rest of the object name. | | |
288 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
289 | | ``key-marker`` | String | The beginning marker for the list of uploads. | | |
290 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
291 | | ``max-keys`` | Integer | The maximum number of in-progress uploads. The default is 1000. | | |
292 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
293 | | ``max-uploads`` | Integer | The maximum number of multipart uploads. The range from 1-1000. The default is 1000. | | |
294 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
c07f9fc5 | 295 | | ``upload-id-marker`` | String | Ignored if ``key-marker`` is not specified. Specifies the ``ID`` of first | |
7c673cae FG |
296 | | | | upload to list in lexicographical order at or following the ``ID``. | |
297 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
298 | ||
299 | ||
300 | Response Entities | |
301 | ~~~~~~~~~~~~~~~~~ | |
302 | ||
303 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
304 | | Name | Type | Description | | |
305 | +=========================================+=============+==========================================================================================================+ | |
306 | | ``ListMultipartUploadsResult`` | Container | A container for the results. | | |
307 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
308 | | ``ListMultipartUploadsResult.Prefix`` | String | The prefix specified by the ``prefix`` request parameter (if any). | | |
309 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
310 | | ``Bucket`` | String | The bucket that will receive the bucket contents. | | |
311 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
312 | | ``KeyMarker`` | String | The key marker specified by the ``key-marker`` request parameter (if any). | | |
313 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
314 | | ``UploadIdMarker`` | String | The marker specified by the ``upload-id-marker`` request parameter (if any). | | |
315 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
316 | | ``NextKeyMarker`` | String | The key marker to use in a subsequent request if ``IsTruncated`` is ``true``. | | |
317 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
318 | | ``NextUploadIdMarker`` | String | The upload ID marker to use in a subsequent request if ``IsTruncated`` is ``true``. | | |
319 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
320 | | ``MaxUploads`` | Integer | The max uploads specified by the ``max-uploads`` request parameter. | | |
321 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
322 | | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | | |
323 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
324 | | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's upload contents were returned. | | |
325 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
326 | | ``Upload`` | Container | A container for ``Key``, ``UploadId``, ``InitiatorOwner``, ``StorageClass``, and ``Initiated`` elements. | | |
327 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
328 | | ``Key`` | String | The key of the object once the multipart upload is complete. | | |
329 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
330 | | ``UploadId`` | String | The ``ID`` that identifies the multipart upload. | | |
331 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
332 | | ``Initiator`` | Container | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload. | | |
333 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
334 | | ``DisplayName`` | String | The initiator's display name. | | |
335 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
336 | | ``ID`` | String | The initiator's ID. | | |
337 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
338 | | ``Owner`` | Container | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object. | | |
339 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
340 | | ``StorageClass`` | String | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY`` | | |
341 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
342 | | ``Initiated`` | Date | The date and time the user initiated the upload. | | |
343 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
344 | | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | | |
345 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
346 | | ``CommonPrefixes.Prefix`` | String | The substring of the key after the prefix as defined by the ``prefix`` request parameter. | | |
347 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
348 | ||
349 | ENABLE/SUSPEND BUCKET VERSIONING | |
350 | -------------------------------- | |
351 | ||
352 | ``PUT /?versioning`` This subresource set the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner. | |
353 | ||
354 | You can set the versioning state with one of the following values: | |
355 | ||
356 | - Enabled : Enables versioning for the objects in the bucket, All objects added to the bucket receive a unique version ID. | |
357 | - Suspended : Disables versioning for the objects in the bucket, All objects added to the bucket receive the version ID null. | |
358 | ||
359 | 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. | |
360 | ||
361 | Syntax | |
362 | ~~~~~~ | |
363 | ||
364 | :: | |
365 | ||
366 | PUT /{bucket}?versioning HTTP/1.1 | |
367 | ||
368 | REQUEST ENTITIES | |
369 | ~~~~~~~~~~~~~~~~ | |
370 | ||
371 | +-----------------------------+-----------+---------------------------------------------------------------------------+ | |
372 | | Name | Type | Description | | |
373 | +=============================+===========+===========================================================================+ | |
374 | | ``VersioningConfiguration`` | Container | A container for the request. | | |
375 | +-----------------------------+-----------+---------------------------------------------------------------------------+ | |
376 | | ``Status`` | String | Sets the versioning state of the bucket. Valid Values: Suspended/Enabled | | |
c07f9fc5 | 377 | +-----------------------------+-----------+---------------------------------------------------------------------------+ |