Configuring a Back-to-Source by Mirroring Rule (SDK for C)

If you have any questions during development, post them on the Issues page of GitHub.

Function

Back to source by mirroring is a function provided by OBS to automatically retrieve data. You can call this API to configure a back-to-source by mirroring rule for a specified bucket. When a client accesses an object that does not exist in the bucket, OBS automatically pulls the data from the origin server, returns the data to the client, and stores the data in the bucket.

Restrictions

To configure a back-to-source by mirroring rule for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketMirrorBackToSource granted using IAM or PutBucketMirrorBackToSource granted using a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Creating a Custom Bucket Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
A bucket can have a maximum of 10 back-to-source by mirroring rules.
Each rule ID must be unique within a bucket.

Method

void set_bucket_mirror_back_to_source(const obs_options *options,
    obs_mirror_back_to_source_rule *mirror_back_to_source_rules,
    unsigned int rule_number,
    obs_response_handler *handler, void *callback_data);

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
options	const obs_options*	Yes	Explanation: Context of the requested bucket. You can set the AK, SK, endpoint, bucket, timeout interval, and temporary credentials through obs_options. Restrictions: None Value range: None Default value: None
mirror_back_to_source_rules	Table 2*	Yes	Explanation: Array of back-to-source by mirroring rules. Restrictions: None Value range: None Default value: None
rule_number	unsigned int	Yes	Explanation: Number of back-to-source by mirroring rules. Restrictions: None Value range: [1, 10] Default value: None
handler	obs_response_handler *	Yes	Explanation: A callback structure where all members are pointers to callback functions, used to set the callback functions that handle response data. You can set a callback function to copy the response data from the server to callback_data (custom callback data). Restrictions: None Value range: None Default value: None
callback_data	void *	No	Explanation: Custom callback data. Restrictions: None Value range: None Default value: None

**Table 2** obs_mirror_back_to_source_rule
Parameter	Type	Mandatory (Yes/No)	Description
id	char *	Yes	Explanation: Rule ID, which uniquely identifies a back-to-source by mirroring rule in a bucket. Restrictions: None Value range: The value can contain 1 to 256 characters. Default value: None
condition	Table 3	Yes	Explanation: Conditions for triggering back to source by mirroring. Restrictions: None Value range: None Default value: None
redirect	Table 4	Yes	Explanation: Redirection configuration, which specifies the target origin server and redirection behavior during back to source. Restrictions: None Value range: None Default value: None

**Table 3** obs_mirror_back_to_source_condition
Parameter	Type	Mandatory (Yes/No)	Description
http_error_code_returned_equals	char *	Yes	Explanation: HTTP error code returned by OBS. When OBS returns this error code, back to source by mirroring is triggered. Restrictions: None Value range: HTTP status code, for example, 404 or 403 Default value: None
key_prefix_equals	char *	No	Explanation: Object name prefix. Back to source by mirroring is triggered only for accessed objects whose names contain the specified prefix. Restrictions: None Value range: None Default value: None

**Table 4** obs_mirror_back_to_source_redirect
Parameter	Type	Mandatory (Yes/No)	Description
agency	char *	Yes	Explanation: Name of the IAM agency, which is used to authorize OBS to access the origin server. Restrictions: None Value range: None Default value: None
public_source	Table 5	Yes	Explanation: Origin server configuration, which specifies the address of the target origin server for back to source by mirroring. Restrictions: None Value range: None Default value: None
retry_conditions	char **	No	Explanation: Retry condition list. A retry is performed when a back-to-source request meets the specified conditions. Restrictions: A maximum of 20 retry conditions are supported. Value range: None Default value: None
retry_conditions_number	unsigned int	No	Explanation: Number of retry conditions. Restrictions: None Value range: [0, 20] Default value: 0
pass_query_string	int	No	Explanation: Whether to transparently transmit query strings to the origin server. Restrictions: None Value range: 0: no 1: yes Default value: 0
mirror_follow_redirect	int	No	Explanation: Whether to follow the redirection response from the origin server. Restrictions: None Value range: 0: no 1: yes Default value: 0
mirror_http_header	Table 7	No	Explanation: HTTP header configuration, which is used to control the transparent transmission, removal, and setting of HTTP headers in back-to-source requests. Restrictions: None Value range: None Default value: None
replace_key_with	char *	No	Explanation: Replaces the object name with a specified value during back to source. Restrictions: None Value range: None Default value: None
replace_key_prefix_with	char *	No	Explanation: Replaces the object name prefix with a specified value during back to source. Restrictions: None Value range: None Default value: None
vpc_endpoint_urn	char *	No	Explanation: URN of VPC Endpoint. It enables access to the origin server via the VPC Endpoint. Restrictions: None Value range: None Default value: None
redirect_without_referer	int	No	Explanation: Whether to retrieve data without including the Referer header. Restrictions: None Value range: 0: Referer is included. 1: Referer is not included. Default value: 0
mirror_allow_http_method	char **	No	Explanation: List of allowed HTTP methods. Restrictions: A maximum of two HTTP methods are allowed. Value range: None Default value: None
mirror_allow_http_method_number	unsigned int	No	Explanation: Number of allowed HTTP methods. Restrictions: None Value range: [0, 2] Default value: 0

**Table 5** obs_mirror_back_to_source_public_source
Parameter	Type	Mandatory (Yes/No)	Description
source_endpoint	Table 6	Yes	Explanation: Origin server endpoint configuration, which specifies the primary and standby origin server addresses. Restrictions: None Value range: None Default value: None

**Table 6** obs_mirror_back_to_source_source_endpoint
Parameter	Type	Mandatory (Yes/No)	Description
master	char **	Yes	Explanation: List of primary origin server addresses. Restrictions: A maximum of five primary origin server addresses are allowed.
master_number	unsigned int	Yes	Explanation: Number of primary origin server addresses. Restrictions: None Value range: [1, 5] Default value: None
slave	char **	No	Explanation: List of standby origin server addresses, which are used when the primary origin servers are unavailable. Restrictions: A maximum of five standby origin server addresses are allowed.
slave_number	unsigned int	No	Explanation: Number of standby origin server addresses. Restrictions: None Value range: [0, 5] Default value: 0

**Table 7** obs_mirror_back_to_source_http_header
Parameter	Type	Mandatory (Yes/No)	Description
pass_all	int	No	Explanation: Whether to transparently transmit all HTTP headers to the origin server. Restrictions: None Value range: 0: Do not transparently transmit all headers. 1: Transparently transmit all headers. Default value: 0
pass	char **	No	Explanation: List of HTTP headers to be transparently transmitted. Restrictions: A maximum of 10 headers are supported. Value range: None Default value: None
pass_number	unsigned int	No	Explanation: Number of HTTP headers to be transparently transmitted. Restrictions: None Value range: [0, 10] Default value: 0
remove	char **	No	Explanation: List of HTTP headers to be removed. Restrictions: A maximum of 10 headers are supported. Value range: None Default value: None
remove_number	unsigned int	No	Explanation: Number of HTTP headers to be removed. Restrictions: None Value range: [0, 10] Default value: 0
set	Table 8*	No	Explanation: List of HTTP headers to be set. Restrictions: A maximum of 10 headers are supported. Value range: None Default value: None
set_number	unsigned int	No	Explanation: Number of HTTP headers to be set. Restrictions: None Value range: [0, 10] Default value: 0

**Table 8** obs_mirror_back_to_source_set_http_header
Parameter	Type	Mandatory (Yes/No)	Description
key	char *	Yes	Explanation: Name of the HTTP header. Restrictions: None Value range: None Default value: None
value	char *	Yes	Explanation: Value of the HTTP header. Restrictions: None Value range: None Default value: None

Sample Code

This example configures a simple back-to-source by mirroring rule for 404 responses.

#include "eSDKOBS.h"
#include <stdio.h>
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
int main()
{
    obs_initialize(OBS_INIT_ALL);
    obs_options options;
    init_obs_options(&options);
    // Enter the endpoint corresponding to the bucket for host_name. CN-Hong Kong is used here as an example. Replace it with the one currently in use.
    options.bucket_options.host_name = "obs.ap-southeast-1.myhuaweicloud.com";
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK and store them in the configuration file or environment variables.
    // In this example, the AK and SK are stored in environment variables for identity authentication. Before running the code in this example, configure local environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    options.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    options.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    options.bucket_options.bucket_name = "example-bucket-name";
    // Configure the primary origin server address.
    char *master_endpoints[] = {"https://source.example.com"};
    obs_mirror_back_to_source_source_endpoint source_endpoint = {0};
    source_endpoint.master = master_endpoints;
    source_endpoint.master_number = 1;
    // Configure origin server information.
    obs_mirror_back_to_source_public_source public_source = {0};
    public_source.source_endpoint = source_endpoint;
    // Configure a redirection rule for back to source by mirroring.
    obs_mirror_back_to_source_redirect redirect = {0};
    redirect.agency = "your-agency-name";
    redirect.public_source = public_source;
    redirect.pass_query_string = 1;
    // Configure conditions that trigger back to source by mirroring.
    obs_mirror_back_to_source_condition condition = {0};
    condition.http_error_code_returned_equals = "404";
    condition.key_prefix_equals = "image/";
    // Configure a back-to-source rule by mirroring rule.
    obs_mirror_back_to_source_rule rule = {0};
    rule.id = "rule1";
    rule.condition = condition;
    rule.redirect = redirect;
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_status ret_status = OBS_STATUS_BUTT;
    set_bucket_mirror_back_to_source(&options, &rule, 1, &response_handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("set bucket mirror back to source successfully.\n");
    } else {
        printf("set bucket mirror back to source failed(%s).\n", obs_get_status_name(ret_status));
    }
    obs_deinitialize();
}
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    (void)properties; (void)callback_data;
    return OBS_STATUS_OK;
}
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
    if (callback_data) { *(obs_status*)callback_data = status; }
    if (error && error->message) { printf("Error: %s\n", error->message); }
}