有奖:语音产品征文挑战赛火热进行中> HOT

简介

本文档提供关于数据万象文件解压任务的相关 API 概览以及 SDK 示例代码。
API
操作描述
创建一个文件解压缩任务
查询文件解压结果

提交文件解压任务

功能说明

以提交任务的方式进行文件解压缩,异步返回压缩包内被解压出来的文件。

方法原型

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; // 新创建任务的 ID
std::string tag; // 新创建任务的 Tag:DocProcess
std::string state; // 任务的状态,为
// Submitted、Running、Success、Failed、Pause、Cancel 其中一个
std::string create_time; // 任务的创建时间
std::string end_time; //
std::string queue_id; // 任务所属的队列 ID
Input 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,就是解压到压缩包所在的当前路径(包含压缩包本身名称)
// 非必选参数,默认 0
opt.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;

// 任务ID
req.SetJobId("XXXXXXXXXXXXXXXXXXXXXXXXXXXXX");

CosResult result = cos.DescribeDataProcessJob(req, &resp);
if (result.IsSucc()) {
// 调用成功,调用 resp 的成员函数获取返回内容
} else {
// 调用失败,调用 result 的成员函数获取错误信息
}