All Products
Search

This Product

    Object Storage Service:PutBucketObjectWormConfiguration

    Document Center

    Object Storage Service:PutBucketObjectWormConfiguration

    Last Updated:Jun 22, 2026

    Enables an object-level retention policy (ObjectWorm) on a bucket and optionally configures a default retention policy. This action is irreversible: once ObjectWorm is enabled for a bucket, you cannot disable it.

    Usage notes

    Important

    This feature is currently available by invitation only. To request access, contact technical support.

    • This action is irreversible. After you enable an object-level retention policy for a bucket, you cannot disable its ObjectWorm or versioning features.

    • Before you call this operation, you must enable versioning for the bucket. Otherwise, the operation returns an error.

    • ObjectWorm is mutually exclusive with a bucket-level retention policy (BucketWorm). If a bucket-level retention policy is already enabled for the bucket, the call fails and returns an error.

    • A default retention policy is optional. If configured, the system automatically applies it to all new objects uploaded to the bucket. The policy does not apply to existing objects. To apply a retention policy to an existing object, call the PutObjectRetention operation.

    • Enabling ObjectWorm disables support for append uploads.

    • You must grant users the oss:PutObjectRetention and oss:GetObjectRetention permissions to allow them to manage object retention policies.

    Request syntax

    PUT /?objectWorm HTTP/1.1
Content-MD5: ContentMD5
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    Request headers

    Parameter

    Type

    Required

    Example

    Description

    Content-MD5

    String

    Yes

    B2M2Y8AsgTpgAmY7PhC****

    The Base64-encoded MD5 hash of the request body. OSS uses this header to verify data integrity.

    Content-Length

    Positive integer

    Yes

    188

    The length of the request body in bytes.

    Request elements

    Parameter

    Type

    Required

    Example

    Description

    ObjectWormConfiguration

    Container

    Yes

    N/A

    A container for the bucket's object-level retention policy configuration.

    Parent element: None

    Child elements: ObjectWormEnabled, Rule

    ObjectWormEnabled

    String

    Yes

    Enabled

    Whether to enable the object-level retention policy. The value must be Enabled.

    Parent element: ObjectWormConfiguration

    Rule

    Container

    No

    N/A

    A container for the bucket's default object-level retention policy.

    Parent element: ObjectWormConfiguration

    Child element: DefaultRetention

    DefaultRetention

    Container

    No

    N/A

    The container for the default retention policy.

    Parent element: Rule

    Child elements: Mode, Days, Years

    Mode

    String

    No

    COMPLIANCE

    The default retention mode for the object-level retention policy. The valid value is:

    • COMPLIANCE (compliance mode): Within the retention period, no user, including the root user, can delete or overwrite a protected object version.

    Parent element: DefaultRetention

    Days

    Positive integer

    No

    1

    The default retention period in days. Valid values: 1 to 36500. You must specify either Days or Years, but not both.

    Parent node: DefaultRetention

    Years

    Positive integer

    No

    1

    The default retention period in years. Valid values: 1 to 100. You must specify either Days or Years, but not both.

    Parent element: DefaultRetention

    Examples

    Example 1: Enable ObjectWorm with a default policy

    This example enables ObjectWorm for a bucket and configures a default retention policy that protects objects in compliance mode for one day.

    • Sample request

      PUT /?objectWorm HTTP/1.1
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-Length: 188
Content-Type: application/xml
Content-MD5: B2M2Y8AsgTpgAmY7PhC****
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d****

<?xml version="1.0" encoding="UTF-8"?>
<ObjectWormConfiguration>
  <ObjectWormEnabled>Enabled</ObjectWormEnabled>
  <Rule>
    <DefaultRetention>
      <Mode>COMPLIANCE</Mode>
      <Days>1</Days>
    </DefaultRetention>
  </Rule>
</ObjectWormConfiguration>

    • Sample response

      HTTP/1.1 200 OK
x-oss-request-id: 5374A2880232A65C2300****
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-Length: 0
Server: AliyunOSS

    Example 2: Enable ObjectWorm without a default policy

    This example enables ObjectWorm for a bucket without a default retention policy. You can later call PutObjectRetention to set retention policies on individual objects.

    • Sample request

      PUT /?objectWorm HTTP/1.1
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-Length: 102
Content-Type: application/xml
Content-MD5: C3N3Z9BthUpgBnZ8QiD****
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=****

<?xml version="1.0" encoding="UTF-8"?>
<ObjectWormConfiguration>
  <ObjectWormEnabled>Enabled</ObjectWormEnabled>
</ObjectWormConfiguration>

    • Sample response

      HTTP/1.1 200 OK
x-oss-request-id: 6485B3990232A65C3400****
Date: Thu, 17 Mar 2026 11:20:15 GMT
Content-Length: 0
Server: AliyunOSS

    Error codes

    Error code

    HTTP status code

    Description

    InvalidBucketState

    409

    Versioning is not enabled for the bucket, so ObjectWorm cannot be enabled. Enable versioning and try again.

    BucketWormAlreadyEnabled

    409

    A bucket-level retention policy (BucketWorm) is already enabled for the bucket. You cannot enable an object-level retention policy (ObjectWorm) at the same time.