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

Updated on 2026-09-11 GMT+08:00

Obtaining Mirroring-based Back-to-Source Rules

Function

This API is used to obtain mirroring-based, back-to-source rules of a bucket if such rules have been configured. If such rules exist, a success message is returned with status code 200. 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 through 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, kms:dek:encrypt, and kms:dek:decrypt permissions must be configured for the IAM agency for OBS 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

GET /

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

GET /?mirrorBackToSource HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Authorization: authorization
Date: date

URI Parameters

This request contains no URI parameters.

Request Headers

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

Request Body

This request contains no request body parameters.

Response Syntax

HTTP/1.1 status_code
Server: OBS
Date: date
Content-Type: type
Content-Length: length

{
    "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,
            "mirrorHttpHeader": {
                "passAll": false,
                "pass": ["content-encoding"],
                "remove": ["content-type"],
                "set": [{
                    "key": "helloworld",
                    "value": "2222"
                }]
            },
            "replaceKeyPrefixWith": "picture/",
            "vpcEndpointURN": "001"
        }
    }]
}

Response Headers

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

Response Body

This response body contains the JSON configuration of the mirroring-based back-to-source rules.

**Table 2** Response body parameters
Parameter	Mandatory	Type	Description
rules	Yes	Container	Definition Array of rules. For the same bucket, prefixes of different rules cannot be the same or contain each other. The same agency is recommended. rules is the parent node of id, condition, and redirect. 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 mirroring-based, back-to-source rule configured for the current bucket. 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. 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. 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. 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. 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. Range 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. For details, see Table 6.
retryConditions	No	Array	Definition Condition for switching the source address. 4XX, 5XX, 400–499, and 500–599 (a maximum of 20 status codes can be configured at the same time). 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.
passQueryString	Yes	Boolean	Definition Whether to include the request character string. If the value is 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.
mirrorFollowRedirect	Yes	Boolean	Definition Whether to obtain resources by redirecting the request based on the 3XX response from the source. 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.
mirrorHttpHeader	No	Container	Definition Rules for passing HTTP headers. mirrorHttpHeader is the parent node of passAll, pass, remove, and set. For details, see Table 8.
replaceKeyWith	No	String	Definition Rule for replacing the object name during back-to-source retrieval. You can use ${key}, prefix, and suffix. If both replaceKeyWith and replaceKeyPrefixWith are left blank, replaceKeyPrefixWith takes effect. The request is invalid if both parameters are specified. Range prefix${key}suffix: A prefix or suffix is added. ${key}: No prefix or suffix is added. ${key} is the keyword, prefix is the added prefix, and suffix is the added suffix. The total length of prefix and suffix ranges from 0 to 1,023 characters.
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. 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
vpcEndpointURN	No	String	Definition URN of VPC Endpoint service. Range A string of 0 to 127 characters
redirectWithoutReferer	No	Boolean	Definition Whether to include the original host as the Referer header in the redirect request. 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.
mirrorAllowHttpMethod	No	Array	Definition Request method that supports transparent passing. Value options: GET: obtains objects from a bucket. HEAD: obtains the object metadata from a bucket.

**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. For details, see Table 7.

**Table 7** sourceEndpoint parameters
Parameter	Mandatory	Type	Description
master	No	Array	Definition Primary source address. 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. If the source is a bucket accessible over HTTP, this address is the bucket domain name. If the source is a private bucket hosted by another cloud vendor, this address is the regional domain name. 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.
slave	No	Array	Definition Secondary source address. 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. 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. If the source is a bucket accessible over HTTP, this address is the bucket domain name. If the source is a private bucket hosted by another cloud vendor, this address is the regional domain name.

**Table 8** mirrorHttpHeader parameters
Parameter	Mandatory	Type	Description
passAll	No	Boolean	Definition Whether to pass all HTTP headers to the source. 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: All HTTP headers are passed to the source.
pass	No	Array	Definition List of HTTP headers passed. Only letters, digits, hyphens (-), and underscores (_) are allowed. A maximum of 10 HTTP headers are displayed. The length of each header ranges from 1 to 63 characters.
remove	No	Array	Definition List of HTTP headers that are not passed. Only letters, digits, hyphens (-), and underscores (_) are allowed. A maximum of 10 HTTP headers are displayed. The length of each header ranges from 1 to 63 characters. The priority of remove is higher than that of pass and passAll.
set	No	Array	Definition Custom HTTP headers that are passed. A maximum of 10 HTTP headers are displayed. Each header contains a key and a value. For details about keys and values, see Table 9. The priority of set is higher than that of remove, pass, and passAll. If a custom Referer header is included, redirectWithoutReferer must be set to true. Otherwise, there will be an overwriting.

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

Error Responses

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

Sample Request

GET /?mirrorBackToSource HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:sc2PM13Wlfcoc/YZLK0MwsI2Zpo=
Date: Tue, 21 Jul 2020 22:28:46 GMT

Sample Response

HTTP/1.1 200 OK
Server: OBS
Date: Tue, 07 Jul 2020 07:28:46 GMT
Content-Type: application/json
Content-Length: 1063
{
    "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,
            "mirrorHttpHeader": {
                "passAll": false,
                "pass": ["content-encoding"],
                "remove": ["content-type"],
                "set": [{
                    "key": "helloworld",
                    "value": "2222"
                }]
            },
            "replaceKeyPrefixWith": "picture/",
            "vpcEndpointURN": "001"
        }
    }]
}

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: Configuring Mirroring-based Back-to-Source Rules

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