RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2025-01-18 00:43:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
3956cb8f19
ceph/doc/api/s3/objectops.rst
John 3956cb8f19 doc/api/s3 <-chipping away at objectops and clean up. Added Copy Object. 
doc/source <-fixed a typo, updates for installing on precise, rm $ from cmds
doc/start  <-replaced clone link with tarball link. Link to Ceph Source Code.


Signed-off-by: John Wilkins <john.wilkins@inktank.com>
2012-05-23 15:44:11 -07:00

383 lines
18 KiB
ReStructuredText
Raw Blame History

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
----------
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
Reference in New Issue View Git Blame Copy Permalink