简介
本文档提供关于数据万象文件解压任务的相关 API 概览以及 SDK 示例代码。
提交文件解压任务
功能说明
以提交任务的方式进行文件解压缩,异步返回压缩包内被解压出来的文件。
方法原型
CosResult CosAPI::CreateDataProcessJobs(const CreateDataProcessJobsReq& req,CreateDataProcessJobsResp* resp);
参数说明
参数名称 | 描述 | 类型 | 是否必选 |
req | 创建异步任务操作的请求 | CreateDataProcessJobsReq | 是 |
resp | 创建异步任务操作的响应 | CreateDataProcessJobsResp | 是 |
req 包含如下方法:
void setOperation(JobsOptions operation);
JobsOptions 结构体如下:
struct JobsOptions {std::string tag; // 任务类型,文件解压缩的任务类型为 FileUncompress ,必传Input input; // 输入文件参数,任务类型为文件解压缩时必传JobsOperation operation; // 任务参数,必传std::string callback_format; // 任务回调格式,JSON 或 XML,默认 XML,优先级高于队列的回调格式,非必传std::string callback_type; // 任务回调类型,Url 或 TDMQ,默认 Url,优先级高于队列的回调类型,非必传std::string callback; // 任务回调的地址,优先级高于队列的回调地址,非必传CallBackkMqConfig callback_mq_config; // 任务回TDMQ配置,非必传};struct Input {std::string object; // 文件在 COS 上的文件路径, 必传std::string region; // 地域,必传std::string bucket; // 桶名称,必传};struct JobsOperation {Output output; // 指定解压后的文件保存的存储桶信息,必传std::string user_data; // 自定义透传信息,非必传FileUncompressConfig file_uncompress_config; // 指定文件解压的处理规则,必传FileUncompressResult file_uncompress_result; // 文件解压的结果,任务未完成时不返回,非请求参数,在任务完成时返回};struct FileUncompressConfig {std::string prefix; // 指定解压后输出文件的前缀,不填则默认保存在存储桶根路径,非必传std::string un_compress_key; // 解压密钥,传入时需先经过 base64 编码,非必传std::string prefix_replaced; // 指定解压后的文件路径是否需要替换前缀,有效值:// - 0:不添加额外的前缀,解压缩将保存在Prefix指定的路径下(不会保留压缩包的名称,仅将压缩包内的文件保存至指定的路径)。// - 1:以压缩包本身的名称作为前缀,解压缩将保存在Prefix指定的路径下。// - 2:以压缩包完整路径作为前缀,此时如果不指定Prefix,就是解压到压缩包所在的当前路径(包含压缩包本身名称)。// - 默认值为0。};struct FileUncompressResult {std::string region; // 解压后文件保存的存储桶的地域,非请求参数std::string bucket; // 解压后文件保存的存储桶,非请求参数std::string file_count; // 解压后文件的个数,非请求参数};
resp 包含如下方法:
JobsDetails GetJobsDetail() const;
JobsDetails 结构体如下:
struct JobsDetails {std::string code; // 错误码,只有 State 为 Failed 时有意义std::string message; // 错误描述,只有 State 为 Failed 时有意义std::string job_id; // 新创建任务的 IDstd::string tag; // 新创建任务的 Tag:DocProcessstd::string state; // 任务的状态,为// Submitted、Running、Success、Failed、Pause、Cancel 其中一个std::string create_time; // 任务的创建时间std::string end_time; //std::string queue_id; // 任务所属的队列 IDInput input; // 该任务的输入文件路径JobsOperation operation; // 任务operation,同 Req 中的 JobsOperation};
返回结果说明
成功:API 返回 CosResult 结构,获取对应 Response 结构中的数据。
失败:API 返回 CosResult 结构,失败可以通过 CosResult 获取详细信息。详情请参见 异常处理。
请求示例
qcloud_cos::CosConfig config("./config.json");qcloud_cos::CosAPI cos(config);std::string bucket_name = "examplebucket-1250000000";CreateDataProcessJobsReq req(bucket_name);CreateDataProcessJobsResp resp;JobsOptions opt;opt.input.bucket = bucket_name;opt.input.region = "ap-chongqing";opt.input.object = "test.zip";opt.tag = "FileUncompress";// 文件解压参数// 指定解压后输出文件的前缀,不填则默认保存在存储桶根路径,非必选opt.operation.file_uncompress_config.prefix = "output/";// 指定解压后的文件路径是否需要替换前缀,可选值如下// 0:不添加额外的前缀,解压缩将保存在Prefix指定的路径下(不会保留压缩包的名称,仅将压缩包内的文件保存至指定的路径)// 1:以压缩包本身的名称作为前缀,解压缩将保存在Prefix指定的路径下// 2:以压缩包完整路径作为前缀,此时如果不指定Prefix,就是解压到压缩包所在的当前路径(包含压缩包本身名称)// 非必选参数,默认 0opt.operation.file_uncompress_config.prefix_replaced = "1";// 解压密钥,传入时需先经过 base64 编码,非必选// opt.operation.file_uncompress_config.un_compress_key = "MTIzNDU2Nzg5MA==";opt.operation.output.bucket = bucket_name;opt.operation.output.region = "ap-chongqing";req.setOperation(opt);CosResult result = cos.CreateDataProcessJobs(req, &resp);if (result.IsSucc()) {// 调用成功,调用 resp 的成员函数获取返回内容} else {// 调用失败,调用 result 的成员函数获取错误信息}
查询指定文件处理解压任务
功能说明
查询指定文件解压任务结果。
方法原型
CosResult CosAPI::DescribeDataProcessJob(const DescribeDataProcessJobReq& req,DescribeDataProcessJobResp* resp);
参数说明
参数名称 | 描述 | 类型 | 是否必选 |
req | 查询异步任务操作的请求 | DescribeDataProcessJobReq | 是 |
resp | 查询异步任务操作的响应 | DescribeDataProcessJobResp | 是 |
req 包含如下方法:
void SetJobId(const std::string& job_id); // 查询的任务ID,必传
resp 包含如下方法:
JobsDetails GetJobsDetail() const;
JobsDetails 结构体同提交文件解压缩任务中的 JobsDetails 结构。
返回结果说明
成功:API 返回 CosResult 结构,获取对应 Response 结构中的数据。
失败:API 返回 CosResult 结构,失败可以通过 CosResult 获取详细信息。详情请参见 异常处理。
请求示例
qcloud_cos::CosConfig config("./config.json");qcloud_cos::CosAPI cos(config);std::string bucket_name = "examplebucket-1250000000";DescribeDataProcessJobReq req(bucket_name);DescribeDataProcessJobResp resp;// 任务IDreq.SetJobId("XXXXXXXXXXXXXXXXXXXXXXXXXXXXX");CosResult result = cos.DescribeDataProcessJob(req, &resp);if (result.IsSucc()) {// 调用成功,调用 resp 的成员函数获取返回内容} else {// 调用失败,调用 result 的成员函数获取错误信息}