GetBucketOverwriteConfig - Object Storage Service - Alibaba Cloud Documentation Center

Notes

If no overwrite rules are configured for the bucket, 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`	Retrieves 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 overwrite configuration. 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 action to take. Only `forbid` is supported, which 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>

The following example response shows several rule formats:

Rule 1 specifies a prefix, suffix, and principal. It forbids the RAM user 27737962156157xxxx from overwriting objects that have the prefix `a/` and the suffix `.txt`.
Rule 2 specifies only a prefix. It forbids all users from overwriting objects that have the prefix `images/`.
Rule 3 specifies only a suffix. It forbids all users from overwriting objects that have the suffix `.jpg`.
Rule 4 specifies only a principal. It 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>