更新时间:2023-12-07 GMT+08:00

分段上传

开发过程中,您有任何问题可以在github上提交issue

对于较大文件上传,可以切分成段上传。用户可以在如下的应用场景内(但不仅限于此),使用分段上传的模式:

  • 上传超过100MB大小的文件。
  • 网络条件较差,和OBS服务端之间的链接经常断开。
  • 上传前无法确定将要上传文件的大小。

分段上传分为如下3个步骤:

  1. 初始化分段上传任务(initiate_multi_part_upload)。
  2. 逐个或并行上传段(upload_part)。
  3. 合并段(complete_multi_part_upload)或取消分段上传任务(abort_multi_part_upload)。

初始化分段上传任务

使用分段上传方式传输数据前,必须先通知OBS初始化一个分段上传任务。该操作会返回一个OBS服务端创建的全局唯一标识(upload_id),用于标识本次分段上传任务。您可以根据这个唯一标识来发起相关的操作,如取消分段上传任务、列举分段上传任务、列举已上传的段等。

请注意,多段上传的对象的相关属性(如acl、过期时间等等)是在初始化分段上传任务时设置,不能在上传段或合并段时设置,请注意设置相关属性的时机

您可以通过initiate_multi_part_upload初始化一个分段上传任务,参数描述如下表所示:

字段名

类型

约束

说明

option

请求桶的上下文,配置option

必选

桶参数。

key

char *

必选

对象名。

upload_id_return_size

int

必选

多段上传id缓存大小。

upload_id_return

char *

必选

多段上传id缓存。

put_properties

obs_put_properties*

可选

上传对象属性。

encryption_params

server_side_encryption_params *

可选

服务端加密设置。

handler

obs_response_handler *

必选

回调函数。

callback_data

void *

可选

回调数据。

static void test_initiate_multi_part_upload()
{
    obs_status ret_status = OBS_STATUS_BUTT;
    // 创建并初始化option
    obs_options option;
    init_obs_options(&option);
    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险,建议在配置文件或者环境变量中密文存放,使用时解密,确保安全;本示例以ak和sk保存在环境变量中为例,运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY。
    // 您可以登录访问管理控制台获取访问密钥AK/SK,获取方式请参见https://support.huaweicloud.com/intl/zh-cn/usermanual-ca/ca_01_0003.html
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // 定义多段上传id缓存及大小
    char upload_id[OBS_COMMON_LEN_256] = {0};
    int upload_id_size = OBS_COMMON_LEN_256;
    // 设置响应回调函数
    obs_response_handler handler =
    { 
        &response_properties_callback,
        &response_complete_callback 
    };
    // 初始化分段上传任务,这里的upload_id就是接口定义中的upload_id_return  
    initiate_multi_part_upload(&option, "<object key>", upload_id_size, upload_id, NULL, NULL, &handler, &ret_status);
    if (OBS_STATUS_OK == ret_status)
    {
        printf("test init upload part successfully. uploadId= %s\n", upload_id);
    }
    else
    {
        printf("test init upload part faied(%s).\n", obs_get_status_name(ret_status));
    }
}
  • 在结构体obs_put_properties中,您可以设置对象MIME类型、对象自定义元数据。
  • initiate_multi_part_upload返回分段上传任务的全局唯一标识(upload_id),在后面的操作中将用到它。

上传段

初始化一个分段上传任务之后,可以根据指定的对象名和uploadId来分段上传数据。每一个上传的段都有一个标识它的号码——分段号(Part Number,范围是1~10000)。对于同一个uploadId,该分段号不但唯一标识这一段数据,也标识了这段数据在整个对象内的相对位置。如果您用同一个分段号上传了新的数据,那么OBS上已有的这个段号的数据将被覆盖。除了最后一段以外,其他段的大小范围是100KB~5GB;最后段大小范围是0~5GB。每个段不需要按顺序上传,甚至可以在不同进程、不同机器上上传,OBS会按照分段号排序组成最终对象。

您可以通过upload_part上传段,参数描述如下表:

字段名

类型

约束

说明

option

请求桶的上下文,配置option

必选

桶参数。

key

char *

必选

对象名。

upload_part_info

obs_upload_part_info *

必选

上传段的信息。

upload_part_info->part_number

unsigned int

必选

上传段的段号。取值为从1到10000的整数。

upload_part_info->upload_id

char *

必选

多段上传任务Id。

content_length

uint64_t

必选

上传内容长度。

put_properties

obs_put_properties*

可选

上传对象属性。

encryption_params

server_side_encryption_params *

可选

服务端加密设置。

handler

obs_upload_handler *

必选

回调函数。

callback_data

void *

可选

回调数据。

示例代码如下:

static void test_upload_part()
{
    // 创建并初始化option
    obs_options option;
    init_obs_options(&option);
    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险,建议在配置文件或者环境变量中密文存放,使用时解密,确保安全;本示例以ak和sk保存在环境变量中为例,运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY。
    // 您可以登录访问管理控制台获取访问密钥AK/SK,获取方式请参见https://support.huaweicloud.com/intl/zh-cn/usermanual-ca/ca_01_0003.html
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // 定义分片大小5M
    uint64_t uploadSliceSize =5L * 1024 * 1024; 
    // 定义并初始化上传段大小                  
    uint64_t uploadSize = uploadSliceSize; 
    // 定义并初始化上传文件长度变量                        
    uint64_t filesize = 0;                                          
    //初始化put_properties
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    //回调函数
    obs_upload_handler Handler =
    { 
        {&response_properties_callback, &response_complete_callback},
        &test_upload_file_data_callback
    };   
    //回调数据初始化
    test_upload_file_callback_data data;
    memset(&data, 0, sizeof(test_upload_file_callback_data));
    filesize = get_file_info(filename,&data);
    data.noStatus = 1;
    data.part_size = uploadSize;
    data.part_num = (filesize % uploadSize == 0) ? (filesize / uploadSize) : (filesize / uploadSize +1);
 
    //上传第一段
    uploadPartInfo.part_number=1;
    uploadPartInfo.upload_id = "<upload id>";
    data.start_byte  = 0;
    upload_part(&option,key,&uploadPartInfo,uploadSize,
                                      &put_properties,0,&Handler,&data);
    if (OBS_STATUS_OK == data.ret_status) {
        printf("test upload part 1 successfully. \n");
    }
    else
    {
        printf("test upload part 1 faied(%s).\n", obs_get_status_name(data.ret_status));
    }
    //上传第二段
    uploadPartInfo.part_number=2;
    uploadPartInfo.upload_id = "<upload id>";
    filesize = get_file_info(filename,&data);
    uploadSize =filesize - uploadSize;
    data.part_size = uploadSize;
    data.start_byte = uploadSliceSize;
    fseek(data.infile, data.start_byte, SEEK_SET);
    upload_part(&option,key,&uploadPartInfo,uploadSize, &put_properties,0,&Handler,&data);
    if (OBS_STATUS_OK == data.ret_status) {
        printf("test upload part 2 successfully. \n");
    }
    else
    {
        printf("test upload part 2 faied(%s).\n", obs_get_status_name(data.ret_status));
    }

}
  • 上传段接口要求除最后一段以外,其他的段大小都要大于100KB。但是上传段接口并不会立即校验上传段的大小(因为不知道是否为最后一块);只有调用合并段接口时才会校验。
  • OBS会将服务端收到段数据的ETag值(段数据的MD5值)返回给用户。
  • 为了保证数据在网络传输过程中不出现错误,可以通过设置MD5值,并放到Content-MD5请求头中;OBS服务端会计算上传数据的MD5值与SDK计算的MD5值比较,保证数据完整性。
  • 可以通过put_properties.md5直接设置上传数据的MD5值,提供给OBS服务端用于校验数据完整性。
  • 分段号的范围是1~10000。如果超出这个范围,OBS将返回400 Bad Request错误。
  • OBS 3.0的桶支持最小段的大小为100KB,OBS 2.0的桶支持最小段的大小为5MB。请在OBS 3.0的桶上执行分段上传操作。

合并段

所有分段上传完成后,需要调用合并段接口来在OBS服务端生成最终对象。在执行该操作时,需要提供所有有效的分段列表(包括分段号和分段ETag值);OBS收到提交的分段列表后,会逐一验证每个段的有效性。当所有段验证通过后,OBS将把这些分段组合成最终的对象。

您可以通过complete_multi_part_upload合并段,参数描述如下表:

字段名

类型

约束

说明

option

请求桶的上下文,配置option

必选

桶参数。

key

char *

必选

对象名。

upload_id

char *

必选

指明多段上传任务。

part_number

unsigned int

必选

段个数,complete_upload_Info数组长度

complete_upload_Info

obs_complete_upload_Info *

必选

段信息数组。

complete_upload_Info->part_number

unsigned int

必选

段号。

complete_upload_Info->etag

char *

必选

对应段的ETag值。

put_properties

obs_put_properties*

可选

上传对象属性。

handler

obs_complete_multi_part_upload_handler *

必选

回调函数。

callback_data

void *

可选

回调数据。

示例代码如下:

static void test_complete_upload(char *filename, char *key)
{
    obs_status ret_status = OBS_STATUS_BUTT;

    // 创建并初始化option
    obs_options option;
    init_obs_options(&option);
    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

    //从环境变量读取ak/sk
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");

    // 初始化结构体put_properties
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    // 设置分段信息
    char *uploadId = "<upload id>";
    obs_complete_upload_Info info[2];
    info[0].part_number="1";
    info[0].etag="65fe0e161b35c8deead213871033f7fa";
    info[1].part_number="2";
    info[1].etag="0433d5ffc28450be3b6cf25ab8955267";
    // 设置响应回调函数
    obs_complete_multi_part_upload_handler Handler =
    { 
        {&response_properties_callback,
         &response_complete_callback},
        &CompleteMultipartUploadCallback
    };
    // 合并段   
    complete_multi_part_upload(&option,key,uploadId,number,info,&putProperties,
                &Handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("test complete upload successfully. \n");
    }
    else
    {
        printf("test complete upload faied(%s).\n", obs_get_status_name(ret_status));
    }
}
  • 上面代码中的info结构体数组是进行上传段后保存的分段号和分段ETag值的列表。
  • 分段可以是不连续的。

并发分段上传

分段上传的主要目的是解决大文件上传或网络条件较差的情况。下面的示例代码展示了如何使用分段上传并发上传大文件:

static void test_concurrent_upload_part(char *filename, char *key, uint64_t uploadSliceSize)
{
    obs_status ret_status = OBS_STATUS_BUTT;
    // 创建并初始化option
    obs_options option;
    init_obs_options(&option);
    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

    //从环境变量读取ak/sk
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    char *concurrent_upload_id;
    uint64_t uploadSize = uploadSliceSize;                             
    uint64_t filesize =0;                                          
    //初始化结构体put_properties
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    //大文件信息:文件指针,文件大小,按照分段大小的分段数
    test_upload_file_callback_data data;
    memset(&data, 0, sizeof(test_upload_file_callback_data));
    filesize = get_file_info(filename,&data);
    data.noStatus = 1;
    data.part_size = uploadSize;
    data.part_num = (filesize % uploadSize == 0) ? (filesize / uploadSize) : (filesize / uploadSize +1);
    // 初始化上传段回调函数    
    obs_response_handler Handler =
    { 
         &response_properties_callback, &response_complete_callback 
    };
    // 合并段回调函数
    obs_complete_multi_part_upload_handler complete_multi_handler =
    { 
        {&response_properties_callback,
         &response_complete_callback},
        &CompleteMultipartUploadCallback
    };
    //初始化上传段任务返回uploadId: uploadIdReturn
    char uploadIdReturn[256] = {0};
    int upload_id_return_size = 255;
    initiate_multi_part_upload(&option,key,upload_id_return_size,uploadIdReturn, &putProperties,
            0,&Handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("test init upload part return uploadIdReturn(%s). \n", uploadIdReturn);
        strcpy(concurrent_upload_id,uploadIdReturn);
    }
    else
    {
        printf("test init upload part faied(%s).\n", obs_get_status_name(ret_status));
    }
    // 并发上传
    test_concurrent_upload_file_callback_data *concurrent_upload_file;
    concurrent_upload_file =(test_concurrent_upload_file_callback_data *)malloc(
                    sizeof(test_concurrent_upload_file_callback_data)*(data.part_num+1));
    if(concurrent_upload_file == NULL)
    {
         printf("malloc test_concurrent_upload_file_callback_data failed!!!");
         return ;
    }
    test_concurrent_upload_file_callback_data *concurrent_upload_file_complete =   
                              concurrent_upload_file;
    start_upload_threads(data, concurrent_upload_id,filesize, key, option, concurrent_upload_file_complete);
     // 合并段
    obs_complete_upload_Info *upload_Info = (obs_complete_upload_Info *)malloc(
                sizeof(obs_complete_upload_Info)*data.part_num);
    for(i=0; i<data.part_num; i++)
    {
        upload_Info[i].part_number = concurrent_upload_file_complete[i].part_num;
        upload_Info[i].etag = concurrent_upload_file_complete[i].etag;
    }
    complete_multi_part_upload(&option, key, uploadIdReturn, data.part_num,upload_Info,&putProperties,&complete_multi_handler,&ret_status);
    if (ret_status == OBS_STATUS_OK) {
        printf("test complete upload successfully. \n");
    }
    else
    {
        printf("test complete upload faied(%s).\n", obs_get_status_name(ret_status));
    }
    if(concurrent_upload_file)
    {
        free(concurrent_upload_file);
        concurrent_upload_file = NULL;
    }
    if(upload_Info)
    {
        free(upload_Info);
        upload_Info = NULL;
    }
}