src/ceph/doc/radosgw/s3/objectops.rst

   1 Object Operations
   2 =================
   3
   4 Put Object
   5 ----------
   6 Adds an object to a bucket. You must have write permissions on the bucket to perform this operation.
   7
   8
   9 Syntax
  10 ~~~~~~
  11
  12 ::
  13
  14     PUT /{bucket}/{object} HTTP/1.1
  15
  16 Request Headers
  17 ~~~~~~~~~~~~~~~
  18
  19 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
  20 | Name                 | Description                                | Valid Values                                                                  | Required   |
  21 +======================+============================================+===============================================================================+============+
  22 | **content-md5**      | A base64 encoded MD-5 hash of the message. | A string. No defaults or constraints.                                         | No         |
  23 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
  24 | **content-type**     | A standard MIME type.                      | Any MIME type. Default: ``binary/octet-stream``                               | No         |
  25 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
  26 | **x-amz-meta-<...>** | User metadata.  Stored with the object.    | A string up to 8kb. No defaults.                                              | No         |
  27 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
  28 | **x-amz-acl**        | A canned ACL.                              | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read``   | No         |
  29 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
  30
  31
  32 Copy Object
  33 -----------
  34 To copy an object, use ``PUT`` and specify a destination bucket and the object name.
  35
  36 Syntax
  37 ~~~~~~
  38
  39 ::
  40
  41     PUT /{dest-bucket}/{dest-object} HTTP/1.1
  42     x-amz-copy-source: {source-bucket}/{source-object}
  43
  44 Request Headers
  45 ~~~~~~~~~~~~~~~
  46
  47 +--------------------------------------+-------------------------------------------------+------------------------+------------+
  48 | Name                                 | Description                                     | Valid Values           | Required   |
  49 +======================================+=================================================+========================+============+
  50 | **x-amz-copy-source**                | The source bucket name + object name.           | {bucket}/{obj}         | Yes        |
  51 +--------------------------------------+-------------------------------------------------+------------------------+------------+
  52 | **x-amz-acl**                        | A canned ACL.                                   | ``private``,           | No         |
  53 |                                      |                                                 | ``public-read``,       |            |
  54 |                                      |                                                 | ``public-read-write``, |            |
  55 |                                      |                                                 | ``authenticated-read`` |            |
  56 +--------------------------------------+-------------------------------------------------+------------------------+------------+
  57 | **x-amz-copy-if-modified-since**     |  Copies only if modified since the timestamp.   |   Timestamp            | No         |
  58 +--------------------------------------+-------------------------------------------------+------------------------+------------+
  59 | **x-amz-copy-if-unmodified-since**   |  Copies only if unmodified since the timestamp. |   Timestamp            | No         |
  60 +--------------------------------------+-------------------------------------------------+------------------------+------------+
  61 | **x-amz-copy-if-match**              |  Copies only if object ETag matches ETag.       |   Entity Tag           | No         |
  62 +--------------------------------------+-------------------------------------------------+------------------------+------------+
  63 | **x-amz-copy-if-none-match**         |  Copies only if object ETag doesn't match.      |   Entity Tag           | No         |
  64 +--------------------------------------+-------------------------------------------------+------------------------+------------+
  65
  66 Response Entities
  67 ~~~~~~~~~~~~~~~~~
  68
  69 +------------------------+-------------+-----------------------------------------------+
  70 | Name                   | Type        | Description                                   |
  71 +========================+=============+===============================================+
  72 | **CopyObjectResult**   | Container   |  A container for the response elements.       |
  73 +------------------------+-------------+-----------------------------------------------+
  74 | **LastModified**       | Date        |  The last modified date of the source object. |
  75 +------------------------+-------------+-----------------------------------------------+
  76 | **Etag**               | String      |  The ETag of the new object.                  |
  77 +------------------------+-------------+-----------------------------------------------+
  78
  79 Remove Object
  80 -------------
  81
  82 Removes an object. Requires WRITE permission set on the containing bucket.
  83
  84 Syntax
  85 ~~~~~~
  86
  87 ::
  88
  89     DELETE /{bucket}/{object} HTTP/1.1
  90
  91
  92
  93 Get Object
  94 ----------
  95 Retrieves an object from a bucket within RADOS.
  96
  97 Syntax
  98 ~~~~~~
  99
 100 ::
 101
 102     GET /{bucket}/{object} HTTP/1.1
 103
 104 Request Headers
 105 ~~~~~~~~~~~~~~~
 106
 107 +---------------------------+------------------------------------------------+--------------------------------+------------+
 108 | Name                      | Description                                    | Valid Values                   | Required   |
 109 +===========================+================================================+================================+============+
 110 | **range**                 | The range of the object to retrieve.           | Range: bytes=beginbyte-endbyte | No         |
 111 +---------------------------+------------------------------------------------+--------------------------------+------------+
 112 | **if-modified-since**     | Gets only if modified since the timestamp.     | Timestamp                      | No         |
 113 +---------------------------+------------------------------------------------+--------------------------------+------------+
 114 | **if-unmodified-since**   | Gets only if not modified since the timestamp. | Timestamp                      | No         |
 115 +---------------------------+------------------------------------------------+--------------------------------+------------+
 116 | **if-match**              | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
 117 +---------------------------+------------------------------------------------+--------------------------------+------------+
 118 | **if-none-match**         | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
 119 +---------------------------+------------------------------------------------+--------------------------------+------------+
 120
 121 Response Headers
 122 ~~~~~~~~~~~~~~~~
 123
 124 +-------------------+--------------------------------------------------------------------------------------------+
 125 | Name              | Description                                                                                |
 126 +===================+============================================================================================+
 127 | **Content-Range** | Data range, will only be returned if the range header field was specified in the request   |
 128 +-------------------+--------------------------------------------------------------------------------------------+
 129
 130 Get Object Info
 131 ---------------
 132
 133 Returns information about object. This request will return the same
 134 header information as with the Get Object request, but will include
 135 the metadata only, not the object data payload.
 136
 137 Syntax
 138 ~~~~~~
 139
 140 ::
 141
 142     HEAD /{bucket}/{object} HTTP/1.1
 143
 144 Request Headers
 145 ~~~~~~~~~~~~~~~
 146
 147 +---------------------------+------------------------------------------------+--------------------------------+------------+
 148 | Name                      | Description                                    | Valid Values                   | Required   |
 149 +===========================+================================================+================================+============+
 150 | **range**                 | The range of the object to retrieve.           | Range: bytes=beginbyte-endbyte | No         |
 151 +---------------------------+------------------------------------------------+--------------------------------+------------+
 152 | **if-modified-since**     | Gets only if modified since the timestamp.     | Timestamp                      | No         |
 153 +---------------------------+------------------------------------------------+--------------------------------+------------+
 154 | **if-unmodified-since**   | Gets only if not modified since the timestamp. | Timestamp                      | No         |
 155 +---------------------------+------------------------------------------------+--------------------------------+------------+
 156 | **if-match**              | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
 157 +---------------------------+------------------------------------------------+--------------------------------+------------+
 158 | **if-none-match**         | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
 159 +---------------------------+------------------------------------------------+--------------------------------+------------+
 160
 161 Get Object ACL
 162 --------------
 163
 164 Syntax
 165 ~~~~~~
 166
 167 ::
 168
 169     GET /{bucket}/{object}?acl HTTP/1.1
 170
 171 Response Entities
 172 ~~~~~~~~~~~~~~~~~
 173
 174 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 175 | Name                      | Type        | Description                                                                                  |
 176 +===========================+=============+==============================================================================================+
 177 | ``AccessControlPolicy``   | Container   | A container for the response.                                                                |
 178 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 179 | ``AccessControlList``     | Container   | A container for the ACL information.                                                         |
 180 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 181 | ``Owner``                 | Container   | A container for the object owner's ``ID`` and ``DisplayName``.                               |
 182 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 183 | ``ID``                    | String      | The object owner's ID.                                                                       |
 184 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 185 | ``DisplayName``           | String      | The object owner's display name.                                                             |
 186 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 187 | ``Grant``                 | Container   | A container for ``Grantee`` and ``Permission``.                                              |
 188 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 189 | ``Grantee``               | Container   | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission.  |
 190 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 191 | ``Permission``            | String      | The permission given to the ``Grantee`` object.                                              |
 192 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 193
 194
 195
 196 Set Object ACL
 197 --------------
 198
 199 Syntax
 200 ~~~~~~
 201
 202 ::
 203
 204     PUT /{bucket}/{object}?acl
 205
 206 Request 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 object owner's ``ID`` and ``DisplayName``.                               |
 217 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 218 | ``ID``                    | String      | The object owner's ID.                                                                       |
 219 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 220 | ``DisplayName``           | String      | The object 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`` object.                                              |
 227 +---------------------------+-------------+----------------------------------------------------------------------------------------------+
 228
 229
 230
 231 Initiate Multi-part Upload
 232 --------------------------
 233
 234 Initiate a multi-part upload process.
 235
 236 Syntax
 237 ~~~~~~
 238
 239 ::
 240
 241     POST /{bucket}/{object}?uploads
 242
 243 Request Headers
 244 ~~~~~~~~~~~~~~~
 245
 246 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
 247 | Name                 | Description                                | Valid Values                                                                  | Required   |
 248 +======================+============================================+===============================================================================+============+
 249 | **content-md5**      | A base64 encoded MD-5 hash of the message. | A string. No defaults or constraints.                                         | No         |
 250 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
 251 | **content-type**     | A standard MIME type.                      | Any MIME type. Default: ``binary/octet-stream``                               | No         |
 252 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
 253 | **x-amz-meta-<...>** | User metadata.  Stored with the object.    | A string up to 8kb. No defaults.                                              | No         |
 254 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
 255 | **x-amz-acl**        | A canned ACL.                              | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read``   | No         |
 256 +----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
 257
 258
 259 Response Entities
 260 ~~~~~~~~~~~~~~~~~
 261
 262 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 263 | Name                                    | Type        | Description                                                                                              |
 264 +=========================================+=============+==========================================================================================================+
 265 | ``InitiatedMultipartUploadsResult``     | Container   | A container for the results.                                                                             |
 266 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 267 | ``Bucket``                              | String      | The bucket that will receive the object contents.                                                        |
 268 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 269 | ``Key``                                 | String      | The key specified by the ``key`` request parameter (if any).                                             |
 270 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 271 | ``UploadId``                            | String      | The ID specified by the ``upload-id`` request parameter identifying the multipart upload (if any).       |
 272 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 273
 274
 275 Multipart Upload Part
 276 ---------------------
 277
 278 Syntax
 279 ~~~~~~
 280
 281 ::
 282
 283     PUT /{bucket}/{object}?partNumber=&uploadId= HTTP/1.1
 284
 285 HTTP Response
 286 ~~~~~~~~~~~~~
 287
 288 The following HTTP response may be returned:
 289
 290 +---------------+----------------+--------------------------------------------------------------------------+
 291 | HTTP Status   | Status Code    | Description                                                              |
 292 +===============+================+==========================================================================+
 293 | **404**       | NoSuchUpload   | Specified upload-id does not match any initiated upload on this object   |
 294 +---------------+----------------+--------------------------------------------------------------------------+
 295
 296 List Multipart Upload Parts
 297 ---------------------------
 298
 299 Syntax
 300 ~~~~~~
 301
 302 ::
 303
 304     GET /{bucket}/{object}?uploadId=123 HTTP/1.1
 305
 306 Response Entities
 307 ~~~~~~~~~~~~~~~~~
 308
 309 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 310 | Name                                    | Type        | Description                                                                                              |
 311 +=========================================+=============+==========================================================================================================+
 312 | ``ListPartsResult``                     | Container   | A container for the results.                                                                             |
 313 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 314 | ``Bucket``                              | String      | The bucket that will receive the object contents.                                                        |
 315 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 316 | ``Key``                                 | String      | The key specified by the ``key`` request parameter (if any).                                             |
 317 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 318 | ``UploadId``                            | String      | The ID specified by the ``upload-id`` request parameter identifying the multipart upload (if any).       |
 319 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 320 | ``Initiator``                           | Container   | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload.                            |
 321 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 322 | ``ID``                                  | String      | The initiator's ID.                                                                                      |
 323 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 324 | ``DisplayName``                         | String      | The initiator's display name.                                                                            |
 325 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 326 | ``Owner``                               | Container   | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object.                 |
 327 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 328 | ``StorageClass``                        | String      | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY``                    |
 329 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 330 | ``PartNumberMarker``                    | String      | The part marker to use in a subsequent request if ``IsTruncated`` is ``true``. Precedes the list.        |
 331 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 332 | ``NextPartNumberMarker``                | String      | The next part marker to use in a subsequent request if ``IsTruncated`` is ``true``. The end of the list. |
 333 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 334 | ``MaxParts``                            | Integer     | The max parts allowed in the response as specified by the ``max-parts`` request parameter.               |
 335 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 336 | ``IsTruncated``                         | Boolean     | If ``true``, only a subset of the object's upload contents were returned.                                |
 337 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 338 | ``Part``                                | Container   | A container for ``LastModified``, ``PartNumber``, ``ETag`` and ``Size`` elements.                        |
 339 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 340 | ``LastModified``                        | Date        | Date and time at which the part was uploaded.                                                            |
 341 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 342 | ``PartNumber``                          | Integer     | The identification number of the part.                                                                   |
 343 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 344 | ``ETag``                                | String      | The part's entity tag.                                                                                   |
 345 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 346 | ``Size``                                | Integer     | The size of the uploaded part.                                                                           |
 347 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 348
 349
 350
 351 Complete Multipart Upload
 352 -------------------------
 353 Assembles uploaded parts and creates a new object, thereby completing a multipart upload.
 354
 355 Syntax
 356 ~~~~~~
 357
 358 ::
 359
 360     POST /{bucket}/{object}?uploadId= HTTP/1.1
 361
 362 Request Entities
 363 ~~~~~~~~~~~~~~~~
 364
 365 +----------------------------------+-------------+-----------------------------------------------------+----------+
 366 | Name                             | Type        | Description                                         | Required |
 367 +==================================+=============+=====================================================+==========+
 368 | ``CompleteMultipartUpload``      | Container   | A container consisting of one or more parts.        | Yes      |
 369 +----------------------------------+-------------+-----------------------------------------------------+----------+
 370 | ``Part``                         | Container   | A container for the ``PartNumber`` and ``ETag``.    | Yes      |
 371 +----------------------------------+-------------+-----------------------------------------------------+----------+
 372 | ``PartNumber``                   | Integer     | The identifier of the part.                         | Yes      |
 373 +----------------------------------+-------------+-----------------------------------------------------+----------+
 374 | ``ETag``                         | String      | The part's entity tag.                              | Yes      |
 375 +----------------------------------+-------------+-----------------------------------------------------+----------+
 376
 377
 378 Response Entities
 379 ~~~~~~~~~~~~~~~~~
 380
 381 +-------------------------------------+-------------+-------------------------------------------------------+
 382 | Name                                | Type        | Description                                           |
 383 +=====================================+=============+=======================================================+
 384 | **CompleteMultipartUploadResult**   | Container   | A container for the response.                         |
 385 +-------------------------------------+-------------+-------------------------------------------------------+
 386 | **Location**                        | URI         | The resource identifier (path) of the new object.     |
 387 +-------------------------------------+-------------+-------------------------------------------------------+
 388 | **Bucket**                          | String      | The name of the bucket that contains the new object.  |
 389 +-------------------------------------+-------------+-------------------------------------------------------+
 390 | **Key**                             | String      | The object's key.                                     |
 391 +-------------------------------------+-------------+-------------------------------------------------------+
 392 | **ETag**                            | String      | The entity tag of the new object.                     |
 393 +-------------------------------------+-------------+-------------------------------------------------------+
 394
 395 Abort Multipart Upload
 396 ----------------------
 397
 398 Syntax
 399 ~~~~~~
 400
 401 ::
 402
 403     DELETE /{bucket}/{object}?uploadId= HTTP/1.1