# 对象生命周期(C SDK)
![](https://support.huaweicloud.com/sdk-c-devg-obs/public_sys-resources/notice_3.0-zh-cn.png)
开发过程中，您有任何问题可以在GitHub上[提交issue](https://github.com/huaweicloud/huaweicloud-sdk-c-obs/issues)，或者在[华为云对象存储服务论坛](https://bbs.huaweicloud.com/forum/forum-620-1.html)中发帖求助。
#### 功能说明
对象生命周期是指为对象设置过期时间（x-obs-expires），对象在指定天数后会被OBS服务端自动删除。OBS C SDK支持两种设置对象生命周期的方式：
- **上传时指定**：在上传对象时通过obs_put_properties结构体的obs_expires字段设置，对象上传后即生效。
- **上传后设置**：通过set_object_metadata接口修改已有对象的过期时间。
 
#### 接口约束
- 您必须是桶拥有者或拥有上传对象或设置对象属性的权限。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject或obs:object:ModifyObjectMetaData权限，如果使用桶策略则需授予PutObject或ModifyObjectMetaData权限。相关授权方式介绍可参见[OBS权限控制概述](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)，配置方式详见[使用IAM自定义策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0121.html)、[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。
- OBS支持的Region与Endpoint的对应关系，详细信息请参见[地区与终端节点](https://developer.huaweicloud.com/endpoint?OBS)。
- obs_expires的单位为天，设置的天数计算出的过期时间不能早于当前时间。例如10天前上传的对象，不能设置小于10的值。
- 对象过期后会被OBS服务端自动删除，此操作不可逆。
 
#### 方法定义
**场景一：上传时指定对象生命周期**
在上传对象时，通过obs_put_properties结构体的obs_expires字段设置对象的过期天数。该字段适用于所有上传接口（put_object、put_object_content、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);
```
**场景二：上传后设置对象生命周期**
对于已上传的对象，可以通过set_object_metadata接口修改其过期时间。修改时需要设置metadata_action字段以指定元数据的更新策略。
```
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);
```
#### 请求参数
**场景一：上传时指定对象生命周期**
obs_expires字段位于obs_put_properties结构体中，可通过init_put_properties初始化该结构体。
表1obs_put_properties中的生命周期相关参数 
| 参数名称        | 参数类型    | 是否必选 | 描述                                                                                                                                                                                                                                                                                                                                                                    |
|:---|:---|:---|:---|
| obs_expires | int64_t | 可选   | **参数解释：** 指定对象过期时间，单位是天。过期之后对象会被OBS服务端自动删除。 **约束限制：** 设置的天数计算出的过期时间不能早于当前时间，如10天前上传的对象，不能设置小于10的值。 **取值范围：** 大于0的整数值。 **默认取值：** -1，表示不设置过期时间，对象不会自动删除。 |
   
**场景二：上传后设置对象生命周期**
obs_expires字段位于obs_put_properties结构体中，可通过init_put_properties初始化该结构体。
表2obs_put_properties中的生命周期和元数据操作相关参数 
| 参数名称            | 参数类型                                                          | 是否必选 | 描述                                                                                                                                                                                                                                                                                                                                       |
|:---|:---|:---|:---|
| obs_expires     | int64_t                                                       | 可选   | **参数解释：** 指定对象过期时间，单位是天。过期之后对象会被OBS服务端自动删除。 **约束限制：** 设置的天数计算出的过期时间不能早于当前时间。 **取值范围：** 大于0的整数值。 **默认取值：** -1，表示不设置过期时间。 |
| metadata_action | [metadata_action_indicator] | 可选   | **参数解释：** 元数据操作指示符。 **约束限制：** 无 **取值范围：** 可详见[metadata_action_indicator]。 **默认取值：** 无             |
   
 表3metadata_action_indicator 
| **常量名**                | **原始值**     | **说明**                                                   |
|:---|:---|:---|
| OBS_NO_METADATA_ACTION | -           | 默认的无效值。                                                  |
| OBS_REPLACE            | REPLACE     | 表示使用当前请求中携带的头域完整替换，未指定的元数据会被删除。                          |
| OBS_REPLACE_NEW        | REPLACE_NEW | 表示对于已经存在值的元数据进行替换，不存在值的元数据进行赋值，未指定的元数据保持不变（自定义元数据作替换处理）。 |
   
#### 代码示例-上传时指定对象过期时间
以下示例展示如何在上传文本时指定对象过期时间为30天：
```
#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);
    // host_name填写桶所在的endpoint, 此处以华北-北京四为例，其他地区请按实际情况填写。
    options.bucket_options.host_name = "obs.cn-north-4.myhuaweicloud.com";
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全
    // 本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和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_put_properties put_properties;
    init_put_properties(&put_properties);
    put_properties.obs_expires = 30;  // 对象30天后自动删除
    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); }
}
```
#### 代码示例-上传后设置对象过期时间
以下示例展示如何为已上传的对象设置过期时间为30天：
```
#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);
    // host_name填写桶所在的endpoint, 此处以华北-北京四为例，其他地区请按实际情况填写。
    options.bucket_options.host_name = "obs.cn-north-4.myhuaweicloud.com";
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全
    // 本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和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_object_info object_info = {0};
    object_info.key = "objectname";
    // 设置属性：过期时间 + 元数据操作策略
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    put_properties.obs_expires = 30;  // 对象30天后自动删除
    put_properties.metadata_action = OBS_REPLACE_NEW;  // 替换新增模式，不影响已有元数据
    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); }
}
```
#### 相关链接
- 关于设置对象属性（包含设置对象生命周期）的API说明，请参见[设置对象属性](https://support.huaweicloud.com/api-obs/obs_04_0091.html)。
- 对象生命周期设置过程中返回的错误码含义、问题原因及处理措施可参考[OBS错误码](https://support.huaweicloud.com/api-obs/obs_04_0115.html#section1)。