src/ceph/doc/radosgw/swift/objectops.rst

   1 ===================
   2  Object Operations
   3 ===================
   4
   5 An object is a container for storing data and metadata. A container may
   6 have many objects, but the object names must be unique. This API enables a
   7 client to create an object, set access controls and metadata, retrieve an
   8 object's data and metadata, and delete an object. Since this API makes requests
   9 related to information in a particular user's account, all requests in this API
  10 must be authenticated unless the container or object's access control is
  11 deliberately made publicly accessible (i.e., allows anonymous requests).
  12
  13
  14 Create/Update an Object
  15 =======================
  16
  17 To create a new object, make a ``PUT`` request with the API version, account,
  18 container name and the name of the new object. You must have write permission
  19 on the container to create or update an object. The object name must be
  20 unique within the container. The ``PUT`` request is not idempotent, so if you
  21 do not use a unique name, the request will update the object. However, you may
  22 use pseudo-hierarchical syntax in your object name to distinguish it from
  23 another object of the same name if it is under a different pseudo-hierarchical
  24 directory. You may include access control headers and metadata headers in the
  25 request.
  26
  27
  28 Syntax
  29 ~~~~~~
  30
  31 ::
  32
  33    PUT /{api version}/{account}/{container}/{object} HTTP/1.1
  34         Host: {fqdn}
  35         X-Auth-Token: {auth-token}
  36
  37
  38 Request Headers
  39 ~~~~~~~~~~~~~~~
  40
  41 ``ETag``
  42
  43 :Description: An MD5 hash of the object's contents. Recommended.
  44 :Type: String
  45 :Required: No
  46
  47
  48 ``Content-Type``
  49
  50 :Description: The type of content the object contains.
  51 :Type: String
  52 :Required: No
  53
  54
  55 ``Transfer-Encoding``
  56
  57 :Description: Indicates whether the object is part of a larger aggregate object.
  58 :Type: String
  59 :Valid Values: ``chunked``
  60 :Required: No
  61
  62
  63 Copy an Object
  64 ==============
  65
  66 Copying an object allows you to make a server-side copy of an object, so that
  67 you don't have to download it and upload it under another container/name.
  68 To copy the contents of one object to another object, you may make either a
  69 ``PUT`` request or a ``COPY`` request with the API version, account, and the
  70 container name. For a ``PUT`` request, use the destination container and object
  71 name in the request, and the source container and object in the request header.
  72 For a ``Copy`` request, use the source container and object in the request, and
  73 the destination container and object in the request header. You must have write
  74 permission on the container to copy an object. The destination object name must be
  75 unique within the container. The request is not idempotent, so if you do not use
  76 a unique name, the request will update the destination object. However, you may
  77 use pseudo-hierarchical syntax in your object name to distinguish the destination
  78 object from the source object of the same name if it is under a different
  79 pseudo-hierarchical directory. You may include access control headers and metadata
  80 headers in the request.
  81
  82 Syntax
  83 ~~~~~~
  84
  85 ::
  86
  87         PUT /{api version}/{account}/{dest-container}/{dest-object} HTTP/1.1
  88         X-Copy-From: {source-container}/{source-object}
  89         Host: {fqdn}
  90         X-Auth-Token: {auth-token}
  91
  92
  93 or alternatively:
  94
  95 ::
  96
  97         COPY /{api version}/{account}/{source-container}/{source-object} HTTP/1.1
  98         Destination: {dest-container}/{dest-object}
  99
 100 Request Headers
 101 ~~~~~~~~~~~~~~~
 102
 103 ``X-Copy-From``
 104
 105 :Description: Used with a ``PUT`` request to define the source container/object path.
 106 :Type: String
 107 :Required: Yes, if using ``PUT``
 108
 109
 110 ``Destination``
 111
 112 :Description: Used with a ``COPY`` request to define the destination container/object path.
 113 :Type: String
 114 :Required: Yes, if using ``COPY``
 115
 116
 117 ``If-Modified-Since``
 118
 119 :Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute.
 120 :Type: Date
 121 :Required: No
 122
 123
 124 ``If-Unmodified-Since``
 125
 126 :Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute.
 127 :Type: Date
 128 :Required: No
 129
 130 ``Copy-If-Match``
 131
 132 :Description: Copies only if the ETag in the request matches the source object's ETag.
 133 :Type: ETag.
 134 :Required: No
 135
 136
 137 ``Copy-If-None-Match``
 138
 139 :Description: Copies only if the ETag in the request does not match the source object's ETag.
 140 :Type: ETag.
 141 :Required: No
 142
 143
 144 Delete an Object
 145 ================
 146
 147 To delete an object, make a ``DELETE`` request with the API version, account,
 148 container and object name. You must have write permissions on the container to delete
 149 an object within it. Once you have successfully deleted the object, you will be able to
 150 reuse the object name.
 151
 152 Syntax
 153 ~~~~~~
 154
 155 ::
 156
 157         DELETE /{api version}/{account}/{container}/{object} HTTP/1.1
 158         Host: {fqdn}
 159         X-Auth-Token: {auth-token}
 160
 161
 162 Get an Object
 163 =============
 164
 165 To retrieve an object, make a ``GET`` request with the API version, account,
 166 container and object name. You must have read permissions on the container to
 167 retrieve an object within it.
 168
 169 Syntax
 170 ~~~~~~
 171
 172 ::
 173
 174         GET /{api version}/{account}/{container}/{object} HTTP/1.1
 175         Host: {fqdn}
 176         X-Auth-Token: {auth-token}
 177
 178
 179
 180 Request Headers
 181 ~~~~~~~~~~~~~~~
 182
 183 ``range``
 184
 185 :Description: To retrieve a subset of an object's contents, you may specify a byte range.
 186 :Type: Date
 187 :Required: No
 188
 189
 190 ``If-Modified-Since``
 191
 192 :Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute.
 193 :Type: Date
 194 :Required: No
 195
 196
 197 ``If-Unmodified-Since``
 198
 199 :Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute.
 200 :Type: Date
 201 :Required: No
 202
 203 ``Copy-If-Match``
 204
 205 :Description: Copies only if the ETag in the request matches the source object's ETag.
 206 :Type: ETag.
 207 :Required: No
 208
 209
 210 ``Copy-If-None-Match``
 211
 212 :Description: Copies only if the ETag in the request does not match the source object's ETag.
 213 :Type: ETag.
 214 :Required: No
 215
 216
 217
 218 Response Headers
 219 ~~~~~~~~~~~~~~~~
 220
 221 ``Content-Range``
 222
 223 :Description: The range of the subset of object contents. Returned only if the range header field was specified in the request
 224
 225
 226 Get Object Metadata
 227 ===================
 228
 229 To retrieve an object's metadata, make a ``HEAD`` request with the API version,
 230 account, container and object name. You must have read permissions on the
 231 container to retrieve metadata from an object within the container. This request
 232 returns the same header information as the request for the object itself, but
 233 it does not return the object's data.
 234
 235 Syntax
 236 ~~~~~~
 237
 238 ::
 239
 240         HEAD /{api version}/{account}/{container}/{object} HTTP/1.1
 241         Host: {fqdn}
 242         X-Auth-Token: {auth-token}
 243
 244
 245
 246 Add/Update Object Metadata
 247 ==========================
 248
 249 To add metadata to an object, make a ``POST`` request with the API version,
 250 account, container and object name. You must have write permissions on the
 251 parent container to add or update metadata.
 252
 253
 254 Syntax
 255 ~~~~~~
 256
 257 ::
 258
 259         POST /{api version}/{account}/{container}/{object} HTTP/1.1
 260         Host: {fqdn}
 261         X-Auth-Token: {auth-token}
 262
 263 Request Headers
 264 ~~~~~~~~~~~~~~~
 265
 266 ``X-Object-Meta-{key}``
 267
 268 :Description:  A user-defined meta data key that takes an arbitrary string value.
 269 :Type: String
 270 :Required: No
 271