ceph/doc/api/s3/objectops.rst

Object Operations
=================

Put Object
----------
Adds an object to a bucket. You must have write permissions on the bucket to perform this operation.


Syntax
~~~~~~

::

    PUT /{bucket}/{object} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
| Name                 | Description                                | Valid Values                                                                  | Required   |
+======================+============================================+===============================================================================+============+
| **content-md5**      | A base64 encoded MD-5 hash of the message. | A string. No defaults or constraints.                                         | No         |
+----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
| **content-type**     | A standard MIME type.                      | Any MIME type. Default: ``binary/octet-stream``                               | No         |
+----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
| **x-amz-meta-<...>** | User metadata.  Stored with the object.    | A string up to 8kb. No defaults.                                              | No         |
+----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
| **x-amz-acl**        | A canned ACL.                              | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read``   | No         |
+----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+


Copy Object
-----------
To copy an object, use PUT and specify a destination bucket and the object name.

Syntax
~~~~~~

::

    PUT /{dest-bucket}/{dest-object} HTTP/1.1
    x-amz-copy-source: {source-bucket}/{source-object}

Request Headers
~~~~~~~~~~~~~~~

+--------------------------------------+---------------+----------------+------------+
| Name                                 | Description   | Valid Values   | Required   |
+======================================+===============+================+============+
| **x-amz-copy-source**                |               |                | Yes        |
+--------------------------------------+---------------+----------------+------------+
| **x-amz-acl**                        |               |                | No         |
+--------------------------------------+---------------+----------------+------------+
| **x-amz-copy-if-modified-since**     |               |                | No         |
+--------------------------------------+---------------+----------------+------------+
| **x-amz-copy-if-unmodified-since**   |               |                | No         |
+--------------------------------------+---------------+----------------+------------+
| **x-amz-copy-if-match**              |               |                | No         |
+--------------------------------------+---------------+----------------+------------+
| **x-amz-copy-if-none-match**         |               |                | No         |
+--------------------------------------+---------------+----------------+------------+

Response Entities
~~~~~~~~~~~~~~~~~

+------------------------+-------------+---------------+
| Name                   | Type        | Description   |
+========================+=============+===============+
| **CopyObjectResult**   | Container   |               |
+------------------------+-------------+---------------+
| **LastModified**       | Date        |               |
+------------------------+-------------+---------------+
| **Etag**               | String      |               |
+------------------------+-------------+---------------+

Remove Object
-------------

Removes an object. Requires WRITE permission set on the containing bucket.

Syntax
~~~~~~

::

    DELETE /{bucket}/{object} HTTP/1.1

Get Object
----------

Syntax
~~~~~~

::

    GET /{bucket}/{object} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+---------------------------+---------------+----------------+------------+
| Name                      | Description   | Valid Values   | Required   |
+===========================+===============+================+============+
| **range**                 |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-modified-since**     |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-unmodified-since**   |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-match**              |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-none-match**         |               |                | No         |
+---------------------------+---------------+----------------+------------+

Response Headers
~~~~~~~~~~~~~~~~

+-------------------+--------------------------------------------------------------------------------------------+
| Name              | Description                                                                                |
+===================+============================================================================================+
| **Content-Range** | Data range, will only be returned if the range header field was specified in the request   |
+-------------------+--------------------------------------------------------------------------------------------+

Get Object Info
---------------

Returns information about object. This request will return the same
header information as with the Get Object request, but will not include
the object data payload.

Syntax
~~~~~~

::

    HEAD /{bucket}/{object} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+---------------------------+---------------+----------------+------------+
| Name                      | Description   | Valid Values   | Required   |
+===========================+===============+================+============+
| **range**                 |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-modified-since**     |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-unmodified-since**   |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-match**              |               |                | No         |
+---------------------------+---------------+----------------+------------+
| **if-none-match**         |               |                | No         |
+---------------------------+---------------+----------------+------------+

Get Object ACL
--------------

Syntax
~~~~~~

::

    GET /{bucket}/{object}?acl HTTP/1.1

Response Entities
~~~~~~~~~~~~~~~~~

+---------------------------+-------------+---------------+
| Name                      | Type        | Description   |
+===========================+=============+===============+
| **AccessControlPolicy**   | Container   |               |
+---------------------------+-------------+---------------+
| **AccessControlList**     | Container   |               |
+---------------------------+-------------+---------------+
| **Owner**                 | Container   |               |
+---------------------------+-------------+---------------+
| **ID**                    | String      |               |
+---------------------------+-------------+---------------+
| **DisplayName**           | String      |               |
+---------------------------+-------------+---------------+
| **Grant**                 | Container   |               |
+---------------------------+-------------+---------------+
| **Grantee**               | Container   |               |
+---------------------------+-------------+---------------+
| **Permission**            | String      |               |
+---------------------------+-------------+---------------+

Set Object ACL
--------------

Syntax
~~~~~~

::

    PUT /{bucket}/{object}?acl

Request Entities
~~~~~~~~~~~~~~~~

+---------------------------+-------------+---------------+
| Name                      | Type        | Description   |
+===========================+=============+===============+
| **AccessControlPolicy**   | Container   |               |
+---------------------------+-------------+---------------+
| **AccessControlList**     | Container   |               |
+---------------------------+-------------+---------------+
| **Owner**                 | Container   |               |
+---------------------------+-------------+---------------+
| **ID**                    | String      |               |
+---------------------------+-------------+---------------+
| **DisplayName**           | String      |               |
+---------------------------+-------------+---------------+
| **Grant**                 | Container   |               |
+---------------------------+-------------+---------------+
| **Grantee**               | Container   |               |
+---------------------------+-------------+---------------+
| **Permission**            | String      |               |
+---------------------------+-------------+---------------+

Initiate Multi-part Upload
--------------------------

Initiate a multi-part upload process.

Syntax
~~~~~~

::

    POST /{bucket}/{object}?uploads

Request Headers
~~~~~~~~~~~~~~~

+------------------------+---------------+---------------------------------------------------------------+------------+
| Name                   | Description   | Valid Values                                                  | Required   |
+========================+===============+===============================================================+============+
| **content-md5**        |               |                                                               | No         |
+------------------------+---------------+---------------------------------------------------------------+------------+
| **content-type**       |               |                                                               | No         |
+------------------------+---------------+---------------------------------------------------------------+------------+
| **x-amz-meta-<...>**   |               |                                                               | No         |
+------------------------+---------------+---------------------------------------------------------------+------------+
| **x-amz-acl**          |               | private, public-read, public-read-write, authenticated-read   | No         |
+------------------------+---------------+---------------------------------------------------------------+------------+

Response Entities
~~~~~~~~~~~~~~~~~

+-------------------------------------+-------------+---------------+
| Name                                | Type        | Description   |
+=====================================+=============+===============+
| **InitiateMultipartUploadResult**   | Container   |               |
+-------------------------------------+-------------+---------------+
| **Bucket**                          | String      |               |
+-------------------------------------+-------------+---------------+
| **Key**                             | String      |               |
+-------------------------------------+-------------+---------------+
| **UploadId**                        | String      |               |
+-------------------------------------+-------------+---------------+

Multipart Upload Part
---------------------

Syntax
~~~~~~

::

    PUT /{bucket}/{object}?partNumber=&uploadId= HTTP/1.1

HTTP Response
~~~~~~~~~~~~~

The following HTTP response may be returned:

+---------------+----------------+--------------------------------------------------------------------------+
| HTTP Status   | Status Code    | Description                                                              |
+===============+================+==========================================================================+
| **404**       | NoSuchUpload   | Specified upload-id does not match any initiated upload on this object   |
+---------------+----------------+--------------------------------------------------------------------------+

List Multipart Upload Parts
---------------------------

Syntax
~~~~~~

::

    GET /{bucket}/{object}?uploadId=123 HTTP/1.1

Response Entities
~~~~~~~~~~~~~~~~~

+-------------------------------------+-------------+---------------+
| Name                                | Type        | Description   |
+=====================================+=============+===============+
| **InitiateMultipartUploadResult**   | Container   |               |
+-------------------------------------+-------------+---------------+
| **Bucket**                          | String      |               |
+-------------------------------------+-------------+---------------+
| **Key**                             | String      |               |
+-------------------------------------+-------------+---------------+
| **UploadId**                        | String      |               |
+-------------------------------------+-------------+---------------+
| **StorageClass**                    | String      |               |
+-------------------------------------+-------------+---------------+
| **PartNumberMarker**                | Integer     |               |
+-------------------------------------+-------------+---------------+
| **NextPartNumberMarker**            | Integer     |               |
+-------------------------------------+-------------+---------------+
| **MaxParts**                        | Integer     |               |
+-------------------------------------+-------------+---------------+
| **IsTruncated**                     | Boolean     |               |
+-------------------------------------+-------------+---------------+
| **Part**                            | Container   |               |
+-------------------------------------+-------------+---------------+
| **LastModified**                    | Date        |               |
+-------------------------------------+-------------+---------------+
| **PartNumber**                      | Integer     |               |
+-------------------------------------+-------------+---------------+
| **ETag**                            | String      |               |
+-------------------------------------+-------------+---------------+
| **Size**                            | Integer     |               |
+-------------------------------------+-------------+---------------+

Complete Multipart Upload
-------------------------

Syntax
~~~~~~

::

    POST /{bucket}/{object}?uploadId= HTTP/1.1 

Request Entities
~~~~~~~~~~~~~~~~

+-------------------------------+-------------+----------------+------------+
| Name                          | Type        | Valid Values   | Required   |
+===============================+=============+================+============+
| **CompleteMultipartUpload**   | Container   |                | Yes        |
+-------------------------------+-------------+----------------+------------+
| **Part**                      | Container   |                | Yes        |
+-------------------------------+-------------+----------------+------------+
| **PartNumber**                | Integer     |                | Yes        |
+-------------------------------+-------------+----------------+------------+
| **ETag**                      | String      |                | Yes        |
+-------------------------------+-------------+----------------+------------+

Response Entities
~~~~~~~~~~~~~~~~~

+-------------------------------------+-------------+---------------+
| Name                                | Type        | Description   |
+=====================================+=============+===============+
| **CompleteMultipartUploadResult**   | Container   |               |
+-------------------------------------+-------------+---------------+
| **Location**                        | String      |               |
+-------------------------------------+-------------+---------------+
| **Bucket**                          | String      |               |
+-------------------------------------+-------------+---------------+
| **Key**                             | String      |               |
+-------------------------------------+-------------+---------------+
| **ETag**                            | String      |               |
+-------------------------------------+-------------+---------------+

Abort Multipart Upload
----------------------

Syntax
~~~~~~

::

    DELETE /{bucket}/{object}?uploadId= HTTP/1.1