projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
1 | =================== |
| 2 | Bucket Operations | |
| 3 | =================== | |
| 4 | ||
| 5 | PUT Bucket | |
| 6 | ---------- | |
| 7 | Creates a new bucket. To create a bucket, you must have a user ID and a valid AWS Access Key ID to authenticate requests. You may not | |
| 8 | create buckets as an anonymous user. | |
| 9 | ||
| 7c673cae FG |
10 | Constraints |
| 11 | ~~~~~~~~~~~ | |
| 12 | In general, bucket names should follow domain name constraints. | |
| 13 | ||
| 14 | - Bucket names must be unique. | |
| 15 | - Bucket names must begin and end with a lowercase letter. | |
| 16 | - Bucket names may contain a dash (-). | |
| 17 | ||
| 18 | Syntax | |
| 19 | ~~~~~~ | |
| 20 | ||
| 21 | :: | |
| 22 | ||
| 23 | PUT /{bucket} HTTP/1.1 | |
| 24 | Host: cname.domain.com | |
| 25 | x-amz-acl: public-read-write | |
| 26 | ||
| 27 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
| 28 | ||
| 29 | Parameters | |
| 30 | ~~~~~~~~~~ | |
| 31 | ||
| eafe8130 | 32 | |
| 7c673cae FG |
33 | +---------------+----------------------+-----------------------------------------------------------------------------+------------+ |
| 34 | | Name | Description | Valid Values | Required | | |
| 35 | +===============+======================+=============================================================================+============+ | |
| 36 | | ``x-amz-acl`` | Canned ACLs. | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read`` | No | | |
| 37 | +---------------+----------------------+-----------------------------------------------------------------------------+------------+ | |
| eafe8130 TL |
38 | | ``x-amz-bucket-object-lock-enabled`` | Enable object lock on bucket. | ``true``, ``false`` | No | |
| 39 | +--------------------------------------+-------------------------------+---------------------------------------------+------------+ | |
| 7c673cae | 40 | |
| 81eedcae TL |
41 | Request Entities |
| 42 | ~~~~~~~~~~~~~~~~ | |
| 43 | ||
| 44 | +-------------------------------+-----------+----------------------------------------------------------------+ | |
| 45 | | Name | Type | Description | | |
| 46 | +===============================+===========+================================================================+ | |
| 47 | | ``CreateBucketConfiguration`` | Container | A container for the bucket configuration. | | |
| 48 | +-------------------------------+-----------+----------------------------------------------------------------+ | |
| 49 | | ``LocationConstraint`` | String | A zonegroup api name, with optional :ref:`s3_bucket_placement` | | |
| 50 | +-------------------------------+-----------+----------------------------------------------------------------+ | |
| 7c673cae FG |
51 | |
| 52 | ||
| 53 | HTTP Response | |
| 54 | ~~~~~~~~~~~~~ | |
| 55 | ||
| 56 | If the bucket name is unique, within constraints and unused, the operation will succeed. | |
| 57 | If a bucket with the same name already exists and the user is the bucket owner, the operation will succeed. | |
| 58 | If the bucket name is already in use, the operation will fail. | |
| 59 | ||
| 60 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 61 | | HTTP Status | Status Code | Description | | |
| 62 | +===============+=======================+==========================================================+ | |
| 63 | | ``409`` | BucketAlreadyExists | Bucket already exists under different user's ownership. | | |
| 64 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 65 | ||
| 66 | DELETE Bucket | |
| 67 | ------------- | |
| 68 | ||
| 69 | Deletes a bucket. You can reuse bucket names following a successful bucket removal. | |
| 70 | ||
| 71 | Syntax | |
| 72 | ~~~~~~ | |
| 73 | ||
| 74 | :: | |
| 75 | ||
| 76 | DELETE /{bucket} HTTP/1.1 | |
| 77 | Host: cname.domain.com | |
| 78 | ||
| 79 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
| 80 | ||
| 81 | HTTP Response | |
| 82 | ~~~~~~~~~~~~~ | |
| 83 | ||
| 84 | +---------------+---------------+------------------+ | |
| 85 | | HTTP Status | Status Code | Description | | |
| 86 | +===============+===============+==================+ | |
| 87 | | ``204`` | No Content | Bucket removed. | | |
| 88 | +---------------+---------------+------------------+ | |
| 89 | ||
| 90 | GET Bucket | |
| 91 | ---------- | |
| 92 | Returns a list of bucket objects. | |
| 93 | ||
| 94 | Syntax | |
| 95 | ~~~~~~ | |
| 96 | ||
| 97 | :: | |
| 98 | ||
| 99 | GET /{bucket}?max-keys=25 HTTP/1.1 | |
| 100 | Host: cname.domain.com | |
| 101 | ||
| 102 | Parameters | |
| 103 | ~~~~~~~~~~ | |
| 104 | ||
| 1adf2230 AA |
105 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ |
| 106 | | Name | Type | Description | | |
| 107 | +=====================+===========+=================================================================================================+ | |
| 108 | | ``prefix`` | String | Only returns objects that contain the specified prefix. | | |
| 109 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
| 110 | | ``delimiter`` | String | The delimiter between the prefix and the rest of the object name. | | |
| 111 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
| 112 | | ``marker`` | String | A beginning index for the list of objects returned. | | |
| 113 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
| 114 | | ``max-keys`` | Integer | The maximum number of keys to return. Default is 1000. | | |
| 115 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
| 116 | | ``allow-unordered`` | Boolean | Non-standard extension. Allows results to be returned unordered. Cannot be used with delimiter. | | |
| 117 | +---------------------+-----------+-------------------------------------------------------------------------------------------------+ | |
| 7c673cae FG |
118 | |
| 119 | HTTP Response | |
| 120 | ~~~~~~~~~~~~~ | |
| 121 | ||
| 122 | +---------------+---------------+--------------------+ | |
| 123 | | HTTP Status | Status Code | Description | | |
| 124 | +===============+===============+====================+ | |
| 125 | | ``200`` | OK | Buckets retrieved | | |
| 126 | +---------------+---------------+--------------------+ | |
| 127 | ||
| 128 | Bucket Response Entities | |
| 129 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 130 | ``GET /{bucket}`` returns a container for buckets with the following fields. | |
| 131 | ||
| 132 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 133 | | Name | Type | Description | | |
| 134 | +========================+===========+==================================================================================+ | |
| 135 | | ``ListBucketResult`` | Entity | The container for the list of objects. | | |
| 136 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 137 | | ``Name`` | String | The name of the bucket whose contents will be returned. | | |
| 138 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 139 | | ``Prefix`` | String | A prefix for the object keys. | | |
| 140 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 141 | | ``Marker`` | String | A beginning index for the list of objects returned. | | |
| 142 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 143 | | ``MaxKeys`` | Integer | The maximum number of keys returned. | | |
| 144 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 145 | | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | | |
| 146 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 147 | | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's contents were returned. | | |
| 148 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 149 | | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | | |
| 150 | +------------------------+-----------+----------------------------------------------------------------------------------+ | |
| 151 | ||
| 152 | Object Response Entities | |
| 153 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 154 | The ``ListBucketResult`` contains objects, where each object is within a ``Contents`` container. | |
| 155 | ||
| 156 | +------------------------+-----------+------------------------------------------+ | |
| 157 | | Name | Type | Description | | |
| 158 | +========================+===========+==========================================+ | |
| 159 | | ``Contents`` | Object | A container for the object. | | |
| 160 | +------------------------+-----------+------------------------------------------+ | |
| 161 | | ``Key`` | String | The object's key. | | |
| 162 | +------------------------+-----------+------------------------------------------+ | |
| 163 | | ``LastModified`` | Date | The object's last-modified date/time. | | |
| 164 | +------------------------+-----------+------------------------------------------+ | |
| 165 | | ``ETag`` | String | An MD-5 hash of the object. (entity tag) | | |
| 166 | +------------------------+-----------+------------------------------------------+ | |
| 167 | | ``Size`` | Integer | The object's size. | | |
| 168 | +------------------------+-----------+------------------------------------------+ | |
| 169 | | ``StorageClass`` | String | Should always return ``STANDARD``. | | |
| 170 | +------------------------+-----------+------------------------------------------+ | |
| 11fdf7f2 TL |
171 | | ``Type`` | String | ``Appendable`` or ``Normal``. | |
| 172 | +------------------------+-----------+------------------------------------------+ | |
| 7c673cae FG |
173 | |
| 174 | Get Bucket Location | |
| 175 | ------------------- | |
| 176 | Retrieves the bucket's region. The user needs to be the bucket owner | |
| 177 | to call this. A bucket can be constrained to a region by providing | |
| 178 | ``LocationConstraint`` during a PUT request. | |
| 179 | ||
| 180 | Syntax | |
| 181 | ~~~~~~ | |
| 182 | Add the ``location`` subresource to bucket resource as shown below | |
| 183 | ||
| 184 | :: | |
| 185 | ||
| 186 | GET /{bucket}?location HTTP/1.1 | |
| 187 | Host: cname.domain.com | |
| 188 | ||
| 189 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
| 190 | ||
| 191 | Response Entities | |
| 192 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 193 | ||
| 194 | +------------------------+-----------+------------------------------------------+ | |
| 195 | | Name | Type | Description | | |
| 196 | +========================+===========+==========================================+ | |
| 197 | | ``LocationConstraint`` | String | The region where bucket resides, empty | | |
| 11fdf7f2 | 198 | | | | string for default region | |
| 7c673cae FG |
199 | +------------------------+-----------+------------------------------------------+ |
| 200 | ||
| 201 | ||
| 202 | ||
| 203 | Get Bucket ACL | |
| 204 | -------------- | |
| 205 | Retrieves the bucket access control list. The user needs to be the bucket | |
| 206 | owner or to have been granted ``READ_ACP`` permission on the bucket. | |
| 207 | ||
| 208 | Syntax | |
| 209 | ~~~~~~ | |
| 210 | Add the ``acl`` subresource to the bucket request as shown below. | |
| 211 | ||
| 212 | :: | |
| 213 | ||
| 214 | GET /{bucket}?acl HTTP/1.1 | |
| 215 | Host: cname.domain.com | |
| 216 | ||
| 217 | Authorization: AWS {access-key}:{hash-of-header-and-secret} | |
| 218 | ||
| 219 | Response Entities | |
| 220 | ~~~~~~~~~~~~~~~~~ | |
| 221 | ||
| 222 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 223 | | Name | Type | Description | | |
| 224 | +===========================+=============+==============================================================================================+ | |
| 225 | | ``AccessControlPolicy`` | Container | A container for the response. | | |
| 226 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 227 | | ``AccessControlList`` | Container | A container for the ACL information. | | |
| 228 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 229 | | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | | |
| 230 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 231 | | ``ID`` | String | The bucket owner's ID. | | |
| 232 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 233 | | ``DisplayName`` | String | The bucket owner's display name. | | |
| 234 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 235 | | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | | |
| 236 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 237 | | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | | |
| 238 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 239 | | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | | |
| 240 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 241 | ||
| 242 | PUT Bucket ACL | |
| 243 | -------------- | |
| 244 | Sets an access control to an existing bucket. The user needs to be the bucket | |
| 245 | owner or to have been granted ``WRITE_ACP`` permission on the bucket. | |
| 246 | ||
| 247 | Syntax | |
| 248 | ~~~~~~ | |
| 249 | Add the ``acl`` subresource to the bucket request as shown below. | |
| 250 | ||
| 251 | :: | |
| 252 | ||
| 253 | PUT /{bucket}?acl HTTP/1.1 | |
| 254 | ||
| 255 | Request Entities | |
| 256 | ~~~~~~~~~~~~~~~~ | |
| 257 | ||
| 258 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 259 | | Name | Type | Description | | |
| 260 | +===========================+=============+==============================================================================================+ | |
| 261 | | ``AccessControlPolicy`` | Container | A container for the request. | | |
| 262 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 263 | | ``AccessControlList`` | Container | A container for the ACL information. | | |
| 264 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 265 | | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | | |
| 266 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 267 | | ``ID`` | String | The bucket owner's ID. | | |
| 268 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 269 | | ``DisplayName`` | String | The bucket owner's display name. | | |
| 270 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 271 | | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | | |
| 272 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 273 | | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | | |
| 274 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 275 | | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | | |
| 276 | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | |
| 277 | ||
| 278 | List Bucket Multipart Uploads | |
| 279 | ----------------------------- | |
| 280 | ||
| 281 | ``GET /?uploads`` returns a list of the current in-progress multipart uploads--i.e., the application initiates a multipart upload, but | |
| 282 | the service hasn't completed all the uploads yet. | |
| 283 | ||
| 284 | Syntax | |
| 285 | ~~~~~~ | |
| 286 | ||
| 287 | :: | |
| 288 | ||
| 289 | GET /{bucket}?uploads HTTP/1.1 | |
| 290 | ||
| 291 | Parameters | |
| 292 | ~~~~~~~~~~ | |
| 293 | ||
| 294 | You may specify parameters for ``GET /{bucket}?uploads``, but none of them are required. | |
| 295 | ||
| 296 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
| 297 | | Name | Type | Description | | |
| 298 | +========================+===========+======================================================================================+ | |
| 299 | | ``prefix`` | String | Returns in-progress uploads whose keys contains the specified prefix. | | |
| 300 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
| 301 | | ``delimiter`` | String | The delimiter between the prefix and the rest of the object name. | | |
| 302 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
| 303 | | ``key-marker`` | String | The beginning marker for the list of uploads. | | |
| 304 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
| 305 | | ``max-keys`` | Integer | The maximum number of in-progress uploads. The default is 1000. | | |
| 306 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
| 307 | | ``max-uploads`` | Integer | The maximum number of multipart uploads. The range from 1-1000. The default is 1000. | | |
| 308 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
| c07f9fc5 | 309 | | ``upload-id-marker`` | String | Ignored if ``key-marker`` is not specified. Specifies the ``ID`` of first | |
| 7c673cae FG |
310 | | | | upload to list in lexicographical order at or following the ``ID``. | |
| 311 | +------------------------+-----------+--------------------------------------------------------------------------------------+ | |
| 312 | ||
| 313 | ||
| 314 | Response Entities | |
| 315 | ~~~~~~~~~~~~~~~~~ | |
| 316 | ||
| 317 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 318 | | Name | Type | Description | | |
| 319 | +=========================================+=============+==========================================================================================================+ | |
| 320 | | ``ListMultipartUploadsResult`` | Container | A container for the results. | | |
| 321 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 322 | | ``ListMultipartUploadsResult.Prefix`` | String | The prefix specified by the ``prefix`` request parameter (if any). | | |
| 323 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 324 | | ``Bucket`` | String | The bucket that will receive the bucket contents. | | |
| 325 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 326 | | ``KeyMarker`` | String | The key marker specified by the ``key-marker`` request parameter (if any). | | |
| 327 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 328 | | ``UploadIdMarker`` | String | The marker specified by the ``upload-id-marker`` request parameter (if any). | | |
| 329 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 330 | | ``NextKeyMarker`` | String | The key marker to use in a subsequent request if ``IsTruncated`` is ``true``. | | |
| 331 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 332 | | ``NextUploadIdMarker`` | String | The upload ID marker to use in a subsequent request if ``IsTruncated`` is ``true``. | | |
| 333 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 334 | | ``MaxUploads`` | Integer | The max uploads specified by the ``max-uploads`` request parameter. | | |
| 335 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 336 | | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | | |
| 337 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 338 | | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's upload contents were returned. | | |
| 339 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 340 | | ``Upload`` | Container | A container for ``Key``, ``UploadId``, ``InitiatorOwner``, ``StorageClass``, and ``Initiated`` elements. | | |
| 341 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 342 | | ``Key`` | String | The key of the object once the multipart upload is complete. | | |
| 343 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 344 | | ``UploadId`` | String | The ``ID`` that identifies the multipart upload. | | |
| 345 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 346 | | ``Initiator`` | Container | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload. | | |
| 347 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 348 | | ``DisplayName`` | String | The initiator's display name. | | |
| 349 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 350 | | ``ID`` | String | The initiator's ID. | | |
| 351 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 352 | | ``Owner`` | Container | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object. | | |
| 353 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 354 | | ``StorageClass`` | String | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY`` | | |
| 355 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 356 | | ``Initiated`` | Date | The date and time the user initiated the upload. | | |
| 357 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 358 | | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | | |
| 359 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 360 | | ``CommonPrefixes.Prefix`` | String | The substring of the key after the prefix as defined by the ``prefix`` request parameter. | | |
| 361 | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | |
| 362 | ||
| 363 | ENABLE/SUSPEND BUCKET VERSIONING | |
| 364 | -------------------------------- | |
| 365 | ||
| 366 | ``PUT /?versioning`` This subresource set the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner. | |
| 367 | ||
| 368 | You can set the versioning state with one of the following values: | |
| 369 | ||
| 370 | - Enabled : Enables versioning for the objects in the bucket, All objects added to the bucket receive a unique version ID. | |
| 371 | - Suspended : Disables versioning for the objects in the bucket, All objects added to the bucket receive the version ID null. | |
| 372 | ||
| 373 | If the versioning state has never been set on a bucket, it has no versioning state; a GET versioning request does not return a versioning state value. | |
| 374 | ||
| 375 | Syntax | |
| 376 | ~~~~~~ | |
| 377 | ||
| 378 | :: | |
| 379 | ||
| 380 | PUT /{bucket}?versioning HTTP/1.1 | |
| 381 | ||
| 382 | REQUEST ENTITIES | |
| 383 | ~~~~~~~~~~~~~~~~ | |
| 384 | ||
| 385 | +-----------------------------+-----------+---------------------------------------------------------------------------+ | |
| 386 | | Name | Type | Description | | |
| 387 | +=============================+===========+===========================================================================+ | |
| 388 | | ``VersioningConfiguration`` | Container | A container for the request. | | |
| 389 | +-----------------------------+-----------+---------------------------------------------------------------------------+ | |
| 390 | | ``Status`` | String | Sets the versioning state of the bucket. Valid Values: Suspended/Enabled | | |
| c07f9fc5 | 391 | +-----------------------------+-----------+---------------------------------------------------------------------------+ |
| eafe8130 TL |
392 | |
| 393 | PUT BUCKET OBJECT LOCK | |
| 394 | -------------------------------- | |
| 395 | ||
| 396 | Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock configuration will be | |
| 397 | applied by default to every new object placed in the specified bucket. | |
| 398 | ||
| 399 | Syntax | |
| 400 | ~~~~~~ | |
| 401 | ||
| 402 | :: | |
| 403 | ||
| 404 | PUT /{bucket}?object-lock HTTP/1.1 | |
| 405 | ||
| 406 | Request Entities | |
| 407 | ~~~~~~~~~~~~~~~~ | |
| 408 | ||
| 409 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 410 | | Name | Type | Description | Required | | |
| 411 | +=============================+=============+========================================================================================+==========+ | |
| 412 | | ``ObjectLockConfiguration`` | Container | A container for the request. | Yes | | |
| 413 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 414 | | ``ObjectLockEnabled`` | String | Indicates whether this bucket has an Object Lock configuration enabled. | Yes | | |
| 415 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 416 | | ``Rule`` | Container | The Object Lock rule in place for the specified bucket. | No | | |
| 417 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 418 | | ``DefaultRetention`` | Container | The default retention period applied to new objects placed in the specified bucket. | No | | |
| 419 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 420 | | ``Mode`` | String | The default Object Lock retention mode. Valid Values: GOVERNANCE/COMPLIANCE | Yes | | |
| 421 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 422 | | ``Days`` | Integer | The number of days specified for the default retention period. | No | | |
| 423 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 424 | | ``Years`` | Integer | The number of years specified for the default retention period. | No | | |
| 425 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 426 | ||
| 427 | HTTP Response | |
| 428 | ~~~~~~~~~~~~~ | |
| 429 | ||
| 430 | If the bucket object lock is not enabled when creating the bucket, the operation will fail. | |
| 431 | ||
| 432 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 433 | | HTTP Status | Status Code | Description | | |
| 434 | +===============+=======================+==========================================================+ | |
| 435 | | ``400`` | MalformedXML | The XML is not well-formed | | |
| 436 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 437 | | ``409`` | InvalidBucketState | The bucket object lock is not enabled | | |
| 438 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 439 | ||
| 440 | GET BUCKET OBJECT LOCK | |
| 441 | -------------------------------- | |
| 442 | ||
| 443 | Gets the Object Lock configuration for a bucket. The rule specified in the Object Lock configuration will be applied by | |
| 444 | default to every new object placed in the specified bucket. | |
| 445 | ||
| 446 | Syntax | |
| 447 | ~~~~~~ | |
| 448 | ||
| 449 | :: | |
| 450 | ||
| 451 | GET /{bucket}?object-lock HTTP/1.1 | |
| 452 | ||
| 453 | ||
| 454 | Response Entities | |
| 455 | ~~~~~~~~~~~~~~~~~ | |
| 456 | ||
| 457 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 458 | | Name | Type | Description | Required | | |
| 459 | +=============================+=============+========================================================================================+==========+ | |
| 460 | | ``ObjectLockConfiguration`` | Container | A container for the request. | Yes | | |
| 461 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 462 | | ``ObjectLockEnabled`` | String | Indicates whether this bucket has an Object Lock configuration enabled. | Yes | | |
| 463 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 464 | | ``Rule`` | Container | The Object Lock rule in place for the specified bucket. | No | | |
| 465 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 466 | | ``DefaultRetention`` | Container | The default retention period applied to new objects placed in the specified bucket. | No | | |
| 467 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 468 | | ``Mode`` | String | The default Object Lock retention mode. Valid Values: GOVERNANCE/COMPLIANCE | Yes | | |
| 469 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 470 | | ``Days`` | Integer | The number of days specified for the default retention period. | No | | |
| 471 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 472 | | ``Years`` | Integer | The number of years specified for the default retention period. | No | | |
| 473 | +-----------------------------+-------------+----------------------------------------------------------------------------------------+----------+ | |
| 474 | ||
| 475 | Create Notification | |
| 476 | ------------------- | |
| 477 | ||
| 478 | Create a publisher for a specific bucket into a topic. | |
| 479 | ||
| 480 | Syntax | |
| 481 | ~~~~~~ | |
| 482 | ||
| 483 | :: | |
| 484 | ||
| 485 | PUT /<bucket name>?notification HTTP/1.1 | |
| 486 | ||
| 487 | ||
| 488 | Request Entities | |
| 489 | ~~~~~~~~~~~~~~~~ | |
| 490 | ||
| 491 | Parameters are XML encoded in the body of the request, in the following format: | |
| 492 | ||
| 493 | :: | |
| 494 | ||
| 495 | <NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> | |
| 496 | <TopicConfiguration> | |
| 497 | <Id></Id> | |
| 498 | <Topic></Topic> | |
| 499 | <Event></Event> | |
| 500 | <Filter> | |
| 501 | <S3Key> | |
| 502 | <FilterRule> | |
| 503 | <Name></Name> | |
| 504 | <Value></Value> | |
| 505 | </FilterRule> | |
| 506 | </S3Key> | |
| 507 | <S3Metadata> | |
| 508 | <FilterRule> | |
| 509 | <Name></Name> | |
| 510 | <Value></Value> | |
| 511 | </FilterRule> | |
| 512 | </s3Metadata> | |
| 513 | </Filter> | |
| 514 | </TopicConfiguration> | |
| 515 | </NotificationConfiguration> | |
| 516 | ||
| 517 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 518 | | Name | Type | Description | Required | | |
| 519 | +===============================+===========+======================================================================================+==========+ | |
| 520 | | ``NotificationConfiguration`` | Container | Holding list of ``TopicConfiguration`` entities | Yes | | |
| 521 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 522 | | ``TopicConfiguration`` | Container | Holding ``Id``, ``Topic`` and list of ``Event`` entities | Yes | | |
| 523 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 524 | | ``Id`` | String | Name of the notification | Yes | | |
| 525 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 526 | | ``Topic`` | String | Topic ARN. Topic must be created beforehand | Yes | | |
| 527 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 528 | | ``Event`` | String | List of supported events see: `S3 Notification Compatibility`_. Multiple ``Event`` | No | | |
| 529 | | | | entities can be used. If omitted, all events are handled | | | |
| 530 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 531 | | ``Filter`` | Container | Holding ``S3Key`` and ``S3Metadata`` entities | No | | |
| 532 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 533 | | ``S3Key`` | Container | Holding a list of ``FilterRule`` entities, for filtering based on object key. | No | | |
| 534 | | | | At most, 3 entities may be in the list, with ``Name`` be ``prefix``, ``suffix`` or | | | |
| 535 | | | | ``regex``. All filter rules in the list must match for the filter to match. | | | |
| 536 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 537 | | ``S3Metadata`` | Container | Holding a list of ``FilterRule`` entities, for filtering based on object metadata. | No | | |
| 538 | | | | All filter rules in the list must match the ones defined on the object. The object, | | | |
| 539 | | | | have other metadata entitied not listed in the filter. | | | |
| 540 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 541 | | ``S3Key.FilterRule`` | Container | Holding ``Name`` and ``Value`` entities. ``Name`` would be: ``prefix``, ``suffix`` | Yes | | |
| 542 | | | | or ``regex``. The ``Value`` would hold the key prefix, key suffix or a regular | | | |
| 543 | | | | expression for matching the key, accordingly. | | | |
| 544 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 545 | | ``S3Metadata.FilterRule`` | Container | Holding ``Name`` and ``Value`` entities. ``Name`` would be the name of the metadata | Yes | | |
| 546 | | | | attribute (e.g. ``x-amz-meta-xxx``). The ``Value`` would be the expected value for | | | |
| 547 | | | | this attribute | | | |
| 548 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 549 | ||
| 550 | ||
| 551 | HTTP Response | |
| 552 | ~~~~~~~~~~~~~ | |
| 553 | ||
| 554 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 555 | | HTTP Status | Status Code | Description | | |
| 556 | +===============+=======================+==========================================================+ | |
| 557 | | ``400`` | MalformedXML | The XML is not well-formed | | |
| 558 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 559 | | ``400`` | InvalidArgument | Missing Id; Missing/Invalid Topic ARN; Invalid Event | | |
| 560 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 561 | | ``404`` | NoSuchBucket | The bucket does not exist | | |
| 562 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 563 | | ``404`` | NoSuchKey | The topic does not exist | | |
| 564 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 565 | ||
| 566 | ||
| 567 | Delete Notification | |
| 568 | ------------------- | |
| 569 | ||
| 570 | Delete a specific, or all, notifications from a bucket. | |
| 571 | ||
| 572 | .. note:: | |
| 573 | ||
| 574 | - Notification deletion is an extension to the S3 notification API | |
| 575 | - When the bucket is deleted, any notification defined on it is also deleted | |
| 576 | - Deleting an unkown notification (e.g. double delete) is not considered an error | |
| 577 | ||
| 578 | Syntax | |
| 579 | ~~~~~~ | |
| 580 | ||
| 581 | :: | |
| 582 | ||
| 583 | DELETE /bucket?notification[=<notification-id>] HTTP/1.1 | |
| 584 | ||
| 585 | ||
| 586 | Parameters | |
| 587 | ~~~~~~~~~~ | |
| 588 | ||
| 589 | +------------------------+-----------+----------------------------------------------------------------------------------------+ | |
| 590 | | Name | Type | Description | | |
| 591 | +========================+===========+========================================================================================+ | |
| 592 | | ``notification-id`` | String | Name of the notification. If not provided, all notifications on the bucket are deleted | | |
| 593 | +------------------------+-----------+----------------------------------------------------------------------------------------+ | |
| 594 | ||
| 595 | HTTP Response | |
| 596 | ~~~~~~~~~~~~~ | |
| 597 | ||
| 598 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 599 | | HTTP Status | Status Code | Description | | |
| 600 | +===============+=======================+==========================================================+ | |
| 601 | | ``404`` | NoSuchBucket | The bucket does not exist | | |
| 602 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 603 | ||
| 604 | Get/List Notification | |
| 605 | --------------------- | |
| 606 | ||
| 607 | Get a specific notification, or list all notifications configured on a bucket. | |
| 608 | ||
| 609 | Syntax | |
| 610 | ~~~~~~ | |
| 611 | ||
| 612 | :: | |
| 613 | ||
| 614 | GET /bucket?notification[=<notification-id>] HTTP/1.1 | |
| 615 | ||
| 616 | ||
| 617 | Parameters | |
| 618 | ~~~~~~~~~~ | |
| 619 | ||
| 620 | +------------------------+-----------+----------------------------------------------------------------------------------------+ | |
| 621 | | Name | Type | Description | | |
| 622 | +========================+===========+========================================================================================+ | |
| 623 | | ``notification-id`` | String | Name of the notification. If not provided, all notifications on the bucket are listed | | |
| 624 | +------------------------+-----------+----------------------------------------------------------------------------------------+ | |
| 625 | ||
| 626 | Response Entities | |
| 627 | ~~~~~~~~~~~~~~~~~ | |
| 628 | ||
| 629 | Response is XML encoded in the body of the request, in the following format: | |
| 630 | ||
| 631 | :: | |
| 632 | ||
| 633 | <NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> | |
| 634 | <TopicConfiguration> | |
| 635 | <Id></Id> | |
| 636 | <Topic></Topic> | |
| 637 | <Event></Event> | |
| 638 | <Filter> | |
| 639 | <S3Key> | |
| 640 | <FilterRule> | |
| 641 | <Name></Name> | |
| 642 | <Value></Value> | |
| 643 | </FilterRule> | |
| 644 | </S3Key> | |
| 645 | <S3Metadata> | |
| 646 | <FilterRule> | |
| 647 | <Name></Name> | |
| 648 | <Value></Value> | |
| 649 | </FilterRule> | |
| 650 | </s3Metadata> | |
| 651 | </Filter> | |
| 652 | </TopicConfiguration> | |
| 653 | </NotificationConfiguration> | |
| 654 | ||
| 655 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 656 | | Name | Type | Description | Required | | |
| 657 | +===============================+===========+======================================================================================+==========+ | |
| 658 | | ``NotificationConfiguration`` | Container | Holding list of ``TopicConfiguration`` entities | Yes | | |
| 659 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 660 | | ``TopicConfiguration`` | Container | Holding ``Id``, ``Topic`` and list of ``Event`` entities | Yes | | |
| 661 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 662 | | ``Id`` | String | Name of the notification | Yes | | |
| 663 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 664 | | ``Topic`` | String | Topic ARN | Yes | | |
| 665 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 666 | | ``Event`` | String | Handled event. Multiple ``Event`` entities may exist | Yes | | |
| 667 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 668 | | ``Filter`` | Container | Holding the filters configured for this notification | No | | |
| 669 | +-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+ | |
| 670 | ||
| 671 | HTTP Response | |
| 672 | ~~~~~~~~~~~~~ | |
| 673 | ||
| 674 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 675 | | HTTP Status | Status Code | Description | | |
| 676 | +===============+=======================+==========================================================+ | |
| 677 | | ``404`` | NoSuchBucket | The bucket does not exist | | |
| 678 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 679 | | ``404`` | NoSuchKey | The notification does not exist (if provided) | | |
| 680 | +---------------+-----------------------+----------------------------------------------------------+ | |
| 681 | ||
| 682 | .. _S3 Notification Compatibility: ../s3-notification-compatibility |