PutBucketOverwriteConfig - Object Storage Service - Alibaba Cloud Documentation Center

Precautions

In high-concurrency write scenarios, such as when multiple clients simultaneously write to a non-existent path or write during a deletion, the system may initially permit the writes because no file exists to be overwritten. However, once the file is created, the rule blocks all subsequent overwrite attempts.
Configuring only forbid prevents overwriting under any circumstances, which poses a high risk.
PutBucketOverwriteConfig uses overwrite semantics. For example, if a bucket already has a rule named Rule1 and you want to add Rule2, perform the following steps:
- Call GetBucketOverwriteConfig to retrieve the current configuration that contains Rule1.
- Add Rule2 to the retrieved configuration.
- Call PutBucketOverwriteConfig 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 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 not specified, a UUID is randomly generated. If specified, it must be unique across all rules in the bucket.
Principal supports the asterisk (*) wildcard character. For more information, see Bucket policy examples.
A rule is matched only when all its filter conditions (Prefix, Suffix, and Principals) are met. If any rule matches, the overwrite request is denied.

Permissions

An Alibaba Cloud account has all permissions by default. RAM users and RAM roles have no permissions by default. You must grant permissions by 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 not specified, a UUID is randomly generated. The value must be unique across all rules. Child node: None Parent node: Rule
Action	String	Yes	forbid	The action type. Currently, only `forbid` (prohibit overwrites) is supported. Child node: None Parent node: Rule
Prefix	String	No	a/	The object name prefix used to filter target objects. Maximum length: 1,023 characters. Each rule supports at most one prefix. Regular expressions are not supported. Child node: None Parent node: Rule
Suffix	String	No	.txt	The object name suffix used to filter target objects. Maximum length: 1,023 characters. Each rule supports at most one suffix. Regular expressions are not supported. Child node: None Parent node: Rule
Principals	Container	No	None	A collection of authorized entities, similar to the Principal element in a bucket policy. You can specify an Alibaba Cloud account, a RAM user, or a RAM role. If 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	An authorized entity. You can specify an Alibaba Cloud account, a RAM user, or a RAM role. If 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