Call GetBucketOverwriteConfig to retrieve the overwrite configuration - Object Storage Service

Call the GetBucketOverwriteConfig operation to retrieve the overwrite configuration of a bucket.

Notes

If a bucket does not have an overwrite configuration, the operation returns a 404 status code.

Permissions

By default, Alibaba Cloud accounts have all permissions. Resource Access Management (RAM) users and RAM roles have no permissions by default. The Alibaba Cloud account owner or an administrator must grant permissions using a RAM policy or a bucket policy.

API	Action	Description
GetBucketOverwriteConfig	`oss:GetBucketOverwriteConfig`	Gets the overwrite configuration of a bucket.

Request syntax

GET /?overwriteConfig HTTP/1.1
Host: bucket-name.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue

Request headers

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

Request elements

This operation does not contain any request elements.

Response elements

Name	Type	Example	Description
OverwriteConfiguration	Container	None	The root node of the rule cannot be overwritten. Child node: Rule Parent node: None
Rule	Container	None	An overwrite rule. Child nodes: ID, Action, Prefix, Suffix, and Principals Parent node: OverwriteConfiguration
ID	String	rule-001	The unique identifier of the rule. Child node: None Parent node: Rule
Action	String	forbid	The operation type. Only `forbid` is supported. `forbid` prevents objects from being overwritten. Child node: None Parent node: Rule
Prefix	String	a/	The prefix of the object name. Child node: None Parent node: Rule
Suffix	String	.txt	The suffix of the object name. Child node: None Parent node: Rule
Principals	Container	None	A collection of authorized entities. Child node: Principal Parent node: Rule
Principal	String	27737962156157xxxx	The authorized entity. Child node: None Parent node: Principals

Response headers

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

Examples

Request example

GET /?overwriteConfig HTTP/1.1
Host: bucket-name.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue

Response examples

Successful response (rules are configured)

HTTP/1.1 200 OK
x-oss-request-id: 5C4E5B5C5E5F5A5B5C5D5E5F
Date: Mon, 25 Nov 2024 15:00:59 GMT
Content-Type: application/xml
Content-Length: 512

<?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>
    <Suffix/>
    <Principals/>
  </Rule>
  <Rule>
    <ID>rule-003</ID>
    <Action>forbid</Action>
    <Prefix/>
    <Suffix>.jpg</Suffix>
    <Principals/>
  </Rule>
  <Rule>
    <ID>rule-004</ID>
    <Action>forbid</Action>
    <Prefix/>
    <Suffix/>
    <Principals>
      <Principal>27737962156157xxxx</Principal>
    </Principals>
  </Rule>
</OverwriteConfiguration>

This example shows several possible rule formats:

Rule1 includes a specified prefix, suffix, and principal. This rule forbids the RAM user 27737962156157xxxx from overwriting objects that have the prefix `a/` and the suffix `.txt`.
Rule2 specifies only a prefix. This rule forbids all users from overwriting objects that have the prefix `images/`.
Rule3 specifies only a suffix. This rule forbids all users from overwriting objects that have the suffix `.jpg`.
Rule4 specifies only a principal. This rule forbids the specified user from overwriting any object in the bucket.
Response when no rules are configured (404)

HTTP/1.1 404 Not Found
x-oss-request-id: 5C4E5B5C5E5F5A5B5C5XXXX
Date: Mon, 25 Nov 2025 15:00:59 GMT
Content-Type: application/xml
Content-Length: 200

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchOverwriteConfiguration</Code>
  <Message>The specified overwrite configuration does not exist.</Message>
  <RequestId>5C4E5B5C5E5F5A5B5C5XXXX</RequestId>
  <HostId>bucket-name.oss-cn-hangzhou.aliyuncs.com</HostId>
</Error>