mirror of
https://github.com/ceph/ceph
synced 2024-12-30 07:23:11 +00:00
6da5a5888c
Add the ability to list the contents of a bucket without the results being sorted. This can have performance benefits since all bucket shards do not need to be queried. This is done by adding a parameter to the REST query string (i.e., "allow_unordered" [note underscore] for swift or "allow-unordered" [note hyphen] for s3) to true. This works with other request parameters such as marker, end_marker, and prefix. But it does not work when delimeter is used. Also, because the results are not in order, a subsequent marker may precede an earlier marker. Signed-off-by: J. Eric Ivancich <ivancich@redhat.com>
287 lines
7.0 KiB
ReStructuredText
287 lines
7.0 KiB
ReStructuredText
======================
|
|
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
|
|
|
|
``allow_unordered``
|
|
|
|
:Description: Allows the results to be returned unordered to reduce computation overhead. Cannot be used with ``delimiter``.
|
|
:Type: Boolean
|
|
:Required: No
|
|
:Non-Standard Extension: Yes
|
|
|
|
|
|
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``
|
|
|