有奖捉虫:云通信与企业服务文档专题,速来> HOT

简介

本文档提供关于文档预览的相关 API 概览以及 SDK 示例代码。
API
操作描述
查询已经开通文档预览功能的存储桶
文档预览功能支持对多种文件类型生成图片格式预览,并可对转换后的图片同步进行基础处理操作,可以解决文档内容的页面展示问题
异步处理接口
API
操作名
操作描述
提交文档预览任务
用于提交一个文档预览任务
查询文档预览任务
查询指定的文档预览任务
拉取文档预览任务
拉取符合条件的文档预览任务
查询文档预览队列
用于查询文档预览队列
更新文档预览队列
用于更新文档预览队列

查询文档预览开通状态

功能说明

查询已经开通文档预览功能的存储桶。

方法原型

CosResult DescribeDocProcessBuckets(const DescribeDocProcessBucketsReq& request, DescribeDocProcessBucketsResp *response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

DescribeDocProcessBucketsReq req;
DescribeDocProcessBucketsResp resp;

req.SetRegions("ap-guangzhou");
// 设置存储桶名称,以“,”分隔,支持多个存储桶,精确搜索
// req.SetBucketNames("xxx");
// 设置存储桶名称前缀,前缀搜索
// req.SetBucketName("xxx");
// 设置第几页
// req.SetPageNumber();
// 设置每页个数
// req.SetPageSize();

CosResult result = cos.DescribeDocProcessBuckets(req, &resp);
if (result.IsSucc()) {
// 调用成功,调用 resp 的成员函数获取返回内容
std::cout << "Result: " << resp.GetResult().to_string() << std::endl;
} else {
// 调用失败,调用 result 的成员函数获取错误信息
}

参数说明

参数
参数描述
类型
是否必填
req
DescribeDocProcessBuckets操作的请求
DescribeDocProcessBucketsReq
resp
DescribeDocProcessBuckets操作的响应
DescribeDocProcessBucketsResp
req有如下方法:
void SetRegions(const std::string& regions);
void SetBucketNames(const std::string& bucket_names);
void SetBucketName(const std::string& bucket_name);
void SetPageNumber(const std::string& page_number);
void SetPageSize(const std::string& page_size);
resp涉及到如下结构:
struct DocBucketList {
std::string bucket_id; //存储桶 ID
std::string name; // 存储桶名称,同 BucketId
std::string region; //所在的地域
std::string create_time; // 创建时间
std::string alias_bucket_id; // 存储桶别名
};

struct DocBucketResponse {
std::string request_id; // 请求的唯一 ID
int total_count; // 文档预览 Bucket 总数
int page_number; // 当前页数,同请求中的 pageNumber
int page_size; // 每页个数,同请求中的 pageSize
std::vector<DocBucketList> doc_bucket_list; // 文档预览 Bucket 列表
};

同步请求接口

功能说明

支持对多种文件类型生成图片格式预览。

方法原型

CosResult DocPreview(const DocPreviewReq& request, DocPreviewResp *response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

DocPreviewReq req(bucket_name, object_name, local_file);
req.SetSrcType("docx");
DocPreviewResp resp;

CosResult result = cos.DocPreview(req, &resp);
if (result.IsSucc()) {
// 调用成功,调用 resp 的成员函数获取返回内容
std::cout << "Result: " << resp.GetResult().to_string() << std::endl;
} else {
// 调用失败,调用 result 的成员函数获取错误信息
}

参数说明

参数
参数描述
类型
是否必填
req
DocPreview操作的请求
DocPreviewReq
resp
DocPreview操作的响应
DocPreviewResp
req 有如下方法:
// 源数据的后缀类型,当前文档转换根据 COS 对象的后缀名来确定源数据类型。当 COS
// 对象没有后缀名时,可以设置该值
void SetSrcType(const std::string& src_type);
// 需转换的文档页码,默认从1开始计数;表格文件中 page 表示转换的第 X 个 sheet
// 的第 X 张图
void SetPage(const int page);
// 转换后的图片处理参数,支持 基础图片处理 所有处理参数,多个处理参数可通过
// 管道操作符 分隔,从而实现在一次访问中按顺序对图片进行不同处理
void SetImageParams(const std::string& image_param);
// 表格文件参数,转换第 X 个表,默认为1
void SetSheet(const int sheet);
// 转换输出目标文件类型
void SetDstType(const std::string& dst_type);
// Office 文档的打开密码,如果需要转换有密码的文档,请设置该字段
void SetPasswd(const std::string& passwd);
// 是否隐藏批注和应用修订,默认为
void SetComment(const int comment);
// 表格文件转换纸张方向,0代表垂直方向,非0代表水平方向,默认为0
void SetExcelPaperDirection(const int direction);
// 生成预览图的图片质量,取值范围 [1-100],默认值100。
// 例:值为100,代表生成图片质量为100%
void SetQuality(const int quality);
// 预览图片的缩放参数,取值范围[10-200], 默认值100。 例:值为200,代表图片缩放比例为200% 即放大两倍
void SetScale(const int scale);
resp 有如下方法:
// 返回文档总页数(表格文件表示当前 sheet 转换后的总图片数),异常时为空
int GetTotalPage() const { return m_x_total_page; }
// 当异常时返回错误码
std::string GetErrNo() const { return m_x_errno; }
// 返回文档中总表数
int GetTotalSheet() const { return m_x_total_sheet; }
// 返回当前 sheet 名
std::string GetSheetName() const { return m_sheet_name; }

异步处理任务接口

提交预览任务

功能说明

提交一个文档预览任务。

方法原型

CosResult CreateDocProcessJobs(const CreateDocProcessJobsReq& request, CreateDocProcessJobsResp *response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

CreateDocProcessJobsReq req;
CreateDocProcessJobsResp resp;

Input input;
input.object = "xxx.docx";
req.SetInput(input);

Operation operation;
Output output;
output.bucket = "examplebucket-1250000000";
output.region = "ap-guangzhou";
output.object = "test-${Number}";

operation.output = output;
req.SetOperation(operation);

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

参数说明

参数
参数描述
类型
是否必填
req
CreateDocProcessJobs 操作的请求
CreateDocProcessJobsReq
resp
CreateDocProcessJobs 操作的响应
CreateDocProcessJobsResp
req 有如下方法:
void SetTag(const std::string& tag);
void SetOperation(const Operation& operation);
void SetInput(const Input& input);
void SetQueueId(const std::string& queue_id);
resp 涉及到如下结构:
struct Input {
std::string object; // 文件在 COS 上的文件路径,Bucket 由 Host 指定
};

struct Output {
std::string region; // 存储桶的地域
std::string bucket; // 存储结果的存储桶
std::string object; // 输出文件路径
};

struct DocProcess {
std::string src_type; // 源数据的后缀类型
std::string tgt_type; // 转换输出目标文件类型
int sheet_id; // 表格文件参数
int start_page; // 从第 X 页开始转换
int end_page; // 转换至第 X 页
std::string image_params; // 转换后的图片处理参数
std::string doc_passwd; // Office 文档的打开密码
int comments; // 是否隐藏批注和应用修订,默认为0
int paper_direction; // 表格文件转换纸张方向,0代表垂直方向,非0代表水平方向,默认为0
int quality; // 生成预览图的图片质量,取值范围 [1-100],默认值100。
// 例:值为100,代表生成图片质量为100%
int zoom; // 预览图片的缩放参数
};

struct PageInfo {
int page_no; // 预览产物页码,源文件为 Excel 格式时表示 SheetId
std::string tgt_uri; // 预览产物生成的 cos 桶路径
int x_sheet_pics; // 当前 Sheet 生成的图片总数(源文件为 Excel 特有参数)
int pic_index; // 当前预览产物在整个源文件中的序号(源文件为 Excel 特有参数)
int pic_num; // 当前预览产物在 Sheet 中的序号(源文件为 Excel 特有参数)
};

struct DocProcessResult {
PageInfo page_info; // 预览任务产物详情
std::string tgt_type; // 预览产物目标格式
int total_pageount; // 预览任务产物的总数
int succ_pagecount; // 预览任务产物的成功数
int fail_pagecount; // 预览任务产物的失败数
int total_sheetcount; // 预览任务的 Sheet 总数(源文件为 Excel 特有参数)
};

struct Operation {
Output output; // 当 Tag 为 DocProcess 时有效,指定该任务的参数
DocProcess doc_process; // 结果输出地址
DocProcessResult
doc_process_result; // 在 job 的类型为 DocProcess 且 job 状态为 success
// 时,返回文档预览任务结果详情
};

struct JobsDetail {
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; // 该任务的输入文件路径
Operation operation; // 该任务的规则
};

查询指定的文档预览任务

功能说明

查询指定的文档预览任务。

方法原型

CosResult DescribeDocProcessJob(const DescribeDocProcessJobReq& request, DescribeDocProcessJobResp *response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

DescribeDocProcessJobReq req(bucket_name);
DescribeDocProcessJobResp resp;

req.SetJobId("xxx");

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

参数说明

参数
参数描述
类型
是否必填
req
DescribeDocProcessJob 操作的请求
DescribeDocProcessJobReq
resp
DescribeDocProcessJob 操作的响应
DescribeDocProcessJobResp
req 有如下方法:
void SetJobId(const std::string& job_id);
resp有如下方法:
std::vector<JobsDetail> GetJobsDetails() const;

拉取文档预览任务

功能说明

拉取符合条件的文档预览任务。

方法原型

CosResult DescribeDocProcessJobs(const DescribeDocProcessJobsReq& request, DescribeDocProcessJobsResp *response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

DescribeDocProcessJobsReq req(bucket_name);
DescribeDocProcessJobsResp resp;

req.SetQueueId("xxx");

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

参数说明

参数
参数描述
类型
是否必填
req
DescribeDocProcessJobs 操作的请求
DescribeDocProcessJobsReq
resp
DescribeDocProcessJobs 操作的响应
DescribeDocProcessJobsReq
req 有如下方法:
void SetQueueId(const std::string& queue_id);
void SetOrderByTime(const std::string& order);
void SetNextToken(const std::string& next_token);
void SetSize(const int size);
void SetStates(const std::string& states);
void SetStartCreationTime(const std::string& start_time);
void SetEndCreationTime(const std::string& end_time);
resp 有如下方法:
std::vector<JobsDetail> GetJobsDetails() const;
std::string GetNextToken() const;

异步处理队列接口

查询文档预览队列

功能说明

查询文档预览队列。

方法原型

CosResult DescribeDocProcessQueues(const DescribeDocProcessQueuesReq& request, DescribeDocProcessQueuesResp *response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

DescribeDocProcessQueuesReq req(bucket_name);
DescribeDocProcessQueuesResp resp;

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

参数说明

参数
参数描述
类型
是否必填
req
DescribeDocProcessQueues 操作的请求
DescribeDocProcessQueuesReq
resp
DescribeDocProcessQueues 操作的响应
DescribeDocProcessQueuesResp
req 有如下方法:
void SetQueueIds(const std::string& queue_ids) ;
void SetState(const std::string& state);
void SetPageNumber(const std::string& page_number);
void SetPageSize(const std::string& page_size);
resp 涉及到如下结构:
struct NotifyConfig {
std::string url; // 回调地址
std::string state; // 开关状态,On 或者 Off
std::string type; // 回调类型,Url
std::string event; // 触发回调的事件
};

struct QueueList {
std::string queue_id; //队列 ID
std::string name; // 队列名字
std::string state; // 当前状态,Active 或者 Paused
NotifyConfig notify_config; // 回调配置
int max_size; // 队列最大长度
int max_concurrent; // 当前队列最大并行执行的任务数
std::string update_time; // 更新时间
std::string create_time; // 创建时间
std::string bucket_id; //
std::string category; //
};

struct NonExistPIDs {
std::vector<std::string> queue_id; // NonExistPIDs
};
resp 有如下方法:
int GetTotalCount() const;
std::string GetRequestId();
int GetPageNumber() const;
int GetPageSize() const;
QueueList GetQueueList() const;
NonExistPIDs GetNonExistPIDs() const;

更新文档预览队列

功能说明

更新文档预览队列。

方法原型

CosResult UpdateDocProcessQueue(const UpdateDocProcessQueueReq& request, UpdateDocProcessQueueResp *response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

UpdateDocProcessQueueReq req(bucket_name);
UpdateDocProcessQueueResp resp;

req.SetName("xxx");
req.SetQueueId("xxx");
req.SetState("Active");

NotifyConfig notify_config;
notify_config.url = "xxx";
notify_config.state = "On";
req.SetNotifyConfig(notify_config);

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

参数说明

参数
参数描述
类型
是否必填
req
UpdateDocProcessQueue 操作的请求
UpdateDocProcessQueueReq
resp
UpdateDocProcessQueue 操作的响应
UpdateDocProcessQueueResp
req 涉及到如下结构:
struct NotifyConfig {
std::string url; // 回调地址
std::string state; // 开关状态,On 或者 Off
std::string type; // 回调类型,Url
std::string event; // 触发回调的事件
};
req 有如下方法:
void SetQueueId(const std::string& queue_id);
void SetName(const std::string& name);
void SetState(const std::string& state);
void SetNotifyConfig(const NotifyConfig& notify_config);
resp 有如下方法:
std::string GetRequestId() const;
QueueList GetQueueList() const;