PutBucketOverwriteConfig-对象存储(OSS)-阿里云帮助中心

调用PutBucketOverwriteConfig接口设置存储空间（Bucket）的禁止覆盖写，用于防止指定对象被覆盖写入。

注意事项

只配置forbid，任意情况下都不允许覆盖写，风险较高。
PutBucketOverwriteConfig为覆盖语义。例如，某个Bucket已配置了禁止覆盖写Rule1，如果需要在Rule1基础上继续追加规则Rule2，则需要执行以下操作：
- 调用GetBucketOverwriteConfig接口获取当前禁止覆盖写配置Rule1。
- 在Rule1基础上叠加Rule2。
- 调用PutBucketOverwriteConfig接口更新禁止覆盖写为Rule1+Rule2。
如果GetBucketOverwriteConfig返回404，说明当前Bucket未配置禁止覆盖写，可以直接调用PutBucketOverwriteConfig设置新规则。
单个Bucket最多支持配置100条禁止覆盖写。
Prefix、Suffix最大长度为1023个字符。
单个Rule中的前缀、后缀分别最多支持一个。前后缀均不支持正则表达式，即输入*，则会将其当作字符串来处理。
ID为可选项，如果不填写，则会随机生成一个UUID来填充；如果填写，则必须为唯一值，即不同的Rule中不能设置相同的ID。
Principal支持通配符星号（*），可参考Bucket Policy常见示例中Principal的配置。
满足Rule的前提是满足所有Filter条件（Prefix、Suffix、Principals）。只要有任一Rule被满足，即视为命中禁止覆盖写规则，此时覆盖写请求会被拒绝。

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。

API	Action	说明
PutBucketOverwriteConfig	`oss:PutBucketOverwriteConfig`	设置Bucket的禁止覆盖写。

请求语法

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>

请求头

此接口除支持公共请求头外，无特有请求头。更多信息，请参见公共HTTP头定义。

请求元素

名称	类型	是否必选	示例值	描述
OverwriteConfiguration	容器	是	无	禁止覆盖写的根节点。子节点：Rule 父节点：无
Rule	容器	是	无	禁止覆盖写项。单个Bucket最多支持配置100条规则。子节点：ID、Action、Prefix、Suffix、Principals 父节点：OverwriteConfiguration
ID	字符串	否	rule-001	规则的唯一标识符。如果不填写，则会随机生成一个UUID来填充；如果填写，则必须为唯一值，即不同的Rule中不能设置相同的ID。子节点：无父节点：Rule
Action	字符串	是	forbid	操作类型。当前只支持设置forbid（禁止覆盖写）。子节点：无父节点：Rule
Prefix	字符串	否	a/	Object名称的前缀，用于筛选需要处理的Object。最大长度为1023个字符。单个Rule中最多一个Prefix。前后缀不支持正则表达。子节点：无父节点：Rule
Suffix	字符串	否	.txt	Object名称的后缀，用于筛选需要处理的Object。最大长度为1023个字符。单个Rule中最多一个Suffix。前后缀不支持正则表达。子节点：无父节点：Rule
Principals	容器	否	无	授权主体集合。用法与Bucket Policy的Principal相仿，支持主账号、子账号或角色的输入。如果为空或不配置，则表明对于满足前后缀条件的Object，一律不允许覆盖写。子节点：Principal 父节点：Rule
Principal	字符串	否	27737962156157xxxx	授权主体。支持主账号、子账号或角色的输入。如果值为空，则为无效设置。子节点：无父节点：Principals

响应元素

此接口不返回响应元素。

响应头

此接口仅涉及公共响应头。更多信息，请参见公共HTTP头定义。

示例

请求示例

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>

返回示例

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