Help Center/ Object Storage Service/ API Reference/ Bucket APIs/ Back to Source by Mirroring/ Configuring Mirroring-based Back-to-Source Rules

Updated on 2026-07-27 GMT+08:00

Configuring Mirroring-based Back-to-Source Rules

Function

OBS provides the back-to-source function. If the requested data cannot be found, OBS can obtain the data from the origin server based on back-to-source rules. This API is used to configure back-to-source by mirroring rules for a bucket. For more information about back to source by mirroring, see Using Mirroring-Based Back to Source to Retrieve Data.

Constraints

**Table 1** Back to source constraints
Category	Description
Bucket versions	Only buckets of version 3.0 or later support back to source by mirroring.
Time	It takes about five minutes to apply any changes to a back-to-source by mirroring rule.
Number of rules	A maximum of 10 back-to-source by mirroring rules can be configured for a bucket.
Functions	Anonymous users are not allowed to configure back-to-source by mirroring rules. Federated users cannot use back to source by mirroring. For more information about federated users, see What Are the Relationships Between a Huawei Cloud Account, HUAWEI ID, IAM User, and Federated User? and Introduction to Identity Providers. Parallel file systems do not support back-to-source by mirroring rules. Static website hosting does not support back to source by mirroring. Specifically, if 404 is returned when you use a static website domain name to download an object, back to source by mirroring will not be triggered. A bucket cannot mirror itself. Currently, back to source by mirroring from private buckets is only supported for some cloud vendors. In back-to-source setups, two buckets cannot act as each other's origin. For example, if bucket A is the origin for bucket B, bucket B cannot be the origin for bucket A. Transfer-Encoding: chunked cannot be used for the origin server to transmit data, or the origin pull will fail. The response to the request for downloading an object from the origin server must contain the Content-Length header to specify the size of the source object. To achieve this, in the Create/Edit Back-to-Source Rule window, choose Pass all parameters for HTTP Header Pass Rule, enable Do not pass specified parameters, and add Accept-Encoding. If both a CDN acceleration domain name and a back-to-source by mirroring rule are configured and range requests are enabled on CDN, the origin server must return at least one of the Etag and Last-Modified headers. Otherwise, the request may be interrupted. If NGINX was deployed as a reverse proxy for your origin server, turn off chunked_transfer_encoding of the NGINX. location / { chunked_transfer_encoding off; }
Permissions	To configure, obtain, or delete back-to-source by mirroring rules, you must have the Tenant Administrator permission assigned by using role/policy-based authorization of IAM. You must create a cloud service agency using role/policy-based authorization of IAM to delegate OBS to pull data from the origin server. The agency must include the obs:object:PutObject, obs:object:GetObject, obs:bucket:ListBucket, and obs:object:AbortMultipartUpload permissions. If SSE-KMS is enabled for a bucket, the kms:cmk:get, kms:cmk:list, kms:cmk:create, kms:dek:create, and kms:dek:crypto permissions must be configured for the IAM agency for OBS by using role/policy-based authorization.
Others	Back to source by mirroring is free now. An object cannot match two different back-to-source by mirroring rules.

Authorization

To call this API, you must be the bucket owner or have the Tenant Administrator permission. To configure the Tenant Administrator permission, you need to use role/policy-based authorization (IAM v3 APIs in the old IAM version). For details, see Using IAM for Authorization.

URI

PUT /

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

Request Syntax

PUT /?mirrorBackToSource HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Authorization: authorization
Content-Type: application/json
Content-Length: length
Date: date

{
    "rules": [{
        "id": "abc123",
        "condition": {
            "httpErrorCodeReturnedEquals": 404,
            "objectKeyPrefixEquals": "video/"
        },
        "redirect": {
            "agency": "agency",
            "publicSource": {
                "sourceEndpoint": {
                    "master":["http://bucket1.xxx.yyy.com", "https://bucket2.xxx.yyy.com"],
                    "slave": ["http://bucket3.xxx.yyy.com", "https://bucket4.xxx.yyy.com"]
                }
            },
            "retryConditions": ["4XX", "5XX"],
            "passQueryString": true,
            "mirrorFollowRedirect": true,
            "redirectWithoutReferer": true,
            "mirrorAllowHttpMethod":["HEAD"],
            "mirrorHttpHeader": {
                "passAll": false,
                "pass": ["content-encoding"],
                "remove": ["content-type"],
                "set": [{
                    "key": "helloworld",
                    "value": "2222"
                }]
            },
            "replaceKeyWith": "prefix${key}suffix",
            "vpcEndpointURN": "001"
        }
    }]
}

URI Parameters

This request contains no URI parameters.

Request Headers

This request uses common headers. For details, see Table 3.

Request Body

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
rules	Yes	Container	Definition Array of rules. rules is the parent node of id, condition, and redirect. Constraints For the same bucket, prefixes of different rules cannot be the same or contain each other. The same agency is recommended. Range A maximum of 10 mirroring-based, back-to-source rules can be configured for a bucket. Therefore, the array can include 1 to 10 rules. For details, see Table 3. Default Value N/A

**Table 3** rules parameters
Parameter	Mandatory	Type	Description
id	Yes	String	Definition Unique ID of a back-to-source rule configured for the current bucket. Constraints The rule ID must be unique in the bucket. Range The value can contain 1 to 256 characters. Only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-) are allowed. Default Value N/A
condition	Yes	Container	Definition Condition for triggering back-to-source. condition is the parent node of httpErrorCodeReturnedEquals and objectKeyPrefixEquals. Constraints N/A Range For details, see Table 4. Default Value N/A
redirect	Yes	Container	Definition Parameters for implementing back-to-source. redirect is the parent node of agency, publicSource, retryConditions, passQueryString, mirrorFollowRedirect, replaceKeyWith, replaceKeyPrefixWith, vpcEndpointURN, redirectWithoutReferer, and mirrorAllowHttpMethod. Constraints N/A Range For details, see Table 5. Default Value N/A

**Table 4** condition parameters
Parameter	Mandatory	Type	Description
httpErrorCodeReturnedEquals	Yes	String	Definition Status code that triggers back-to-source. When this error is returned for a download request, back-to-source is triggered. Constraints N/A Range 404: The object does not exist in the OBS bucket. Default Value 404
objectKeyPrefixEquals	No	String	Definition Object name prefix that triggers back-to-source. Back-to-source is performed only when the specified object name prefix is included in the request. Constraints If this parameter is left blank, all objects are matched by default. For the same bucket, prefixes of different rules cannot be the same or contain each other. Range A string of 0 to 1,023 characters Default Value N/A

**Table 5** redirect parameters
Parameter	Mandatory	Type	Description
agency	Yes	String	Definition Agency name. With an agency, you can grant OBS the permissions to query whether a specified object exists in the bucket and to upload objects to the bucket. Constraints N/A Range N/A Default Value N/A
publicSource	No	Container	Definition Publicly accessible source configuration. This parameter is mandatory when the source is a publicly accessible resource. publicSource is the parent node of sourceEndpoint. Constraints N/A Range For details, see Table 6. Default Value N/A
retryConditions	No	Array	Definition Condition for switching the source address. Constraints 4XX and a specific status code starting with 4 cannot be configured together. This rule works the same for 5XX and a status code starting with 5. Range 4XX, 5XX, 400–499, and 500–599 (a maximum of 20 status codes can be configured at the same time) Default Value N/A
passQueryString	Yes	Boolean	Definition Whether to include the request character string. Constraints If it is set to true but the query parameter contains the signature information, the signature information is removed and the remaining parameters are passed. Range false: The queryString value in the OBS request is not passed to the source. true: The queryString value in the OBS request is passed to the source. Default Value false
mirrorFollowRedirect	Yes	Boolean	Definition Whether to obtain resources by redirecting the request based on the 3XX response from the source. Constraints N/A Range false: OBS transparently passes the 3XX response and does not return resources. true: OBS returns resources by redirecting the request based on the 3XX response. Default Value false
mirrorHttpHeader	No	Container	Definition Rules for passing HTTP headers. mirrorHttpHeader is the parent node of passAll, pass, remove, and set. Constraints N/A Range For details, see Table 8. Default Value N/A
replaceKeyWith	No	String	Definition Rule for replacing the object name during back-to-source retrieval. You can use ${key}, prefix, and suffix. Constraints If both replaceKeyWith and replaceKeyPrefixWith are left blank, replaceKeyPrefixWith takes effect. The request is invalid if both parameters are specified. Range prefix${key}suffix: adds a prefix or suffix. ${key}: adds no prefix or suffix. ${key} is the keyword, prefix is the prefix to be added, and suffix is the suffix to be added. The total length of prefix and suffix ranges from 0 to 1,023 characters. Default Value N/A
replaceKeyPrefixWith	No	String	Definition Character string used to replace the prefix in objectKeyPrefixEquals. When objects are downloaded from the source, the system replaces the object name prefix with the prefix specified using this parameter. Constraints If both replaceKeyWith and replaceKeyPrefixWith are left blank, replaceKeyPrefixWith takes effect. The request is invalid if both parameters are specified. Range A string of 0 to 1,023 characters Default Value N/A
vpcEndpointURN	No	String	Definition URN of VPC Endpoint service. Constraints N/A Range A string of 0 to 127 characters Default Value N/A
redirectWithoutReferer	No	Boolean	Definition Whether to include the original host as the referer header in the redirect request. Constraints N/A Range false: The original host is included as the referer header in the redirect request. true: The original host is not included as the referer header in the redirect request. Default Value false
mirrorAllowHttpMethod	No	Array	Definition Request method that supports transparent passing. Constraints N/A Range GET: obtains objects from a bucket. HEAD: obtains the object metadata from a bucket. Default Value N/A

**Table 6** publicSource parameters
Parameter	Mandatory	Type	Description
sourceEndpoint	No	Container	Definition Publicly accessible source address. sourceEndpoint is the parent node of master and slave. Constraints N/A Range For details, see Table 7. Default Value N/A

**Table 7** sourceEndpoint parameters
Parameter	Mandatory	Type	Description
master	No	Array	Definition Primary source address. If the source is a bucket accessible over HTTP, set this address to the bucket domain name. If the source is a private bucket hosted by another cloud vendor, set this address to the regional domain name. Constraints The primary source address is preferentially used during back-to-source. When one to five primary source addresses are configured, they are used in polling mode. If two or more primary addresses are configured, when the first request to a primary address fails and the retry conditions are met, another primary address will be used for a retry. Range The format of a single source address is https://xxx.yyy.zzz or http://xxx.yyy.zzz. The value can contain 10 to 255 characters. Default Value N/A
slave	No	Array	Definition Secondary source address. If the source is a bucket accessible over HTTP, set this address to the bucket domain name. If the source is a private bucket hosted by another cloud vendor, set this address to the regional domain name. Constraints When back-to-source requests fail on the primary source address, the system automatically retries using the secondary source address. A maximum of five secondary addresses can be configured. Range The format of a single source address is https://xxx.yyy.zzz or http://xxx.yyy.zzz. The value can contain 10 to 255 characters. Default Value N/A

**Table 8** mirrorHttpHeader parameters
Parameter	Mandatory	Type	Description
passAll	No	Boolean	Definition Whether to pass all HTTP headers to the source. Constraints passAll and pass are mutually exclusive. The following HTTP headers cannot be passed: Headers starting with the following prefixes: x-obs- x-amz- All standard HTTP headers, for example: Content-Length Authorization Date Range false: Do not pass all HTTP headers to the source. true: Pass all HTTP headers to the source. Default Value false
pass	No	Array	Definition List of HTTP headers to be passed. Constraints Only letters, digits, hyphens (-), and underscores (_) are allowed. Range A maximum of 10 HTTP headers are supported. The length of each header ranges from 1 to 63 characters. Default Value N/A
remove	No	Array	Definition List of HTTP headers that cannot be passed. Constraints The priority of remove is higher than that of pass and passAll. Only letters, digits, hyphens (-), and underscores (_) are allowed. Range A maximum of 10 HTTP headers are supported. The length of each header ranges from 1 to 63 characters. Default Value N/A
set	No	Array	Definition Custom HTTP headers to be passed. Constraints The priority of set is higher than that of remove, pass, and passAll. If a custom referrer header is included, redirectWithoutReferer must be set to true. Otherwise, there will be an overwriting. Range A maximum of 10 HTTP headers are supported in one set. Each header contains a key and a value. For details about keys and values, see Table 9. Default Value N/A

**Table 9** set parameters
Parameter	Mandatory	Type	Description
key	No	String	Definition Key of a custom HTTP header to be passed. Constraints Each key must be unique. Only letters, digits, hyphens (-), and underscores (_) are allowed. Range A string of 1 to 63 characters Default Value N/A
value	No	String	Definition Value of a custom HTTP header to be passed. Constraints N/A Range A string of 1 to 2,048 characters Default Value N/A

Response Syntax

HTTP/1.1 status
Server: OBS
Date: date
Content-Length: length

Response Headers

This response uses common headers. For details, see Table 1.

Response Body

This response contains no elements.

Error Responses

No special errors. You can find all errors inError Code Overview and Table 3.

Sample Request

PUT /?mirrorBackToSource HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:sc2PM13Wlfcoc/YZLK0MwsI2Zpo=
Content-Type: application/json
Content-Length: 1049
Date: Tue, 21 Jul 2020 15:38:30 GMT

{
    "rules": [{
        "id": "abc123",
        "condition": {
            "httpErrorCodeReturnedEquals": "404",
            "objectKeyPrefixEquals": "video/"
        },
        "redirect": {
            "agency": "agency",
            "publicSource": {
                "sourceEndpoint": {
                    "master":["http://bucket1.xxx.yyy.com", "https://bucket2.xxx.yyy.com"],
                    "slave": ["http://bucket3.xxx.yyy.com", "https://bucket4.xxx.yyy.com"]
                }
            },
            "retryConditions": ["4XX", "5XX"],
            "passQueryString": true,
            "mirrorFollowRedirect": true,
            "redirectWithoutReferer": true,
            "mirrorAllowHttpMethod":["HEAD"],
            "mirrorHttpHeader": {
                "passAll": false,
                "pass": ["content-encoding"],
                "remove": ["content-type"],
                "set": [{
                    "key": "helloworld",
                    "value": "2222"
                }]
            },
            "replaceKeyWith": "prefix${key}suffix",
            "vpcEndpointURN": "001"
        }
    }]
}

Sample Response

HTTP/1.1 201 Created
Server: OBS
Date: Tue, 07 Jul 2020 07:29:13 GMT
Content-Length: 0

Helpful Links

For more information about back to source by mirroring, see Using Back to Source by Mirroring to Retrieve Data.
For details about the billing items involved in API operations, see Billing Items.

Parent Topic: Back to Source by Mirroring

Previous topic: Back to Source by Mirroring

Next topic: Obtaining Mirroring-based Back-to-Source Rules

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

For any further questions, feel free to contact us through the chatbot.

Chatbot