PutBucketOverwriteConfig - Object Storage Service - Alibaba Cloud Documentation Center

Call the PutBucketOverwriteConfig operation to configure overwrite protection for a bucket. This prevents specified objects from being overwritten.

Precautions

If you only configure `forbid`, overwrites are prohibited in all cases. This configuration carries a high risk.
The PutBucketOverwriteConfig operation has overwrite semantics. For example, if a bucket is configured with an overwrite protection rule named Rule1 and you want to add another rule named Rule2, you must perform the following steps:
- Call the GetBucketOverwriteConfig operation to retrieve the current configuration that contains Rule1.
- Add Rule2 to the retrieved configuration.
- Call the PutBucketOverwriteConfig operation to upload the new configuration that contains both Rule1 and Rule2.
If GetBucketOverwriteConfig returns a 404 error, no overwrite protection is configured for the bucket. You can then call PutBucketOverwriteConfig directly to set a new rule.
A single bucket can have a maximum of 100 overwrite protection rules.
The maximum length for Prefix and Suffix is 1,023 characters.
Each rule can have at most one prefix and one suffix. Prefixes and suffixes do not support regular expressions. If you enter an asterisk (*), it is treated as a string.
ID is optional. If you do not specify an ID, a universally unique identifier (UUID) is randomly generated. If you specify an ID, it must be unique. Different rules cannot have the same ID.
Principal supports the asterisk (*) wildcard character. For more information about how to configure Principal, see Bucket policy examples.
A rule is matched only if all its filter conditions (Prefix, Suffix, and Principals) are met. If any rule is matched, the overwrite protection rule is triggered, and the overwrite request is denied.

Permissions

An Alibaba Cloud account has all permissions by default. A Resource Access Management (RAM) user or RAM role under an Alibaba Cloud account has no permissions by default. You must grant permissions to the RAM user or RAM role using a RAM policy or a bucket policy.

API	Action	Description
PutBucketOverwriteConfig	`oss:PutBucketOverwriteConfig`	Configures overwrite protection for a bucket.

Request syntax

PUT /?overwriteConfig HTTP/1.1
Host: bucket-name.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<OverwriteConfiguration>
  <Rule>
    <ID>string</ID>
    <Action>forbid</Action>
    <Prefix>string</Prefix>
    <Suffix>string</Suffix>
    <Principals>
      <Principal>string</Principal>
    </Principals>
  </Rule>
</OverwriteConfiguration>

Request headers

This operation uses only common request headers. For more information, see Common request headers.

Request elements

Name	Type	Required	Example	Description
OverwriteConfiguration	Container	Yes	None	The root node for the overwrite protection configuration. Child node: Rule Parent node: None
Rule	Container	Yes	None	An overwrite protection rule. A bucket can have a maximum of 100 rules. Child nodes: ID, Action, Prefix, Suffix, Principals Parent node: OverwriteConfiguration
ID	String	No	rule-001	The unique identifier of the rule. If you do not specify this element, a UUID is randomly generated. If you specify this element, the value must be unique. Different rules cannot have the same ID. Child node: None Parent node: Rule
Action	String	Yes	forbid	The operation type. Currently, only `forbid` (prohibit overwrites) is supported. Child node: None Parent node: Rule
Prefix	String	No	a/	The prefix of object names to filter the objects that you want to process. The maximum length is 1,023 characters. Each rule can have at most one prefix. Prefixes and suffixes do not support regular expressions. Child node: None Parent node: Rule
Suffix	String	No	.txt	The suffix of object names to filter the objects that you want to process. The maximum length is 1,023 characters. Each rule can have at most one suffix. Prefixes and suffixes do not support regular expressions. Child node: None Parent node: Rule
Principals	Container	No	None	A collection of authorized entities. The usage is similar to the `Principal` element in a bucket policy. You can specify an Alibaba Cloud account, a RAM user, or a RAM role. If this element is empty or not configured, overwrites are prohibited for all objects that match the prefix and suffix conditions. Child node: Principal Parent node: Rule
Principal	String	No	27737962156157xxxx	The authorized entity. You can specify an Alibaba Cloud account, a RAM user, or a RAM role. If this element is empty, the setting is invalid. Child node: None Parent node: Principals

Response elements

This operation does not return any response elements.

Response headers

This operation uses only common response headers. For more information, see Common request headers.

Examples

Request example

PUT /?overwriteConfig HTTP/1.1
Host: bucket-name.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<OverwriteConfiguration>
  <Rule>
    <ID>rule-001</ID>
    <Action>forbid</Action>
    <Prefix>a/</Prefix>
    <Suffix>.txt</Suffix>
    <Principals>
      <Principal>27737962156157xxxx</Principal>
    </Principals>
  </Rule>
  <Rule>
    <ID>rule-002</ID>
    <Action>forbid</Action>
    <Prefix>images/</Prefix>
  </Rule>
  <Rule>
    <ID>rule-003</ID>
    <Action>forbid</Action>
    <Suffix>.jpg</Suffix>
  </Rule>
  <Rule>
    <ID>rule-004</ID>
    <Action>forbid</Action>
    <Principals>
      <Principal>27737962156157xxxx</Principal>
    </Principals>
  </Rule>
</OverwriteConfiguration>

Response example

HTTP/1.1 200 OK
x-oss-request-id: 5C4E5B5C5E5F5A5B5C5D5XXX
Date: Mon, 25 Nov 2025 15:00:59 GMT