Obtaining Back-to-Source by Mirroring Rules (SDK for C)

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

Function

This API is used to obtain the back-to-source by mirroring rules of a specified bucket.

Restrictions

To obtain the back-to-source by mirroring rules of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketMirrorBackToSource granted using IAM or GetBucketMirrorBackToSource 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.

Method

void get_bucket_mirror_back_to_source(const obs_options *options,
    obs_get_bucket_mirror_back_to_source_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
handler	Table 2*	Yes	Explanation: Callback structure, which is used to set the callback functions that handle response 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_get_bucket_mirror_back_to_source_handler
Parameter	Type	Mandatory (Yes/No)	Description
response_handler	obs_response_handler	Yes	Explanation: Response callback function structure. Restrictions: None Value range: None Default value: None
get_bucket_mirror_back_to_source_callback	Table 3*	Yes	Explanation: Pointer to the callback function of the back-to-source by mirroring rules. You can record the content of mirror_back_to_source_rules_return to callback_data in this callback. Restrictions: None Value range: None Default value: None

**Table 3** obs_get_bucket_mirror_back_to_source_callback
Parameter	Type	Mandatory (Yes/No)	Description
mirror_back_to_source_rules_return	Table 4*	Yes	Explanation: Structure array of the back-to-source by mirroring rules, including id, condition, and redirect. Restrictions: The structure and the memory to which the pointer points will be released by the SDK after the callback. Copy them if you need to keep the data. Value range: None Default value: None
rule_number	unsigned int	Yes	Explanation: Number of back-to-source by mirroring rules. Restrictions: None Value range: None Default value: None
callback_data	void *	Yes	Explanation: Pointer to the custom callback data. Restrictions: None Value range: None Default value: None

**Table 4** 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 5	Yes	Explanation: Conditions for triggering back to source by mirroring. Restrictions: None Value range: None Default value: None
redirect	Table 6	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 5** 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 6** 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 7	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 9	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 7** obs_mirror_back_to_source_public_source
Parameter	Type	Mandatory (Yes/No)	Description
source_endpoint	Table 8	Yes	Explanation: Origin server endpoint configuration, which specifies the primary and standby origin server addresses. Restrictions: None Value range: None Default value: None

**Table 8** 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 9** 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 10*	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 10** 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 obtains the back-to-source by mirroring rules of a bucket.

#include "eSDKOBS.h"
#include <stdio.h>
#include <string.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);
obs_status get_mirror_back_to_source_callback(obs_mirror_back_to_source_rule *mirror_back_to_source_rules_return,
    unsigned int rule_number, void *callback_data);
typedef struct MirrorBackInfo {
    unsigned int rule_count;
    obs_status ret_status;
} MirrorBackInfo;
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";
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_get_bucket_mirror_back_to_source_handler get_mirror_handler = {
        response_handler,
        &get_mirror_back_to_source_callback
    };
    MirrorBackInfo mirror_info = {0};
    mirror_info.ret_status = OBS_STATUS_BUTT;
    get_bucket_mirror_back_to_source(&options, &get_mirror_handler, &mirror_info);
    if (OBS_STATUS_OK == mirror_info.ret_status) {
        printf("get bucket mirror back to source successfully. rule_count: %u\n", mirror_info.rule_count);
    } else {
        printf("get bucket mirror back to source failed(%s).\n", obs_get_status_name(mirror_info.ret_status));
    }
    obs_deinitialize();
}
obs_status get_mirror_back_to_source_callback(obs_mirror_back_to_source_rule *mirror_back_to_source_rules_return,
    unsigned int rule_number, void *callback_data)
{
    MirrorBackInfo *info = (MirrorBackInfo *)callback_data;
    info->rule_count = rule_number;
    if (mirror_back_to_source_rules_return) {
        unsigned int i;
        for (i = 0; i < rule_number; i++) {
            obs_mirror_back_to_source_rule *rule = &mirror_back_to_source_rules_return[i];
            printf("rule[%u]: id=%s, agency=%s\n",
                i,
                rule->id ? rule->id : "",
                rule->redirect.agency ? rule->redirect.agency : "");
        }
    }
    return OBS_STATUS_OK;
}
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) { ((MirrorBackInfo*)callback_data)->ret_status = status; }
    if (error && error->message) { printf("Error: %s\n", error->message); }
}