ceph/doc/radosgw/s3/bucketops.rst

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