Ci cpp sdk file process

product/大数据与AI/万象优图2.0/SDK 文档/C++ SDK/文件处理/文件压缩.md

@@ -0,0 +1,219 @@
+## 简介
+
+本文档提供关于数据万象文件处理文件解压缩任务的相关 API 概览以及 SDK 示例代码。
+
+> **注意**
+>  该功能需要 COS CPP SDK v5.5.10 及以上版本。旧版本SDK该接口可能未覆盖或缺少更新参数，使用时建议升级到 [最新版本](https://cloud.tencent.com/document/product/460/72872)。
+
+
+| API | 操作描述 |
+| ------ | ------ |
+| [提交文件解压缩任务](https://cloud.tencent.com/document/product/460/83087) | 创建一个文件解压缩任务 |
+
+## 提交文件解压缩任务
+
+### 功能说明
+
+以提交任务的方式进行文件解压缩，异步返回压缩包内被解压出来的文件。
+
+### 方法原型
+``` c++
+CosResult CosAPI::CreateDataProcessJobs(const CreateDataProcessJobsReq& req,
+                               CreateDataProcessJobsResp* resp);
+```
+
+### 参数说明
+
+| 参数名称 | 描述 | 类型 | 必传 |
+|  :---: | :---: |  :---: | :---: |
+| req | 创建异步任务操作的请求 | CreateDataProcessJobsReq  | 是 |
+| resp | 创建异步任务操作的响应 | CreateDataProcessJobsResp  | 是 |
+
+
+req 包含如下方法：
+
+```cpp
+void setOperation(JobsOptions operation);
+```
+
+
+JobsOptions 结构体如下：
+
+```cpp
+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 包含如下方法：
+
+```cpp
+JobsDetails GetJobsDetail() const；
+```
+
+JobsDetails 结构体如下：
+
+```cpp
+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 获取详细信息。详情请参见 [异常处理](https://cloud.tencent.com/document/product/436/35164)。
+
+
+### 请求示例
+```cpp
+  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 的成员函数获取错误信息
+  } 
+```
+
+
+## 查询制定文件处理解压缩任务
+
+### 功能说明
+
+查询指定文件解压任务结果。
+
+| API | 操作描述 |
+| ------ | ------ |
+| [查询文件解压结果](https://cloud.tencent.com/document/product/460/83088) | 查询文件解压结果 |
+
+### 方法原型
+``` c++
+CosResult CosAPI::DescribeDataProcessJob(const DescribeDataProcessJobReq& req,
+                                 DescribeDataProcessJobResp* resp);
+```
+
+### 参数说明
+
+| 参数名称 | 描述 | 类型 | 必传 |
+|  :---: | :---: |  :---: | :---: |
+| req | 查询异步任务操作的请求 | DescribeDataProcessJobReq  | 是 |
+| resp | 查询异步任务操作的响应 | DescribeDataProcessJobResp  | 是 |
+
+
+req 包含如下方法：
+
+```cpp
+void SetJobId(const std::string& job_id);   // 查询的任务ID，必传
+```
+
+resp 包含如下方法：
+
+```cpp
+JobsDetails GetJobsDetail() const；
+```
+
+JobsDetails 结构体同 提交文件解压缩任务 中的 JobsDetails 结构。
+
+
+
+### 返回结果说明
+- 成功：API 返回 CosResult 结构，获取对应 Response 结构中的数据。
+
+- 失败：API 返回 CosResult 结构，失败可以通过 CosResult 获取详细信息。详情请参见 [异常处理](https://cloud.tencent.com/document/product/436/35164)。
+
+
+### 请求示例
+```cpp
+  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 的成员函数获取错误信息
+  } 
+```