ceph/doc/radosgw/swift/containerops.rst

   1 ======================
   2  Container Operations
   3 ======================
   4
   5 A container is a mechanism for storing data objects. An account may
   6 have many containers, but container names must be unique. This API enables a
   7 client to create a container, set access controls and metadata,
   8 retrieve a container's contents, and delete a container. Since this API
   9 makes requests related to information in a particular user's account, all
  10 requests in this API must be authenticated unless a container's access control
  11 is deliberately made publicly accessible (i.e., allows anonymous requests).
  12
  13 .. note:: The Amazon S3 API uses the term 'bucket' to describe a data container.
  14    When you hear someone refer to a 'bucket' within the Swift API, the term
  15    'bucket' may be construed as the equivalent of the term 'container.'
  16
  17 One facet of object storage is that it does not support hierarchical paths
  18 or directories. Instead, it supports one level consisting of one or more
  19 containers, where each container may have objects. The RADOS Gateway's
  20 Swift-compatible API supports the notion of 'pseudo-hierarchical containers,'
  21 which is a means of using object naming to emulate a container (or directory)
  22 hierarchy without actually implementing one in the storage system. You may
  23 name objects with pseudo-hierarchical names
  24 (e.g., photos/buildings/empire-state.jpg), but container names cannot
  25 contain a forward slash (``/``) character.
  26
  27
  28 Create a Container
  29 ==================
  30
  31 To create a new container, make a ``PUT`` request with the API version, account,
  32 and the name of the new container. The container name must be unique, must not
  33 contain a forward-slash (/) character, and should be less than 256 bytes. You
  34 may include access control headers and metadata headers in the request. The
  35 operation is idempotent; that is, if you make a request to create a container
  36 that already exists, it will return with a HTTP 202 return code, but will not
  37 create another container.
  38
  39
  40 Syntax
  41 ~~~~~~
  42
  43 ::
  44
  45         PUT /{api version}/{account}/{container} HTTP/1.1
  46         Host: {fqdn}
  47         X-Auth-Token: {auth-token}
  48         X-Container-Read: {comma-separated-uids}
  49         X-Container-Write: {comma-separated-uids}
  50         X-Container-Meta-{key}: {value}
  51
  52
  53 Headers
  54 ~~~~~~~
  55
  56 ``X-Container-Read``
  57
  58 :Description: The user IDs with read permissions for the container.
  59 :Type: Comma-separated string values of user IDs.
  60 :Required: No
  61
  62 ``X-Container-Write``
  63
  64 :Description: The user IDs with write permissions for the container.
  65 :Type: Comma-separated string values of user IDs.
  66 :Required: No
  67
  68 ``X-Container-Meta-{key}``
  69
  70 :Description:  A user-defined meta data key that takes an arbitrary string value.
  71 :Type: String
  72 :Required: No
  73
  74
  75 HTTP Response
  76 ~~~~~~~~~~~~~
  77
  78 If a container with the same name already exists, and the user is the
  79 container owner then the operation will succeed. Otherwise the operation
  80 will fail.
  81
  82 ``409``
  83
  84 :Description: The container already exists under a different user's ownership.
  85 :Status Code: ``BucketAlreadyExists``
  86
  87
  88
  89
  90 List a Container's Objects
  91 ==========================
  92
  93 To list the objects within a container, make a ``GET`` request with the with the
  94 API version, account, and the name of the container.  You can specify query
  95 parameters to filter the full list, or leave out the parameters to return a list
  96 of the first 10,000 object names stored in the container.
  97
  98
  99 Syntax
 100 ~~~~~~
 101
 102 ::
 103
 104    GET /{api version}/{container} HTTP/1.1
 105         Host: {fqdn}
 106         X-Auth-Token: {auth-token}
 107
 108
 109 Parameters
 110 ~~~~~~~~~~
 111
 112 ``format``
 113
 114 :Description: Defines the format of the result.
 115 :Type: String
 116 :Valid Values: ``json`` | ``xml``
 117 :Required: No
 118
 119 ``prefix``
 120
 121 :Description: Limits the result set to objects beginning with the specified prefix.
 122 :Type: String
 123 :Required: No
 124
 125 ``marker``
 126
 127 :Description: Returns a list of results greater than the marker value.
 128 :Type: String
 129 :Required: No
 130
 131 ``limit``
 132
 133 :Description: Limits the number of results to the specified value.
 134 :Type: Integer
 135 :Valid Range: 0 - 10,000
 136 :Required: No
 137
 138 ``delimiter``
 139
 140 :Description: The delimiter between the prefix and the rest of the object name.
 141 :Type: String
 142 :Required: No
 143
 144 ``path``
 145
 146 :Description: The pseudo-hierarchical path of the objects.
 147 :Type: String
 148 :Required: No
 149
 150 ``allow_unordered``
 151
 152 :Description: Allows the results to be returned unordered to reduce computation overhead. Cannot be used with ``delimiter``.
 153 :Type: Boolean
 154 :Required: No
 155 :Non-Standard Extension: Yes
 156
 157
 158 Response Entities
 159 ~~~~~~~~~~~~~~~~~
 160
 161 ``container``
 162
 163 :Description: The container.
 164 :Type: Container
 165
 166 ``object``
 167
 168 :Description: An object within the container.
 169 :Type: Container
 170
 171 ``name``
 172
 173 :Description: The name of an object within the container.
 174 :Type: String
 175
 176 ``hash``
 177
 178 :Description: A hash code of the object's contents.
 179 :Type: String
 180
 181 ``last_modified``
 182
 183 :Description: The last time the object's contents were modified.
 184 :Type: Date
 185
 186 ``content_type``
 187
 188 :Description: The type of content within the object.
 189 :Type: String
 190
 191
 192
 193 Update a Container's ACLs
 194 =========================
 195
 196 When a user creates a container, the user has read and write access to the
 197 container by default. To allow other users to read a container's contents or
 198 write to a container, you must specifically enable the user.
 199 You may also specify ``*`` in the ``X-Container-Read`` or ``X-Container-Write``
 200 settings, which effectively enables all users to either read from or write
 201 to the container. Setting ``*`` makes the container public. That is it
 202 enables anonymous users to either read from or write to the container.
 203
 204 .. note:: If you are planning to expose public read ACL functionality
 205           for the Swift API, it is strongly recommended to include the
 206           Swift account name in the endpoint definition, so as to most
 207           closely emulate the behavior of native OpenStack Swift. To
 208           do so, set the ``ceph.conf`` configuration option ``rgw
 209           swift account in url = true``, and update your Keystone
 210           endpoint to the URL suffix ``/v1/AUTH_%(tenant_id)s``
 211           (instead of just ``/v1``).
 212
 213
 214 Syntax
 215 ~~~~~~
 216
 217 ::
 218
 219    POST /{api version}/{account}/{container} HTTP/1.1
 220    Host: {fqdn}
 221         X-Auth-Token: {auth-token}
 222         X-Container-Read: *
 223         X-Container-Write: {uid1}, {uid2}, {uid3}
 224
 225 Request Headers
 226 ~~~~~~~~~~~~~~~
 227
 228 ``X-Container-Read``
 229
 230 :Description: The user IDs with read permissions for the container.
 231 :Type: Comma-separated string values of user IDs.
 232 :Required: No
 233
 234 ``X-Container-Write``
 235
 236 :Description: The user IDs with write permissions for the container.
 237 :Type: Comma-separated string values of user IDs.
 238 :Required: No
 239
 240
 241 Add/Update Container Metadata
 242 =============================
 243
 244 To add metadata to a container, make a ``POST`` request with the API version,
 245 account, and container name. You must have write permissions on the
 246 container to add or update metadata.
 247
 248 Syntax
 249 ~~~~~~
 250
 251 ::
 252
 253    POST /{api version}/{account}/{container} HTTP/1.1
 254    Host: {fqdn}
 255         X-Auth-Token: {auth-token}
 256         X-Container-Meta-Color: red
 257         X-Container-Meta-Taste: salty
 258
 259 Request Headers
 260 ~~~~~~~~~~~~~~~
 261
 262 ``X-Container-Meta-{key}``
 263
 264 :Description:  A user-defined meta data key that takes an arbitrary string value.
 265 :Type: String
 266 :Required: No
 267
 268
 269 Enable Object Versioning for a Container
 270 ========================================
 271
 272 To enable object versioning a container, make a ``POST`` request with
 273 the API version, account, and container name. You must have write
 274 permissions on the container to add or update metadata.
 275
 276 .. note:: Object versioning support is not enabled in radosgw by
 277           default; you must set ``rgw swift versioning enabled =
 278           true`` in ``ceph.conf`` to enable this feature.
 279
 280 Syntax
 281 ~~~~~~
 282
 283 ::
 284
 285    POST /{api version}/{account}/{container} HTTP/1.1
 286    Host: {fqdn}
 287         X-Auth-Token: {auth-token}
 288         X-Versions-Location: {archive-container}
 289
 290 Request Headers
 291 ~~~~~~~~~~~~~~~
 292
 293 ``X-Versions-Location``
 294
 295 :Description: The name of a container (the "archive container") that
 296               will be used to store versions of the objects in the
 297               container that the ``POST`` request is made on (the
 298               "current container"). The archive container need not
 299               exist at the time it is being referenced, but once
 300               ``X-Versions-Location`` is set on the current container,
 301               and object versioning is thus enabled, the archive
 302               container must exist before any further objects are
 303               updated or deleted in the current container.
 304
 305               .. note:: ``X-Versions-Location`` is the only
 306                         versioning-related header that radosgw
 307                         interprets. ``X-History-Location``, supported
 308                         by native OpenStack Swift, is currently not
 309                         supported by radosgw.
 310 :Type: String
 311 :Required: No (if this header is passed with an empty value, object
 312            versioning on the current container is disabled, but the
 313            archive container continues to exist.)
 314
 315
 316 Delete a Container
 317 ==================
 318
 319 To delete a container, make a ``DELETE`` request with the API version, account,
 320 and the name of the container. The container must be empty. If you'd like to check
 321 if the container is empty, execute a ``HEAD`` request against the container. Once
 322 you have successfully removed the container, you will be able to reuse the container name.
 323
 324 Syntax
 325 ~~~~~~
 326
 327 ::
 328
 329         DELETE /{api version}/{account}/{container} HTTP/1.1
 330         Host: {fqdn}
 331         X-Auth-Token: {auth-token}
 332
 333
 334 HTTP Response
 335 ~~~~~~~~~~~~~
 336
 337 ``204``
 338
 339 :Description: The container was removed.
 340 :Status Code: ``NoContent``
 341