Configuring Object Lifecycle Rules (SDK for C)

Function

Configuring object lifecycle rules is to set the expiration time (using x-obs-expires) for objects. Objects will be automatically deleted by the OBS server after the specified number of days. The OBS SDK for C allows you to configure a lifecycle rule for an object in either of the following ways:

• Specifying the expiration time during upload: When uploading an object, you can specify the expiration time using the obs_expires field in the obs_put_properties structure. The setting takes effect immediately after the object is uploaded.
• Setting the expiration time after upload: You can use the set_object_metadata API to modify the expiration time of an existing object.

Restrictions

• To configure a lifecycle rule for an object, you must be the bucket owner or have permission to upload objects or set object properties. When granted using IAM, the required permission is obs:object:PutObject or obs:object:ModifyObjectMetaData. When granted using a bucket policy, the required permission is PutObject or ModifyObjectMetaData. 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.
• The unit of obs_expires is day. The expiration time calculated based on the specified number of days cannot be earlier than the current time. For example, if an object was uploaded 10 days ago, you must specify a value greater than or equal to 10.
• An object will be automatically deleted by the OBS server once it expires. This operation is irreversible.

Method

Scenario 1: configuring a lifecycle rule when uploading an object

When uploading an object, you can set the number of days after which the object expires using the obs_expires field in the obs_put_properties structure. This field applies to all upload APIs (such as put_object, put_object_content, and put_file).

void put_object_content(const obs_options *options, const char *key,
    const char *content, uint64_t content_length,
    obs_put_properties *put_properties,
    server_side_encryption_params *encryption_params,
    obs_put_object_handler *handler, void *callback_data);

Scenario 2: configuring a lifecycle rule after uploading an object

You can call the set_object_metadata API to change the expiration time of an uploaded object. During the change, you need to set the metadata_action field to specify the metadata update policy.

void set_object_metadata(const obs_options *options, obs_object_info *object_info,
    obs_put_properties *put_properties,
    server_side_encryption_params *encryption_params,
    obs_response_handler *handler, void *callback_data);

Request Parameters

Scenario 1: configuring a lifecycle rule when uploading an object

The obs_expires field is located in the obs_put_properties structure. You can use init_put_properties to initialize the structure.

Scenario 2: configuring a lifecycle rule after uploading an object

The obs_expires field is located in the obs_put_properties structure. You can use init_put_properties to initialize the structure.

Sample Code - Specifying the Expiration Time When Uploading an Object

#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);
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";
    // Set the upload properties, including the object expiration time.
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    put_properties.obs_expires = 30;  // The object will be automatically deleted 30 days later.
    const char *content = "Hello, OBS!";
    uint64_t content_length = strlen(content);
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_put_object_handler handler = {response_handler, NULL, NULL};
    obs_status ret_status = OBS_STATUS_BUTT;
    put_object_content(&options, "objectname", content, content_length,
                       &put_properties, NULL, &handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("put object with expires successfully.\n");
    } else {
        printf("put object with expires 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); }
}

Sample Code - Setting the Expiration Time After Uploading an Object

This example sets the expiration time to 30 days for an uploaded object.

#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";
    // Set the object information.
    obs_object_info object_info = {0};
    object_info.key = "objectname";
    // Set the properties: expiration time and metadata operation policy.
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    put_properties.obs_expires = 30;  // The object will be automatically deleted 30 days later.
    put_properties.metadata_action = OBS_REPLACE_NEW;  // Add or update specified metadata. Unspecified metadata remains unchanged.
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_status ret_status = OBS_STATUS_BUTT;
    set_object_metadata(&options, &object_info, &put_properties, NULL, &response_handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("set object metadata with expires successfully.\n");
    } else {
        printf("set object metadata with expires 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); }
}

Helpful Links

• The API for setting object properties (including the lifecycle)
• OBS Error Codes