Configuring Back-to-Source by Mirroring Rules (SDK for Node.js)

Function

OBS provides back to source to help you obtain the requested data from the source site if it is not found in OBS.

Restrictions

**Table 1** Restrictions
Category	Description
Bucket versions	Only buckets whose version is 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 Relationship Between Accounts and Users and Identity Provider Overview. 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. Back to source by mirroring requires that you create an IAM agency by using role/policy-based authorization to delegate OBS to pull data from its origin server. The permissions the agency should assign to OBS include obs:object:PutObject, obs:object:GetObject, obs:bucket:ListBucket, and obs:object:AbortMultipartUpload. 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 by using role/policy-based authorization.
Others	Back to source by mirroring is free now. If a request matches both back-to-source by mirroring and by redirection rules, OBS first attempts to pull the data using the mirroring rule. If the data is not found at the origin server, OBS then proceeds with the redirection rule. An object cannot match two different back-to-source by mirroring rules. When you use Range-based requests to retrieve data from origin servers whose back-to-source by mirroring configurations do not comply with the standards of RFC Range Requests, the Range header must be included in HTTP requests and its value must be validated. The Range header defines the content to be retrieved, and its value cannot exceed the size of the whole file. For instance, to retrieve an object whose size is 1024 bytes using a Range request, you can specify a Range value (from 0 to 511) to retrieve the first 512 bytes. If you specify a Range value (from 0 to 2047) to retrieve 2,048 bytes, the value is invalid and the retrieval fails.

Method

ObsClient.setBucketMirrorBackToSource(params)

Request Parameters

**Table 2** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
Bucket	string	Yes	Explanation: Bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket properties comply with those set in the first creation request. Value range: The value can contain 3 to 63 characters. Default value: None
Rules	string	Yes	Explanation: List of back-to-source by mirroring rules. The value is a string in JSON format. Restrictions: For the same bucket, prefixes specified in different rules cannot overlap with each other. The same agency is recommended. A maximum of 10 back-to-source by mirroring rules can be configured for a bucket. Default value: N/A

Responses

**Table 3** Responses
Type	Description
Table 4 NOTE: This API returns a Promise response, which requires the Promise or async/await syntax.	Explanation: Returned results. For details, see Table 4.

**Table 4** Response
Parameter	Type	Description
CommonMsg	ICommonMsg	Explanation: Common information generated after an API call is complete, including the HTTP status code and error code. For details, see Table 5.
InterfaceResult	Table 6	Explanation: Results returned for a successful call. For details, see Table 6. Restrictions: This parameter is left blank if the value of Status is greater than 300.

**Table 5** ICommonMsg
Parameter	Type	Description
Status	number	Explanation: HTTP status code returned by the OBS server. Value range: A status code is a group of digits indicating the status of a response. It ranges from 2xx (indicating successes) to 4xx or 5xx (indicating errors). For details, see Status Codes.
Code	string	Explanation: Error code returned by the OBS server.
Message	string	Explanation: Error description returned by the OBS server.
HostId	string	Explanation: Request server ID returned by the OBS server.
RequestId	string	Explanation: Request ID returned by the OBS server.
Id2	string	Explanation: Request ID2 returned by the OBS server.
Indicator	string	Explanation: Error code details returned by the OBS server.

**Table 6** BaseResponseOutput
Parameter	Type	Description
RequestId	string	Explanation: Request ID returned by the OBS server

Sample Code

You can call ObsClient.setBucketMirrorBackToSource to configure a back-to-source by mirroring rule. The sample code is as follows:

// Import the OBS library.
// Use npm for installation.
const ObsClient = require("esdk-obs-nodejs");
// Use the source code for installation.
// var ObsClient = require('./lib/obs');

// Create an ObsClient instance.
const obsClient = new ObsClient({
  // Obtain an AK and SK pair using environment variables (recommended) or import it in other ways. Using hard coding may result in leakage.
  // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
  access_key_id: process.env.ACCESS_KEY_ID,
  secret_access_key: process.env.SECRET_ACCESS_KEY,
  // (Optional) If you use a temporary AK/SK pair and a security token to access OBS, you are not advised to use hard coding, which may result in information leakage. You can obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways.
  // security_token: process.env.SECURITY_TOKEN,
  // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one currently in use.
  server: "https://obs.ap-southeast-1.myhuaweicloud.com"
});

async function setBucketMirrorBackToSource() {
  try {
    // Construct a back-to-source by mirroring rule (JSON string).
    const rules = JSON.stringify({
      rules: [{
        id: 'rule-001',
        condition: {
          httpErrorCodeReturnedEquals: '404',
          objectKeyPrefixEquals: 'video/'
        },
        redirect: {
          agency: 'your_agency',
          publicSource: {
            sourceEndpoint: {
              master: ['http://bucket1.example.com'],
              slave: ['http://bucket2.example.com']
            }
          },
          passQueryString: true,
          mirrorFollowRedirect: false
        }
      }]
    });
    const params = {
      // Specify a bucket name.
      Bucket: "examplebucket",
      // Specify the back-to-source by mirroring rule.
      Rules: rules,
    };
    // Configure the back-to-source by mirroring rule.
    const result = await obsClient.setBucketMirrorBackToSource(params);
    if (result.CommonMsg.Status <= 300) {
      console.log("Set bucket mirror back to source successful!\n");
      console.log("RequestId: %s", result.CommonMsg.RequestId);
      return;
    };
    console.log("An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    console.log("Status: %d", result.CommonMsg.Status);
    console.log("Code: %s", result.CommonMsg.Code);
    console.log("Message: %s", result.CommonMsg.Message);
    console.log("RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    console.log("An Exception was found, which means the client encountered an internal problem when attempting to communicate with OBS, for example, the client was unable to access the network.");
    console.log(error);
  };
};

setBucketMirrorBackToSource();

Parent topic: Back to Source by Mirroring (SDK for Node.js)

Previous topic: Back to Source by Mirroring (SDK for Node.js)

Next topic: Obtaining Back-to-Source by Mirroring Rules (SDK for Node.js)