对象存储下载对象-SDK 文档-文档中心-腾讯云

简介
本文介绍对象存储 COS 通过 C SDK 实现下载对象功能的示例代码和描述。包括高级接口、简单接口两个部分。
注意事项
若您想要下载对象，需要具有目标对象的读权限：在您进行 授权策略 时，action 需要设置为cos:GetObject ，更多授权请参见 支持CAM的业务接口。
相关示例
功能名称
描述
示例代码
高级接口
高级接口基于 range 多线程下载对象到本地文件，支持断点下载。
﻿GitHub完整示例﻿
简单接口
GET Object 接口可以实现下载对象到本地文件，不支持断点下载功能。
﻿GitHub完整示例﻿
高级接口（推荐）
下载对象
分块下载接口根据用户对象的长度，自动使用 Range 下载数据，实现并发下载，分块大小默认1048576（1MB），可通过 part_size 参数调整。
方法原型
cos_status_t *cos_resumable_download_file(cos_request_options_t *options,
                                          cos_string_t *bucket,
                                          cos_string_t *object,
                                          cos_string_t *filepath,
                                          cos_table_t *headers,
                                          cos_table_t *params,
                                          cos_resumable_clt_params_t *clt_params,
                                          cos_progress_callback progress_callback);
请求示例
// COS 的 bucket 名称, [bucket]-[appid], 如: mybucket-1253666666，可在 https://console.cloud.tencent.com/cos5/bucket 查看
char bucket_name[] = "examplebucket-12500000000";
// 开发者访问 COS 服务时拥有的用户维度唯一资源标识，用以标识资源，可在 https://console.cloud.tencent.com/cam/capi 页面获取
char appid[] = "12500000000";
// 开发者拥有的项目身份ID/密钥，可在 https://console.cloud.tencent.com/cam/capi 页面获取
char secret_id[] = "AKIDXXXXXXXX";
char secret_key[] = "1A2Z3YYYYYYYYYY";
//endpoint 是 COS 访问域名信息（不设置存储桶前缀，访问 COS 时会自动在前面拼接上[bucket]-[appid]）， 详情请参见 https://cloud.tencent.com/document/product/436/6224 文档
char endpoint[] = "cos.ap-guangzhou.myqcloud.com";
// 是否使用自定域名。如果设置为 COS_TRUE ，则访问 COS 时需要将 endpoint 的值修改为自定义域名
int is_cname = COS_FALSE;
﻿
void init_test_config(cos_config_t* config, int is_cname) {
    cos_str_set(&config->endpoint, endpoint);
    cos_str_set(&config->access_key_id, secret_id);
    cos_str_set(&config->access_key_secret, secret_key);
    cos_str_set(&config->appid, appid);
    // cos_str_set(&config->sts_token, token);  // 使用临时密钥时的 token
    config->is_cname = is_cname;  // 是否使用自定义域名
}
﻿
void init_test_request_options(cos_request_options_t* options, int is_cname) {
    options->config = cos_config_create(options->pool);
    init_test_config(options->config, is_cname);
    options->ctl = cos_http_controller_create(options->pool, 0);
}
﻿
void log_status(cos_status_t* s) {
    cos_warn_log("status->code: %d", s->code);
    if (s->error_code)
        cos_warn_log("status->error_code: %s", s->error_code);
    if (s->error_msg)
        cos_warn_log("status->error_msg: %s", s->error_msg);
    if (s->req_id)
        cos_warn_log("status->req_id: %s", s->req_id);
}
﻿
void resumable_get_object_demo() {
    char object_name[] = "big_file.txt";  // 对象名称
    char file_path[] = "big_file.txt";    // 本地文件路径
    int enable_checkpoint = COS_FALSE; // 是否开启断点续传
﻿
    cos_pool_t *p = NULL;
    cos_status_t *s = NULL;
    cos_request_options_t *options = NULL;
    cos_string_t bucket;
    cos_string_t object;
    cos_string_t filepath;
    cos_resumable_clt_params_t *clt_params;
﻿
    cos_pool_create(&p, NULL);
    options = cos_request_options_create(p);
    init_test_request_options(options, is_cname);
    cos_str_set(&bucket, bucket_name);
    cos_str_set(&object, object_name);
    cos_str_set(&filepath, file_path);

    clt_params = cos_create_resumable_clt_params_content(p, 5*1024*1024, 3, enable_checkpoint, NULL);
    s = cos_resumable_download_file(options, &bucket, &object, &filepath, NULL, NULL, clt_params, NULL);
    log_status(s);
    if (cos_status_is_ok(s)) {
        printf("upload succeeded\\n");
    } else {
        printf("upload failed\\n");
    }
﻿
    cos_pool_destroy(p);
}
﻿
int main() {
    if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
        exit(1);
    }
    resumable_get_object_demo();
    // cos_http_io_deinitialize last
    cos_http_io_deinitialize();
    return 0;
}
参数说明
参数名称
参数描述
参数类型
options
COS 请求选项
Struct
bucket
存储桶名称，存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
object
Object 名称
String
filepath
Object 本地文件名称
String
headers
COS 请求附加头域
Struct
params
COS 请求操作参数
Struct
clt_params
下载对象控制参数
Struct
clt_params.part_size
块大小，单位为 bytes，如果用户指定的 part_size 小于4194304（4MB），则按4194304（4MB）处理
Int
clt_params.thread_num
线程池大小，默认为1
Int
clt_params.enable_checkpoint
是否开启断点续传
Boolean
clt_params.checkpoint_path
当开启断点续传时，表示保存上传进度的文件路径，默认路径为<filepath>.cp，其中 filepath 为 Object 本地文件名称
String
progress_callback
下载进度回调函数
func_ptr
结果说明
返回结果
描述
类型
code
错误码
Int
error_code
错误码内容
String
error_msg
错误码描述
String
req_id
请求消息 ID
String
简单接口
下载对象
方法原型
cos_status_t *cos_get_object_to_file(const cos_request_options_t *options,
                                     const cos_string_t *bucket, 
                                     const cos_string_t *object,
                                     cos_table_t *headers, 
                                     cos_table_t *params,
                                     cos_string_t *filename, 
                                     cos_table_t **resp_headers);
请求示例
// COS 的 bucket 名称, [bucket]-[appid], 如: mybucket-1253666666，可在 https://console.cloud.tencent.com/cos5/bucket 查看
char bucket_name[] = "examplebucket-12500000000";
// 开发者访问 COS 服务时拥有的用户维度唯一资源标识，用以标识资源，可在 https://console.cloud.tencent.com/cam/capi 页面获取
char appid[] = "12500000000";
// 开发者拥有的项目身份ID/密钥，可在 https://console.cloud.tencent.com/cam/capi 页面获取
char secret_id[] = "AKIDXXXXXXXX";
char secret_key[] = "1A2Z3YYYYYYYYYY";
//endpoint 是 COS 访问域名信息（不设置存储桶前缀，访问 COS 时会自动在前面拼接上[bucket]-[appid]）， 详情请参见 https://cloud.tencent.com/document/product/436/6224 文档
char endpoint[] = "cos.ap-guangzhou.myqcloud.com";
// 是否使用自定域名。如果设置为 COS_TRUE ，则访问 COS 时需要将 endpoint 的值修改为自定义域名
int is_cname = COS_FALSE;


void init_test_config(cos_config_t* config, int is_cname) {
    cos_str_set(&config->endpoint, endpoint);
    cos_str_set(&config->access_key_id, secret_id);
    cos_str_set(&config->access_key_secret, secret_key);
    cos_str_set(&config->appid, appid);
    // cos_str_set(&config->sts_token, token);  // 使用临时密钥时的 token
    config->is_cname = is_cname;  // 是否使用自定义域名
}


void init_test_request_options(cos_request_options_t* options, int is_cname) {
    options->config = cos_config_create(options->pool);
    init_test_config(options->config, is_cname);
    options->ctl = cos_http_controller_create(options->pool, 0);
}


void log_status(cos_status_t* s) {
    cos_warn_log("status->code: %d", s->code);
    if (s->error_code)
        cos_warn_log("status->error_code: %s", s->error_code);
    if (s->error_msg)
        cos_warn_log("status->error_msg: %s", s->error_msg);
    if (s->req_id)
        cos_warn_log("status->req_id: %s", s->req_id);
}
﻿
void get_object_to_file_demo()
{
    char object_name[] = "test.txt";  // 对象名称
    char file_path[] = "test.txt";    // 本地文件路径

    cos_pool_t *p = NULL;
    cos_status_t *s = NULL;
    cos_request_options_t *options = NULL;
    cos_string_t bucket;
    cos_string_t object;
    cos_table_t *resp_headers;
    cos_string_t file;
    cos_table_t *headers = NULL;
    cos_table_t *params = NULL;

    cos_pool_create(&p, NULL);
    options = cos_request_options_create(p);
    init_test_request_options(options, is_cname);
    cos_str_set(&bucket, bucket_name);
    cos_str_set(&file, file_path);
    cos_str_set(&object, object_name);

    //限速值设置范围为819200 - 838860800，即100KB/s - 100MB/s，如果超出该范围将返回400错误
    // headers = cos_table_make(p, 1);
    // cos_table_add_int(headers, "x-cos-traffic-limit", 819200);
    s = cos_get_object_to_file(options, &bucket, &object, headers, params, &file, &resp_headers);
    log_status(s);
﻿
    {
        int i = 0;
        apr_array_header_t * pp = (apr_array_header_t *) apr_table_elts(resp_headers);
        for ( ; i < pp->nelts; i++)
        {
            apr_table_entry_t *ele = (apr_table_entry_t *)pp->elts+i;
            printf("%s: %s\\n",ele->key,ele->val);
        }
    }
﻿
    cos_pool_destroy(p);
}
﻿
int main() {
    if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
        exit(1);
    }
    get_object_to_file_demo();
    // cos_http_io_deinitialize last
    cos_http_io_deinitialize();
    return 0;
}
参数说明
参数名称
参数描述
参数类型
options
COS 请求选项
Struct
bucket
存储桶名称，存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
object
Object 名称
String
headers
COS 请求附加头域
Struct
params
COS 请求操作参数
Struct
filename
Object 本地保存文件名称
String
resp_headers
返回 HTTP 响应消息的头域
Struct
返回结果说明
返回结果
描述
类型
code
错误码
Int
error_code
错误码内容
String
error_msg
错误码描述
String
req_id
请求消息 ID
String
API 操作
关于下载对象接口涉及的 API 接口说明，请参见 GET Object 查看。

功能名称	描述	示例代码
高级接口	高级接口基于 range 多线程下载对象到本地文件，支持断点下载。	GitHub完整示例
简单接口	GET Object 接口可以实现下载对象到本地文件，不支持断点下载功能。	GitHub完整示例

参数名称	参数描述	参数类型
options	COS 请求选项	Struct
bucket	存储桶名称，存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式	String
object	Object 名称	String
filepath	Object 本地文件名称	String
headers	COS 请求附加头域	Struct
params	COS 请求操作参数	Struct
clt_params	下载对象控制参数	Struct
clt_params.part_size	块大小，单位为 bytes，如果用户指定的 part_size 小于4194304（4MB），则按4194304（4MB）处理	Int
clt_params.thread_num	线程池大小，默认为1	Int
clt_params.enable_checkpoint	是否开启断点续传	Boolean
clt_params.checkpoint_path	当开启断点续传时，表示保存上传进度的文件路径，默认路径为`<filepath>.cp`，其中 filepath 为 Object 本地文件名称	String
progress_callback	下载进度回调函数	func_ptr

返回结果	描述	类型
code	错误码	Int
error_code	错误码内容	String
error_msg	错误码描述	String
req_id	请求消息 ID	String

下载对象

本页目录：

简介

注意事项

相关示例

高级接口（推荐）

下载对象

方法原型

请求示例

参数说明

结果说明

简单接口

下载对象

方法原型

请求示例

参数说明

返回结果说明

API 操作