PutBucketOverwriteConfig - Object Storage Service

調用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中的首碼、尾碼分別最多支援一個。前尾碼均不支援Regex，即輸入*，則會將其當作字串來處理。
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