RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2024-12-21 02:42:48 +00:00
Code Issues Packages Projects Releases Wiki Activity
5465e81097
ceph/doc/api/s3/objectops.rst
Tommi Virtanen 5465e81097 doc: Whitespace cleanup. 
Signed-off-by: Tommi Virtanen <tommi.virtanen@dreamhost.com>
2012-05-03 10:15:21 -07:00

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