Object Storage Service:Lifecycle (C SDK)

Prerequisites

Before you begin, ensure that you have:

• Reviewed Lifecycle rules based on the last modified time to understand how rules are evaluated

• The required RAM permissions for the operations you plan to perform:

  Operation	Required permission
  Set lifecycle rules	oss:PutBucketLifecycle
  View lifecycle rules	oss:GetBucketLifecycle
  Delete all lifecycle rules	oss:DeleteBucketLifecycle

  For instructions on granting permissions, see Attach a custom policy to a RAM user.

Usage notes

• Examples in this topic use the public endpoint for the China (Hangzhou) region. If your application runs within Alibaba Cloud in the same region as your bucket, use an internal endpoint instead. See Regions and endpoints.

• All examples initialize the OSS client using an OSS endpoint. To use a custom domain name or Security Token Service (STS) credentials instead, see Initialization.

• Expiration dates must be in UTC format — for example, 2023-10-11T00:00:00.000Z.

Initialize the client

The examples below share the same initialization pattern. Call aos_http_io_initialize once at program startup, create a memory pool, and build oss_request_options_t using init_options.

#include "oss_api.h"
#include "aos_http_io.h"

/* Replace with your bucket's endpoint.
   Example for China (Hangzhou): https://oss-cn-hangzhou.aliyuncs.com */
const char *endpoint = "<your-endpoint>";

/* Replace with your bucket name. */
const char *bucket_name = "examplebucket";

/* Replace with the region ID where your bucket is located.
   Example for China (Hangzhou): cn-hangzhou */
const char *region = "<your-region>";

void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);

    aos_str_set(&options->config->endpoint, endpoint);

    /* Read AccessKey credentials from environment variables.
       Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running. */
    aos_str_set(&options->config->access_key_id,
                getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret,
                getenv("OSS_ACCESS_KEY_SECRET"));

    /* region and signature_version are required. */
    aos_str_set(&options->config->region, region);
    options->config->signature_version = 4;

    /* Set to 0 to use the standard OSS endpoint (no CNAME). */
    options->config->is_cname = 0;

    options->ctl = aos_http_controller_create(options->pool, 0);
}

Set lifecycle rules

oss_put_bucket_lifecycle replaces the bucket's entire lifecycle configuration. To add or modify individual rules without overwriting others, first call oss_get_bucket_lifecycle to retrieve the current rules, update the list, and then call oss_put_bucket_lifecycle with the updated list.

The following example sets two rules on examplebucket:

• rule-1 — expires objects under the dir1/ prefix after 3 days

• rule-2 — expires objects under the dir2/ prefix on a fixed date

int main(int argc, char *argv[])
{
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        exit(1);
    }

    aos_pool_t *pool;
    aos_pool_create(&pool, NULL);

    oss_request_options_t *oss_client_options;
    oss_client_options = oss_request_options_create(pool);
    init_options(oss_client_options);

    aos_string_t bucket;
    aos_table_t *resp_headers = NULL;
    aos_status_t *resp_status = NULL;
    aos_list_t lifecycle_rule_list;

    aos_str_set(&bucket, bucket_name);
    aos_list_init(&lifecycle_rule_list);

    /* Rule 1: expire objects under dir1/ after 3 days. */
    oss_lifecycle_rule_content_t *rule_content_days =
        oss_create_lifecycle_rule_content(pool);
    aos_str_set(&rule_content_days->id, "rule-1");
    aos_str_set(&rule_content_days->prefix, "dir1");
    aos_str_set(&rule_content_days->status, "Enabled");
    rule_content_days->days = 3;
    aos_list_add_tail(&rule_content_days->node, &lifecycle_rule_list);

    /* Rule 2: expire objects under dir2/ on a fixed date (UTC). */
    oss_lifecycle_rule_content_t *rule_content_date =
        oss_create_lifecycle_rule_content(pool);
    aos_str_set(&rule_content_date->id, "rule-2");
    aos_str_set(&rule_content_date->prefix, "dir2");
    aos_str_set(&rule_content_date->status, "Enabled");
    aos_str_set(&rule_content_date->date, "2023-10-11T00:00:00.000Z");
    aos_list_add_tail(&rule_content_date->node, &lifecycle_rule_list);

    /* Apply all rules. This replaces any existing lifecycle configuration. */
    resp_status = oss_put_bucket_lifecycle(oss_client_options, &bucket,
                                           &lifecycle_rule_list,
                                           &resp_headers);
    if (aos_status_is_ok(resp_status)) {
        printf("put bucket lifecycle succeeded\n");
    } else {
        printf("put bucket lifecycle failed, code:%d, error_code:%s, "
               "error_msg:%s, request_id:%s\n",
               resp_status->code, resp_status->error_code,
               resp_status->error_msg, resp_status->req_id);
    }

    aos_pool_destroy(pool);
    aos_http_io_deinitialize();
    return 0;
}

To modify individual rules after setting them, see How do I modify one or more lifecycle rule configurations?.

View lifecycle rules

oss_get_bucket_lifecycle returns all lifecycle rules configured for the bucket. The following example retrieves and prints the rules for examplebucket.

int main(int argc, char *argv[])
{
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        exit(1);
    }

    aos_pool_t *pool;
    aos_pool_create(&pool, NULL);

    oss_request_options_t *oss_client_options;
    oss_client_options = oss_request_options_create(pool);
    init_options(oss_client_options);

    aos_string_t bucket;
    aos_table_t *resp_headers = NULL;
    aos_status_t *resp_status = NULL;
    aos_list_t lifecycle_rule_list;
    oss_lifecycle_rule_content_t *rule_content;

    aos_str_set(&bucket, bucket_name);
    aos_list_init(&lifecycle_rule_list);

    resp_status = oss_get_bucket_lifecycle(oss_client_options, &bucket,
                                           &lifecycle_rule_list,
                                           &resp_headers);
    if (aos_status_is_ok(resp_status)) {
        printf("get bucket lifecycle succeeded\n");

        /* Iterate over each rule and print its fields. */
        aos_list_for_each_entry(oss_lifecycle_rule_content_t,
                                rule_content, &lifecycle_rule_list, node) {
            char *rule_id = apr_psprintf(pool, "%.*s",
                rule_content->id.len, rule_content->id.data);
            char *prefix   = apr_psprintf(pool, "%.*s",
                rule_content->prefix.len, rule_content->prefix.data);
            char *status   = apr_psprintf(pool, "%.*s",
                rule_content->status.len, rule_content->status.data);
            char *date     = apr_psprintf(pool, "%.*s",
                rule_content->date.len, rule_content->date.data);
            int   days     = rule_content->days;

            printf("rule_id: %s\n", rule_id);
            printf("prefix:  %s\n", prefix);
            printf("status:  %s\n", status);
            printf("date:    %s\n", date);
            printf("days:    %d\n", days);
        }
    } else {
        printf("get bucket lifecycle failed, code:%d, error_code:%s, "
               "error_msg:%s, request_id:%s\n",
               resp_status->code, resp_status->error_code,
               resp_status->error_msg, resp_status->req_id);
    }

    aos_pool_destroy(pool);
    aos_http_io_deinitialize();
    return 0;
}

Delete all lifecycle rules

oss_delete_bucket_lifecycle removes every lifecycle rule from the bucket.

int main(int argc, char *argv[])
{
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        exit(1);
    }

    aos_pool_t *pool;
    aos_pool_create(&pool, NULL);

    oss_request_options_t *oss_client_options;
    oss_client_options = oss_request_options_create(pool);
    init_options(oss_client_options);

    aos_string_t bucket;
    aos_table_t *resp_headers = NULL;
    aos_status_t *resp_status = NULL;

    aos_str_set(&bucket, bucket_name);

    resp_status = oss_delete_bucket_lifecycle(oss_client_options, &bucket,
                                              &resp_headers);
    if (aos_status_is_ok(resp_status)) {
        printf("delete bucket lifecycle succeeded\n");
    } else {
        printf("delete bucket lifecycle failed, code:%d, error_code:%s, "
               "error_msg:%s, request_id:%s\n",
               resp_status->code, resp_status->error_code,
               resp_status->error_msg, resp_status->req_id);
    }

    aos_pool_destroy(pool);
    aos_http_io_deinitialize();
    return 0;
}

To delete individual rules rather than clearing all of them, see How do I delete one or more lifecycle rules?.

API reference