mirror of https://github.com/ceph/ceph
402 lines
29 KiB
ReStructuredText
402 lines
29 KiB
ReStructuredText
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** | The source bucket name + object name. | {bucket}/{obj} | Yes |
|
|
+--------------------------------------+-------------------------------------------------+------------------------+------------+
|
|
| **x-amz-acl** | A canned ACL. | ``private``, | No |
|
|
| | | ``public-read``, | |
|
|
| | | ``public-read-write``, | |
|
|
| | | ``authenticated-read`` | |
|
|
+--------------------------------------+-------------------------------------------------+------------------------+------------+
|
|
| **x-amz-copy-if-modified-since** | Copies only if modified since the timestamp. | Timestamp | No |
|
|
+--------------------------------------+-------------------------------------------------+------------------------+------------+
|
|
| **x-amz-copy-if-unmodified-since** | Copies only if unmodified since the timestamp. | Timestamp | No |
|
|
+--------------------------------------+-------------------------------------------------+------------------------+------------+
|
|
| **x-amz-copy-if-match** | Copies only if object ETag matches ETag. | Entity Tag | No |
|
|
+--------------------------------------+-------------------------------------------------+------------------------+------------+
|
|
| **x-amz-copy-if-none-match** | Copies only if object ETag doesn't match. | Entity Tag | No |
|
|
+--------------------------------------+-------------------------------------------------+------------------------+------------+
|
|
|
|
Response Entities
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
+------------------------+-------------+-----------------------------------------------+
|
|
| Name | Type | Description |
|
|
+========================+=============+===============================================+
|
|
| **CopyObjectResult** | Container | A container for the response elements. |
|
|
+------------------------+-------------+-----------------------------------------------+
|
|
| **LastModified** | Date | The last modified date of the source object. |
|
|
+------------------------+-------------+-----------------------------------------------+
|
|
| **Etag** | String | The ETag of the new object. |
|
|
+------------------------+-------------+-----------------------------------------------+
|
|
|
|
Remove Object
|
|
-------------
|
|
|
|
Removes an object. Requires WRITE permission set on the containing bucket.
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
DELETE /{bucket}/{object} HTTP/1.1
|
|
|
|
|
|
|
|
Get Object
|
|
----------
|
|
Retrieves an object from a bucket within RADOS.
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
GET /{bucket}/{object} HTTP/1.1
|
|
|
|
Request Headers
|
|
~~~~~~~~~~~~~~~
|
|
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| Name | Description | Valid Values | Required |
|
|
+===========================+================================================+================================+============+
|
|
| **range** | The range of the object to retrieve. | Range: bytes=beginbyte-endbyte | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-modified-since** | Gets only if modified since the timestamp. | Timestamp | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-unmodified-since** | Gets only if not modified since the timestamp. | Timestamp | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-match** | Gets only if object ETag matches ETag. | Entity Tag | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-none-match** | Gets only if object ETag matches ETag. | Entity Tag | 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 include
|
|
the metadata only, not the object data payload.
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
HEAD /{bucket}/{object} HTTP/1.1
|
|
|
|
Request Headers
|
|
~~~~~~~~~~~~~~~
|
|
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| Name | Description | Valid Values | Required |
|
|
+===========================+================================================+================================+============+
|
|
| **range** | The range of the object to retrieve. | Range: bytes=beginbyte-endbyte | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-modified-since** | Gets only if modified since the timestamp. | Timestamp | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-unmodified-since** | Gets only if not modified since the timestamp. | Timestamp | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-match** | Gets only if object ETag matches ETag. | Entity Tag | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
| **if-none-match** | Gets only if object ETag matches ETag. | Entity Tag | No |
|
|
+---------------------------+------------------------------------------------+--------------------------------+------------+
|
|
|
|
Get Object ACL
|
|
--------------
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
GET /{bucket}/{object}?acl HTTP/1.1
|
|
|
|
Response Entities
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| Name | Type | Description |
|
|
+===========================+=============+==============================================================================================+
|
|
| ``AccessControlPolicy`` | Container | A container for the response. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``AccessControlList`` | Container | A container for the ACL information. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Owner`` | Container | A container for the object owner's ``ID`` and ``DisplayName``. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``ID`` | String | The object owner's ID. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``DisplayName`` | String | The object owner's display name. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Permission`` | String | The permission given to the ``Grantee`` object. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
|
|
|
|
|
|
Set Object ACL
|
|
--------------
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
PUT /{bucket}/{object}?acl
|
|
|
|
Request Entities
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| Name | Type | Description |
|
|
+===========================+=============+==============================================================================================+
|
|
| ``AccessControlPolicy`` | Container | A container for the response. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``AccessControlList`` | Container | A container for the ACL information. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Owner`` | Container | A container for the object owner's ``ID`` and ``DisplayName``. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``ID`` | String | The object owner's ID. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``DisplayName`` | String | The object owner's display name. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
| ``Permission`` | String | The permission given to the ``Grantee`` object. |
|
|
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
|
|
|
|
|
|
|
|
Initiate Multi-part Upload
|
|
--------------------------
|
|
|
|
Initiate a multi-part upload process.
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
POST /{bucket}/{object}?uploads
|
|
|
|
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 |
|
|
+----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
|
|
|
|
|
|
Response Entities
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| Name | Type | Description |
|
|
+=========================================+=============+==========================================================================================================+
|
|
| ``InitiatedMultipartUploadsResult`` | Container | A container for the results. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Bucket`` | String | The bucket that will receive the object contents. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Key`` | String | The key specified by the ``key`` request parameter (if any). |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``UploadId`` | String | The ID specified by the ``upload-id`` request parameter identifying the multipart upload (if any). |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
|
|
|
|
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 |
|
|
+=========================================+=============+==========================================================================================================+
|
|
| ``InitiatedMultipartUploadsResult`` | Container | A container for the results. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Bucket`` | String | The bucket that will receive the object contents. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Key`` | String | The key specified by the ``key`` request parameter (if any). |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``UploadId`` | String | The ID specified by the ``upload-id`` request parameter identifying the multipart upload (if any). |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Initiator`` | Container | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``ID`` | String | The initiator's ID. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``DisplayName`` | String | The initiator's display name. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Owner`` | Container | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``StorageClass`` | String | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY`` |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``PartNumberMarker`` | String | The part marker to use in a subsequent request if ``IsTruncated`` is ``true``. Precedes the list. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``NextPartNumberMarker`` | String | The next part marker to use in a subsequent request if ``IsTruncated`` is ``true``. The end of the list. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``MaxParts`` | Integer | The max parts allowed in the response as specified by the ``max-parts`` request parameter. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``IsTruncated`` | Boolean | If ``true``, only a subset of the object's upload contents were returned. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Part`` | Container | A container for ``Key``, ``Part``, ``InitiatorOwner``, ``StorageClass``, and ``Initiated`` elements. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``PartNumber`` | Integer | The identification number of the part. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``ETag`` | String | The part's entity tag. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
| ``Size`` | Integer | The size of the uploaded part. |
|
|
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
|
|
|
|
|
|
|
|
Complete Multipart Upload
|
|
-------------------------
|
|
Assembles uploaded parts and creates a new object, thereby completing a multipart upload.
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
POST /{bucket}/{object}?uploadId= HTTP/1.1
|
|
|
|
Request Entities
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
+----------------------------------+-------------+-----------------------------------------------------+----------+
|
|
| Name | Type | Description | Required |
|
|
+==================================+=============+=====================================================+==========+
|
|
| ``CompleteMultipartUpload`` | Container | A container consisting of one or more parts. | Yes |
|
|
+----------------------------------+-------------+-----------------------------------------------------+----------+
|
|
| ``Part`` | Container | A container for the ``PartNumber`` and ``ETag``. | Yes |
|
|
+----------------------------------+-------------+-----------------------------------------------------+----------+
|
|
| ``PartNumber`` | Integer | The identifier of the part. | Yes |
|
|
+----------------------------------+-------------+-----------------------------------------------------+----------+
|
|
| ``ETag`` | String | The part's entity tag. | Yes |
|
|
+----------------------------------+-------------+-----------------------------------------------------+----------+
|
|
|
|
|
|
Response Entities
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
+-------------------------------------+-------------+-------------------------------------------------------+
|
|
| Name | Type | Description |
|
|
+=====================================+=============+=======================================================+
|
|
| **CompleteMultipartUploadResult** | Container | A container for the response. |
|
|
+-------------------------------------+-------------+-------------------------------------------------------+
|
|
| **Location** | URI | The resource identifier (path) of the new object. |
|
|
+-------------------------------------+-------------+-------------------------------------------------------+
|
|
| **Bucket** | String | The name of the bucket that contains the new object. |
|
|
+-------------------------------------+-------------+-------------------------------------------------------+
|
|
| **Key** | String | The object's key. |
|
|
+-------------------------------------+-------------+-------------------------------------------------------+
|
|
| **ETag** | String | The entity tag of the new object. |
|
|
+-------------------------------------+-------------+-------------------------------------------------------+
|
|
|
|
Abort Multipart Upload
|
|
----------------------
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
::
|
|
|
|
DELETE /{bucket}/{object}?uploadId= HTTP/1.1
|