diff options
Diffstat (limited to 'src/ceph/doc/radosgw/swift/containerops.rst')
| -rw-r--r-- | src/ceph/doc/radosgw/swift/containerops.rst | 279 |
1 files changed, 0 insertions, 279 deletions
diff --git a/src/ceph/doc/radosgw/swift/containerops.rst b/src/ceph/doc/radosgw/swift/containerops.rst deleted file mode 100644 index 463d91c..0000000 --- a/src/ceph/doc/radosgw/swift/containerops.rst +++ /dev/null @@ -1,279 +0,0 @@ -====================== - Container Operations -====================== - -A container is a mechanism for storing data objects. An account may -have many containers, but container names must be unique. This API enables a -client to create a container, set access controls and metadata, -retrieve a container's contents, and delete a container. Since this API -makes requests related to information in a particular user's account, all -requests in this API must be authenticated unless a container's access control -is deliberately made publicly accessible (i.e., allows anonymous requests). - -.. note:: The Amazon S3 API uses the term 'bucket' to describe a data container. - When you hear someone refer to a 'bucket' within the Swift API, the term - 'bucket' may be construed as the equivalent of the term 'container.' - -One facet of object storage is that it does not support hierarchical paths -or directories. Instead, it supports one level consisting of one or more -containers, where each container may have objects. The RADOS Gateway's -Swift-compatible API supports the notion of 'pseudo-hierarchical containers,' -which is a means of using object naming to emulate a container (or directory) -hierarchy without actually implementing one in the storage system. You may -name objects with pseudo-hierarchical names -(e.g., photos/buildings/empire-state.jpg), but container names cannot -contain a forward slash (``/``) character. - - -Create a Container -================== - -To create a new container, make a ``PUT`` request with the API version, account, -and the name of the new container. The container name must be unique, must not -contain a forward-slash (/) character, and should be less than 256 bytes. You -may include access control headers and metadata headers in the request. The -operation is idempotent; that is, if you make a request to create a container -that already exists, it will return with a HTTP 202 return code, but will not -create another container. - - -Syntax -~~~~~~ - -:: - - PUT /{api version}/{account}/{container} HTTP/1.1 - Host: {fqdn} - X-Auth-Token: {auth-token} - X-Container-Read: {comma-separated-uids} - X-Container-Write: {comma-separated-uids} - X-Container-Meta-{key}: {value} - - -Headers -~~~~~~~ - -``X-Container-Read`` - -:Description: The user IDs with read permissions for the container. -:Type: Comma-separated string values of user IDs. -:Required: No - -``X-Container-Write`` - -:Description: The user IDs with write permissions for the container. -:Type: Comma-separated string values of user IDs. -:Required: No - -``X-Container-Meta-{key}`` - -:Description: A user-defined meta data key that takes an arbitrary string value. -:Type: String -:Required: No - - -HTTP Response -~~~~~~~~~~~~~ - -If a container with the same name already exists, and the user is the -container owner then the operation will succeed. Otherwise the operation -will fail. - -``409`` - -:Description: The container already exists under a different user's ownership. -:Status Code: ``BucketAlreadyExists`` - - - - -List a Container's Objects -========================== - -To list the objects within a container, make a ``GET`` request with the with the -API version, account, and the name of the container. You can specify query -parameters to filter the full list, or leave out the parameters to return a list -of the first 10,000 object names stored in the container. - - -Syntax -~~~~~~ - -:: - - GET /{api version}/{container} HTTP/1.1 - Host: {fqdn} - X-Auth-Token: {auth-token} - - -Parameters -~~~~~~~~~~ - -``format`` - -:Description: Defines the format of the result. -:Type: String -:Valid Values: ``json`` | ``xml`` -:Required: No - -``prefix`` - -:Description: Limits the result set to objects beginning with the specified prefix. -:Type: String -:Required: No - -``marker`` - -:Description: Returns a list of results greater than the marker value. -:Type: String -:Required: No - -``limit`` - -:Description: Limits the number of results to the specified value. -:Type: Integer -:Valid Range: 0 - 10,000 -:Required: No - -``delimiter`` - -:Description: The delimiter between the prefix and the rest of the object name. -:Type: String -:Required: No - -``path`` - -:Description: The pseudo-hierarchical path of the objects. -:Type: String -:Required: No - - -Response Entities -~~~~~~~~~~~~~~~~~ - -``container`` - -:Description: The container. -:Type: Container - -``object`` - -:Description: An object within the container. -:Type: Container - -``name`` - -:Description: The name of an object within the container. -:Type: String - -``hash`` - -:Description: A hash code of the object's contents. -:Type: String - -``last_modified`` - -:Description: The last time the object's contents were modified. -:Type: Date - -``content_type`` - -:Description: The type of content within the object. -:Type: String - - - -Update a Container's ACLs -========================= - -When a user creates a container, the user has read and write access to the -container by default. To allow other users to read a container's contents or -write to a container, you must specifically enable the user. -You may also specify ``*`` in the ``X-Container-Read`` or ``X-Container-Write`` -settings, which effectively enables all users to either read from or write -to the container. Setting ``*`` makes the container public. That is it -enables anonymous users to either read from or write to the container. - - -Syntax -~~~~~~ - -:: - - POST /{api version}/{account}/{container} HTTP/1.1 - Host: {fqdn} - X-Auth-Token: {auth-token} - X-Container-Read: * - X-Container-Write: {uid1}, {uid2}, {uid3} - -Request Headers -~~~~~~~~~~~~~~~ - -``X-Container-Read`` - -:Description: The user IDs with read permissions for the container. -:Type: Comma-separated string values of user IDs. -:Required: No - -``X-Container-Write`` - -:Description: The user IDs with write permissions for the container. -:Type: Comma-separated string values of user IDs. -:Required: No - - -Add/Update Container Metadata -============================= - -To add metadata to a container, make a ``POST`` request with the API version, -account, and container name. You must have write permissions on the -container to add or update metadata. - -Syntax -~~~~~~ - -:: - - POST /{api version}/{account}/{container} HTTP/1.1 - Host: {fqdn} - X-Auth-Token: {auth-token} - X-Container-Meta-Color: red - X-Container-Meta-Taste: salty - -Request Headers -~~~~~~~~~~~~~~~ - -``X-Container-Meta-{key}`` - -:Description: A user-defined meta data key that takes an arbitrary string value. -:Type: String -:Required: No - - - -Delete a Container -================== - -To delete a container, make a ``DELETE`` request with the API version, account, -and the name of the container. The container must be empty. If you'd like to check -if the container is empty, execute a ``HEAD`` request against the container. Once -you have successfully removed the container, you will be able to reuse the container name. - -Syntax -~~~~~~ - -:: - - DELETE /{api version}/{account}/{container} HTTP/1.1 - Host: {fqdn} - X-Auth-Token: {auth-token} - - -HTTP Response -~~~~~~~~~~~~~ - -``204`` - -:Description: The container was removed. -:Status Code: ``NoContent`` - |