Feature description

This interface allows setting the bucket's origin rules. You can configure multiple rules based on different conditions in the rules.

Notes

Only the bucket owner can set the origin rules.

Up to 20 origin rules can be set.

For detailed information, see mirroring back to origin Notes and redirect back to origin Notes.

Request syntax

PUT /?mirror HTTP/1.1​
Host: bucketname.tos-cn-beijing.volces.com​
Date: Fri, 30 Jul 2021 08:05:36 +0000​
Authorization: authorization string​
{​
    "Rules":[{​
        "ID":"1",​
        "Condition":{​
            "HttpCode":404,  ​
            "KeyPrefix":"object-key-prefix",  ​
            "KeySuffix": "object-key-suffix",​
            "AllowHost": [​
                    "example.volcengine.com"​
                ],​
            "HttpMethod": [​
                    "GET",​
                    "HEAD"​
               ]​
        },​
        "Redirect":{​
            "RedirectType": "Mirror",        ​
            "FetchSourceOnRedirect": false,​
            "PublicSource":{      ​
                "SourceEndpoint":{ ​
                    "Primary":["http://abc.123/"],​
                    "Follower":["http://abc.456/"]​
                }​
            },​
            "PassQuery": true,     ​
            "FollowRedirect": true, ​
            "MirrorHeader":{       ​
                "PassAll": true,​
                "Pass": ["aaa", "bbb"],​
                "Remove": ["xxx", "yyy"]​
            },​
            "Transform": { ​
               "WithKeyPrefix": "addtional-key-prefix", ​
               "WithKeySuffix": "addtional-key-suffix",  ​
               "ReplaceKeyPrefix": { ​
                  "KeyPrefix": "key-prefix",​
                  "ReplaceWith": "replace-with"​
               }​
            }​
        }​
    }]​
}​

Request parameters and headers

This request uses public request headers, see public parameters.

Name	Location	Type	Required	Sample value	Note
mirror	Query	String	Yes	-	Special identifier representing the PutBucketMirrorBack request.

Request body elements

Rules

Name	Parameter type	Required	Sample value	Note
Rules	Array	Yes	-	Origin fetch policy rule array. Root node, no parent node.
ID	String	No	1	Rule ID. The unique identifier for the origin rule configured on the current bucket. You can set it yourself to differentiate multiple rules. Restrictions are as follows: The characters support letters, numbers,-and_。 Supports up to 32 characters. Parent node: Rules.

Condition

Name	Type	Required	Sample value	Note
Condition	Object	Yes	-	Condition to trigger back-to-origin functionality. Parent node: Rules.
HttpCode	int	Yes	404	Error code that triggers the origin fetch function. When a download request returns this error code, it triggers the origin fetch function. Limit: Currently only 404 is supported. Parent node: Condition
KeyPrefix	String	No	object-key-prefix	Prefix of the object name matched for the origin object. Limit: supports up to 512 characters. Parent node: Condition
KeySuffix	String	No	object-key-suffix	The object name suffix that matches the back-to-origin target. Limit: supports up to 512 characters. Parent node: Condition
AllowHost	Array	Not supported	["example.volcengine.com"]	Only requests with specified domain names will trigger origin fetch. The domain must be able to access the bucket. We recommend using the custom domain associated with the bucket. Limit: supports up to 30 domains. Parent node: Condition
HttpMethod	Array	No	["GET","HEAD"]	Request types that trigger back-to-origin, with the following values: [\"GET\",\"HEAD\"]: indicates that both GetObject and HeadObject requests can trigger back-to-origin. [\"GET\"]: indicates that only GetObject requests can trigger back-to-origin. Defaults to [\"GET\"].

Redirect

Name	Type	Required	Sample value	Note
Redirect	Object	Yes	-	Specify the action to perform after matching this rule. Parent node: Rules
RedirectType	String	No	Mirror	Specify the type of redirect. Value range: Mirror: mirror back to origin. Async: redirect back to origin. Parent node: Redirect
FetchSourceOnRedirect	Boolean	No	false	Whether to pull data from the configured origin after redirection. The values are described as follows: true: Pull data from the configured origin after redirection. false: Do not pull data from the configured origin after redirection. Parent node: Redirect
FetchSourceOnRedirectWithQuery	Boolean	No	false	Whether to carry request parameters when pulling data after redirection; if not configured, inherits PassQuery setting: true: carry request parameters. false: no request parameters carried Parent node: Redirect
PublicSource	Object	No	-	Backsource address configuration when the origin is a public bucket. For details, please refer to the PublicSource below. Parent node: Redirect
PrivateSource	Object	No	-	Back-to-origin address configuration for private buckets as source stations. For details, see the following PrivateSource. Parent node: Redirect
PassQuery	Boolean	No	true	Whether to include request parameters when executing redirect or mirror origin rules. The options are as follows: true: include request parameters. false: do not include request parameters. warning Even if set to true, Query parameters related to TOS authentication will not be included. Parent node: Redirect
FollowRedirect	Boolean	No	true	If the mirror origin response is a 3xx status, whether to continue redirecting to the specified Location to fetch data. The options are as follows: true: TOS will continue to request the address corresponding to Location. false: TOS will return 302. Parent node: Redirect
MirrorHeader	Object	No	-	Header carried when specifying the image origin fallback. Parent node: Redirect
PassAll	Boolean	No	true	Whether to forward all HTTP headers to the origin server. The options are as follows: true: forward all HTTP headers to the origin server. false: do not forward all HTTP headers to the origin server. The following HTTP header types do not support forwarding: Host Content-Length Date Authorization Parent node: MirrorHeader
Pass	Array	Not supported	["aaa", "bbb"]	Pass the specified header to the origin server. Limit: maximum quantity 64. Parent node: MirrorHeader
Remove	Array	No	["xxx", "yyy"]	Prohibit forwarding specified headers to the origin server. Limit: maximum quantity 64. Parent node: MirrorHeader
Transform	Object	No	-	Defines the transformation of the object name for the origin request. Parent node: Redirect
WithKeyPrefix	String	No	addtional-key-prefix	Add a prefix before the object name when requesting the origin server. Limit: supports up to 512 characters. Parent node: Transform
WithKeySuffix	String	No	addtional-key-suffix	A suffix added after the object name when requesting the origin server. Limit: supports up to 512 characters. Parent node: Transform
ReplaceKeyPrefix	Object	No	-	Replace the object name prefix when requesting the origin server. Parent node: Transform
KeyPrefix	String	No	key-prefix	When requesting the origin, the object name prefix to be replaced. Limit: up to 512 characters supported. Parent node: ReplaceKeyPrefix
ReplaceWith	String	No	replace-with	The value after replacing the object name prefix when requesting the origin server. Limit: supports up to 512 characters. Parent node: ReplaceKeyPrefix

PublicSource

Name	Type	Required	Sample value	Note
PublicSource	Object	No	-	Origin address configuration for public buckets. Parent node: Redirect
SourceEndpoint	Object	No	-	Publicly accessible source endpoint address. Parent node: PublicSource tip Required when the origin is a public bucket.
Primary	Array	No	["http://abc.123/"]	Origin site address. Limit: maximum length 255, supports up to 5 origin addresses. Parent node: SourceEndpoint The origin will prioritize selecting the source from this configuration.
Follower	Array	No	["http://abc.456/"]	Origin server address. Limit: maximum length 255, supports up to 5 origin addresses. Parent node: SourceEndpoint Select the origin from this configuration when all origin retrievals in Primary fail

PrivateSource

Name	Type	Required	Sample value	Description
PrivateSource	Object	No	-	Configure the back-to-origin address when the origin is a private bucket. Parent node: Redirect
SourceEndpoint	Object	No	-	Origin server fallback address configuration for private buckets. Parent node: PrivateSource
Primary	Array	No	-	Requested origin address, supports up to 5 origin addresses Parent node: SourceEndpoint tip Required when the origin is a private bucket
Endpoint	String	No	http://s3.bj.bcebos.com	Access domain name of the origin service provider, excluding bucket name, maximum length 255. Parent node: Primary tip Required when the origin is a private bucket.
BucketName	String	No	bucket	Name of the origin bucket. Parent node: Primary tip Required when the origin is a private bucket.
CredentialProvider	Object	No	-	Private origin authorization method. Parent node: Primary tip Required when the origin is a private bucket.
Role	String	No	ServiceRoleBackSourceAccessTOS	Name of AssumeRole, used only for authentication when accessing private buckets in TOS using AssumeRole. Parent node: CredentialProvider tip Role authentication and AK/SK authentication are mutually exclusive; they cannot be set simultaneously.
Region	String	No	cn-beijing	Region of the origin bucket; required when using AK/SK authentication. Parent node: CredentialProvider
StaticCredential	Object	No	-	Authenticate using AK/SK method. Parent node: CredentialProvider tip Choose either AK/SK authentication or Role authentication; these cannot be set simultaneously.
StorageVendor	String	No	S3	The options for origin service providers are as follows: BOS: Baidu Cloud S3: Other S3 protocol cloud providers Parent node: StaticCredential
AK	String	No	AKLTNDk3NDMxY2NmNzNhNGNiN****	The AccessKey ID of the origin bucket, required when using AK/SK authentication. Parent node: StaticCredential
SK	String	No	AADFSDfdsfa3ewdr23==d****	SecretKey of the origin bucket, required when using AK/SK authentication. Parent node: StaticCredential
SKEncryptType	String	No	AES256	The encryption method used by SecretKey. Values are as follows: Empty: SecretKey is in plain text. After receiving the SecretKey, the server encrypts and stores it. AES256: SecretKey is encrypted with the AES256 algorithm on the server side. After receiving the SecretKey, the server parses it and stores it in encrypted form. tip Since the initial creation of the origin rule uses AES256 to encrypt the SecretKey, when modifying the origin rule without changing the SecretKey parameter, the SecretKey must first be decrypted before being re-encrypted and stored. Therefore, you can set SKEncryptType to AES256 only when modifying other parameters without changing the SecretKey parameter by calling the PutBucketMirrorBack interface to update the origin rule. Parent node: StaticCredential

Response headers

This request returns public response headers, see public parameters.

Response body elements

This response does not use message elements.

Sample request

Sample request 1: origin is a public bucket

PUT /?mirror HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string
{
"Rules":[{
"ID":"xxx",
"Condition":{
"HttpCode":404,
"KeyPrefix":"prefix"
},
"Redirect":{
"PublicSource":{
"SourceEndpoint":{
"Primary":["http://abc.123/"]
}
},
"PassQuery":true,
"FollowRedirect":true,
"MirrorHeader":{"PassAll":true}
}
}]
}

Sample request 2: origin is a TOS private bucket

PUT /?mirror HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string
{
"Rules":[{
"ID":"xxx",
"Condition":{
"HttpCode":404,
"KeyPrefix":"prefix"
},
"Redirect":{
"PrivateSource":{
"SourceEndpoint":{
"Primary": [{
"Endpoint": "http://tos-cn-beijing.volces.com",
"BucketName": "bucket",
"CredentialProvider": {
"Role": "ServiceRoleBackSourceAccessTOS"
}
}]
}
},
"PassQuery":true,
"FollowRedirect":true,
"MirrorHeader":{"PassAll":true}
}
}]
}

Sample request 3: origin is a private bucket from other S3-compatible cloud providers

PUT /?mirror HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string
{
"Rules":[{
"ID":"xxx",
"Condition":{
"HttpCode":404,
"KeyPrefix":"prefix"
},
"Redirect":{
"PrivateSource":{
"SourceEndpoint":{
"Primary": [{
"Endpoint": "http://s3.com",
"BucketName": "bucket",
"CredentialProvider": {
"Region": "cn-beijing",
"StaticCredential": {
"StorageVendor": "S3",
"AK": "AKLTNDk3NDMxY2NmNzNhNGNiN****",
"SK":"AADFSDfdsfa3ewdr23==d****"
}
}
}]
}
},
"PassQuery":true,
"FollowRedirect":true,
"MirrorHeader":{"PassAll":true}
}
}]
}

Sample response

Torch Object Storage