From 68874afaaa80847cfbf9ad4dfd6ccec821ee836b Mon Sep 17 00:00:00 2001 From: John Wilkins Date: Fri, 25 May 2012 16:03:02 -0700 Subject: [PATCH] doc: Filled in descriptions for object operations. Signed-off-by: John Wilkins --- doc/api/s3/bucketops.rst | 9 +- doc/api/s3/objectops.rst | 307 +++++++++++++++++++++------------------ 2 files changed, 164 insertions(+), 152 deletions(-) diff --git a/doc/api/s3/bucketops.rst b/doc/api/s3/bucketops.rst index 9bf7b24fa24..4bb8332ae5b 100644 --- a/doc/api/s3/bucketops.rst +++ b/doc/api/s3/bucketops.rst @@ -82,7 +82,6 @@ Returns a list of bucket objects. Syntax ~~~~~~ - :: GET /{bucket}?max-keys=25 HTTP/1.1 @@ -104,7 +103,6 @@ Parameters +-----------------+-----------+-----------------------------------------------------------------------+ - HTTP Response ~~~~~~~~~~~~~ @@ -161,7 +159,6 @@ The ``ListBucketResult`` contains objects, where each object is within a ``Conte Get Bucket ACL -------------- - Retrieves the bucket access control list. The user needs to be the bucket owner or to have been granted ``READ_ACP`` permission on the bucket. @@ -170,7 +167,6 @@ Syntax Add the ``acl`` subresource to the bucket request as shown below. :: - GET /{bucket}?acl HTTP/1.1 Host: cname.domain.com @@ -209,7 +205,6 @@ Syntax Add the ``acl`` subresource to the bucket request as shown below. :: - PUT /{bucket}?acl HTTP/1.1 Request Entities @@ -243,9 +238,7 @@ the service hasn't completed all the uploads yet. Syntax ~~~~~~ - :: - GET /{bucket}?uploads HTTP/1.1 Parameters @@ -285,7 +278,7 @@ Response Entities +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``KeyMarker`` | String | The key marker specified by the ``key-marker`` request parameter (if any). | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ -| ``UploadIdMarker`` | String | The marker specified by the ``upload-id-marker`` request paramter (if any). | +| ``UploadIdMarker`` | String | The marker specified by the ``upload-id-marker`` request parameter (if any). | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``NextKeyMarker`` | String | The key marker to use in a subsequent request if ``IsTruncated`` is ``true``. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ diff --git a/doc/api/s3/objectops.rst b/doc/api/s3/objectops.rst index ea25aaf4fd3..857976d1b66 100644 --- a/doc/api/s3/objectops.rst +++ b/doc/api/s3/objectops.rst @@ -31,7 +31,7 @@ Request Headers Copy Object ----------- -To copy an object, use PUT and specify a destination bucket and the object name. +To copy an object, use ``PUT`` and specify a destination bucket and the object name. Syntax ~~~~~~ @@ -88,8 +88,11 @@ Syntax DELETE /{bucket}/{object} HTTP/1.1 + + Get Object ---------- +Retrieves an object from a bucket within RADOS. Syntax ~~~~~~ @@ -101,19 +104,19 @@ Syntax Request Headers ~~~~~~~~~~~~~~~ -+---------------------------+---------------+----------------+------------+ -| Name | Description | Valid Values | Required | -+===========================+===============+================+============+ -| **range** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-modified-since** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-unmodified-since** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-match** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-none-match** | | | No | -+---------------------------+---------------+----------------+------------+ ++---------------------------+------------------------------------------------+--------------------------------+------------+ +| 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 ~~~~~~~~~~~~~~~~ @@ -128,8 +131,8 @@ 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. +header information as with the Get Object request, but will include +the metadata only, not the object data payload. Syntax ~~~~~~ @@ -141,19 +144,19 @@ Syntax Request Headers ~~~~~~~~~~~~~~~ -+---------------------------+---------------+----------------+------------+ -| Name | Description | Valid Values | Required | -+===========================+===============+================+============+ -| **range** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-modified-since** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-unmodified-since** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-match** | | | No | -+---------------------------+---------------+----------------+------------+ -| **if-none-match** | | | No | -+---------------------------+---------------+----------------+------------+ ++---------------------------+------------------------------------------------+--------------------------------+------------+ +| 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 -------------- @@ -168,25 +171,27 @@ Syntax Response Entities ~~~~~~~~~~~~~~~~~ -+---------------------------+-------------+---------------+ -| Name | Type | Description | -+===========================+=============+===============+ -| **AccessControlPolicy** | Container | | -+---------------------------+-------------+---------------+ -| **AccessControlList** | Container | | -+---------------------------+-------------+---------------+ -| **Owner** | Container | | -+---------------------------+-------------+---------------+ -| **ID** | String | | -+---------------------------+-------------+---------------+ -| **DisplayName** | String | | -+---------------------------+-------------+---------------+ -| **Grant** | Container | | -+---------------------------+-------------+---------------+ -| **Grantee** | Container | | -+---------------------------+-------------+---------------+ -| **Permission** | String | | -+---------------------------+-------------+---------------+ ++---------------------------+-------------+----------------------------------------------------------------------------------------------+ +| 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 -------------- @@ -201,25 +206,27 @@ Syntax Request Entities ~~~~~~~~~~~~~~~~ -+---------------------------+-------------+---------------+ -| Name | Type | Description | -+===========================+=============+===============+ -| **AccessControlPolicy** | Container | | -+---------------------------+-------------+---------------+ -| **AccessControlList** | Container | | -+---------------------------+-------------+---------------+ -| **Owner** | Container | | -+---------------------------+-------------+---------------+ -| **ID** | String | | -+---------------------------+-------------+---------------+ -| **DisplayName** | String | | -+---------------------------+-------------+---------------+ -| **Grant** | Container | | -+---------------------------+-------------+---------------+ -| **Grantee** | Container | | -+---------------------------+-------------+---------------+ -| **Permission** | String | | -+---------------------------+-------------+---------------+ ++---------------------------+-------------+----------------------------------------------------------------------------------------------+ +| 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 -------------------------- @@ -236,32 +243,34 @@ Syntax 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 | -+------------------------+---------------+---------------------------------------------------------------+------------+ ++----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+ +| 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 | -+=====================================+=============+===============+ -| **InitiateMultipartUploadResult** | Container | | -+-------------------------------------+-------------+---------------+ -| **Bucket** | String | | -+-------------------------------------+-------------+---------------+ -| **Key** | String | | -+-------------------------------------+-------------+---------------+ -| **UploadId** | String | | -+-------------------------------------+-------------+---------------+ ++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ +| 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 --------------------- @@ -297,40 +306,49 @@ Syntax 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 | | -+-------------------------------------+-------------+---------------+ ++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ +| 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 ~~~~~~ @@ -342,34 +360,35 @@ Syntax Request Entities ~~~~~~~~~~~~~~~~ -+-------------------------------+-------------+----------------+------------+ -| Name | Type | Valid Values | Required | -+===============================+=============+================+============+ -| **CompleteMultipartUpload** | Container | | Yes | -+-------------------------------+-------------+----------------+------------+ -| **Part** | Container | | Yes | -+-------------------------------+-------------+----------------+------------+ -| **PartNumber** | Integer | | Yes | -+-------------------------------+-------------+----------------+------------+ -| **ETag** | String | | Yes | -+-------------------------------+-------------+----------------+------------+ ++----------------------------------+-------------+-----------------------------------------------------+----------+ +| 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 | | -+-------------------------------------+-------------+---------------+ -| **Location** | String | | -+-------------------------------------+-------------+---------------+ -| **Bucket** | String | | -+-------------------------------------+-------------+---------------+ -| **Key** | String | | -+-------------------------------------+-------------+---------------+ -| **ETag** | String | | -+-------------------------------------+-------------+---------------+ ++-------------------------------------+-------------+-------------------------------------------------------+ +| 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 ----------------------