断点续传下载
开发过程中,您有任何问题可以在github上提交issue。
当下载大对象到本地文件时,经常出现因网络不稳定或程序崩溃导致下载失败的情况。失败后再次重新下载不仅浪费资源,而且当网络不稳定时仍然有下载失败的风险。断点续传下载接口能有效地解决此类问题引起的下载失败,其原理是将待下载的对象分成若干个分段分别下载,并实时地将每段下载结果统一记录在checkpoint文件中,仅当所有分段都下载成功时返回下载成功的结果,否则抛出异常提醒用户再次调用接口进行重新下载(重新下载时因为有checkpoint文件记录当前的下载进度,避免重新下载所有分段,从而节省资源提高效率)。
您可以通过download_file进行断点续传下载。该接口可设置的参数描述如下:
字段名 |
类型 |
约束 |
说明 |
---|---|---|---|
option |
请求桶的上下文,配置option |
必选 |
桶参数。 |
key |
char * |
必选 |
对象名。 |
version_id |
char * |
必选 |
对象的版本号。 |
download_file_config |
obs_download_file_configuration * |
必选 |
下载文件的配置说明,请参考下表obs_download_file_configuration成员说明。 |
get_conditions |
obs_get_conditions * |
必选 |
对象筛选条件和读取范围设置,请参考7.2限定条件说明。 |
encryption_params |
server_side_encryption_params * |
可选 |
上传对象加密设置。 |
handler |
obs_download_file_response_handler * |
必选 |
回调函数。 |
callback_data |
void * |
可选 |
回调数据。 |
下载文件结构obs_download_file_configuration描述如下表:
字段名 |
类型 |
约束 |
说明 |
---|---|---|---|
downLoad_file |
char * |
必选 |
下载对象的本地文件路径。当该值为空时,默认为当前程序的运行目录。 |
part_size |
uint64_t |
必选 |
分段大小,单位字节,取值范围是5MB~5GB,默认为5MB。 |
task_num |
int |
必选 |
分段下载时的最大并发数,默认为1。 |
enable_check_point |
int |
必选 |
是否开启断点续传模式,默认为0,表示不开启。 |
check_point_file |
char * |
必选 |
记录下载进度的文件,只在断点续传模式下有效。当该值为空时,默认与下载对象的本地文件路径同目录。 |
以下代码展示了如何使用断点续传下载接口下载对象到本地文件:
void downloadFileResultCallback(obs_status status, char *resultMsg, int partCountReturn, obs_download_file_part_info * downloadInfoList, void *callbackData); //回调函数声明 static void test_download_file(char *filename, char *key) { obs_status ret_status = OBS_STATUS_BUTT; uint64_t uploadSliceSize =5L * 1024 * 1024; // 创建并初始化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"); // 初始化getConditions obs_get_conditions getConditions; memset_s(&getConditions,sizeof(obs_get_conditions),0,sizeof(obs_get_conditions)); init_get_properties(&getConditions); // 断点下载对象信息 obs_download_file_configuration downloadFileConfig; memset_s(&downloadFileConfig,sizeof(obs_download_file_configuration),0, sizeof(obs_download_file_configuration)); downloadFileConfig.check_point_file = NULL; downloadFileConfig.enable_check_point = 1; downloadFileConfig.part_size = uploadSliceSize; downloadFileConfig.task_num = 10; downloadFileConfig.downLoad_file= filename; // 设置响应回调函数 obs_download_file_response_handler Handler = { {&response_properties_callback, &response_complete_callback_for_multi_task}, &downloadFileResultCallback }; initialize_break_point_lock(); download_file(&option, key, 0,&getConditions,0,&downloadFileConfig, &Handler, &ret_status); deinitialize_break_point_lock(); if (OBS_STATUS_OK == ret_status) { printf("test download file successfully. \n"); } else { printf("test download file faied(%s).\n", obs_get_status_name(ret_status)); } } //downloadFileResultCallback 示例,printf语句可以替换为自定义的日志打印语句 void downloadFileResultCallback(obs_status status, char *resultMsg, int partCountReturn, obs_download_file_part_info * downloadInfoList, void *callbackData) { int i=0; obs_download_file_part_info * pstDownloadInfoList = downloadInfoList; printf("status return is %d(%s)\n", status, obs_get_status_name(status)); printf("%s",resultMsg); printf("partCount[%d]\n",partCountReturn); for(i=0;i<partCountReturn;i++) { printf("partNum[%d],startByte[%llu],partSize[%llu],status[%d]\n", pstDownloadInfoList->part_num, pstDownloadInfoList->start_byte, pstDownloadInfoList->part_size, pstDownloadInfoList->status_return); pstDownloadInfoList++; } if (callbackData) { obs_status* retStatus = (obs_status*)callbackData; (*retStatus) = status; } }
- 断点续传下载接口是利用分段上传特性实现的,是对范围下载的封装和加强。
- 断点续传下载接口不仅能在失败重下时节省资源提高效率,还因其对分段进行并发下载的机制能加快下载速度,帮助用户快速完成下载业务;且其对用户透明,用户不用关心checkpoint文件的创建和删除、分段任务的切分、并发下载的实现等内部细节。
- enable_check_point参数默认是0,代表不启用断点续传模式,此时断点续传下载接口退化成对范围下载的简单封装,不会产生checkpoint文件。
- check_point_file参数仅在enable_check_point参数为1时有效。
- 断点续传下载可通过task_num参数设置并发数,实现对单个对象的并行下载。