ceph/doc/radosgw/s3/bucketops.rst

   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
  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
  32
  33 +---------------+----------------------+-----------------------------------------------------------------------------+------------+
  34 | Name          | Description          | Valid Values                                                                | Required   |
  35 +===============+======================+=============================================================================+============+
  36 | ``x-amz-acl`` | Canned ACLs.         | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read`` | No         |
  37 +---------------+----------------------+-----------------------------------------------------------------------------+------------+
  38 | ``x-amz-bucket-object-lock-enabled`` | Enable object lock on bucket. | ``true``, ``false``                         | No         |
  39 +--------------------------------------+-------------------------------+---------------------------------------------+------------+
  40
  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 +-------------------------------+-----------+----------------------------------------------------------------+
  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
 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 +---------------------+-----------+-------------------------------------------------------------------------------------------------+
 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 +------------------------+-----------+------------------------------------------+
 171 | ``Type``               | String    | ``Appendable`` or ``Normal``.            |
 172 +------------------------+-----------+------------------------------------------+
 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   |
 198 |                        |           | string for default region                |
 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 +------------------------+-----------+--------------------------------------------------------------------------------------+
 309 | ``upload-id-marker``   | String    | Ignored if ``key-marker`` is not specified. Specifies the ``ID`` of first            |
 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 |
 391 +-----------------------------+-----------+---------------------------------------------------------------------------+
 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