PutBucketMirroring
Updated at：2025-11-03
API description
This API is used to define rules for managing image back-to-origin processes.
Note:
- Only the bucket owner with FULL_CONTROL permission can execute this request.
- PutBucketMirroring will replace existing image back-to-origin rules. To add new rules while retaining existing ones, include both the old and new rules in the request.
Request
-
Request syntax
Plain Text1PUT /?mirroring HTTP/1.1 2Host: <BucketName>.bj.bcebos.com 3x-bce-date: date 4Content-Length: request-body length 5Content-Type: application/json; charset=utf-8 6Authorization: AuthorizationString 7{ 8 "bucketMirroringConfiguration":[ 9 { 10 "mode":"fetch", 11 "sourceUrl":"http://www.baidu.com", 12 "backSourceUrl":"bos://bj.bcebos.com/bucket", 13 "resource" : "folder1/folder2*.jpeg", 14 "prefix": "testprefix", 15 "suffix": ".jpeg", 16 "fixedKey":"folder1/404.jpeg", 17 "version":"v2", 18 "prefixReplace" : "a/b/c", 19 "passQuerystring":true, 20 "storageClass":"STANDARD", 21 "customHeaders":[ 22 { 23 "headerName":"testheader1", 24 "headerValue":"name1", 25 }, 26 { 27 "headerName":"TestHeaderName", 28 "headerValue":"TestHeaderValue", 29 } 30 ], 31 "ignoreHeaders": ["BanHeader1","BanHeader2"], 32 "passHeaders":["AllowHeader1","AllowHeader2"], //If it is set to be ["*"], all headers are passed through 33. }, 34 ] 35} -
Request headers
No special parameters
-
Request parameters
| Rule item | Description | Required or not | Remarks | Data type |
|---|---|---|---|---|
| bucketMirroringConfiguration | Container | Yes | Container for image back-to-origin rules | List |
| mode | The mode is back to origin or redirect. | Yes | Options: fetch (back-to-origin), redirect (redirection) | String |
| sourceUrl | Primary origin server URL | Yes | The back-to-origin address for the primary origin server. If a private bucket is selected, load "bos://endpoint/bucket". Otherwise, load the URL input by the user manually. | String |
| backSourceUrl | Backup origin server URL | No | Rules are identical to the primary origin server URL. | String |
| resource | Resources to which the rules apply | Yes | The back-to-origin condition includes a prefix and suffix separated by *. For example, "folder1/folder2" specifies the back-to-origin prefix, and ".jpeg" specifies the back-to-origin suffix. | String |
| prefix | Prefix of back-to-origin address | No | Origin server prefix | String |
| suffix | Suffix of back-to-origin address | No | For example, when it is configured as .docx, the back-to-origin object name will be extended to myobject.docx automatically. | String |
| fixedKey | Fixed name of back-to-origin address | No | When fixedKey is loaded and not empty, the back-to-origin operation will be performed to realize a fixed name. In this case, scenarios such as origin server prefix, suffix, or prefix/suffix replacement are ignored. The back-to-origin address will be sourceUrl+fixedKey. | String |
| version | Prefix replacement option of back-to-origin address | No | If version is empty, it defaults to v1, representing the old version configuration. When prefixReplace is "" in old version, no operation is performed on path prefixes in objectname. When the new version is v2, the object prefix replacement is enabled. In this case, "" loaded means the cropping of path prefixes. | String |
| prefixReplace | Prefix replacement and cropping options | No | It is effective only when the version is v2. Loading a non-empty string indicates prefix replacement, and "path1/path2/objectname” is replaced with "a/b/c/objectname". Loading an empty string indicates prefix cropping, and "path1/path2/objectname" is replaced with "objectname". | String |
| passQuerystring | Whether to pass request parameters | No | Options - true or false. It is false by default. | bool |
| storageClass | Back-to-origin storage class | No | Back-to-origin storage class in fetch mode, e.g., STANDARD | String |
| passHeaders | Headers passed through | No | Headers passed through when the origin server is requested. If it is set to be ["*"], all headers are passed through. | List |
| ignoreHeaders | Ignored headers | No | Headers ignored when the origin server is requested. | List |
| customHeaders | Custom header | No | Custom headers carried when the origin server is requested. | List |