文档服务文档转码同步请求-API 文档-文档中心-腾讯云

功能描述
文档预览功能支持对多种文件类型生成图片格式预览，并可对转换后的图片同步进行基础处理操作，可以解决文档内容的页面展示问题，满足 PC、App 等多个用户端的文档在线浏览需求，适用于在线教育、企业 OA、网站转码等业务场景。
注意：
同步接口默认10秒转换超时, 每次请求返回一页内容，大文件的批量转码等耗时操作建议使用异步接口。
文档转码的转换逻辑与本地的打印逻辑相同，如果您需要改变转换方向（例如将列数较多的 excel 文件横向输出到一页），需要更改源文件打印设置。
授权说明
授权策略中 action 设置为 ci:PreviewDocument，详情请参见 数据万象 action。
服务开通
使用该功能需提前开通数据万象，并绑定存储桶。详情请参见 绑定存储桶。
使用该功能需提前通过控制台或接口开通文档处理服务 。详情请参见 开通文档处理服务。
使用限制
使用该接口时，请先确认相关限制条件。详情请参见 使用限制。
费用说明
该接口为付费服务，调用接口会产生 文档处理费用 和 流量费用，产生的费用将由数据万象收取。
﻿
请求
请求示例
GET /<ObjectKey>?ci-process=doc-preview&page=<page>&srcType=<srcType>&ImageParams=<ImageParams> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
说明：
Authorization: Auth String（详情请参见 请求签名 文档）。
通过子账号使用时，需要授予相关的权限，详情请参见 授权粒度详情 文档。
私有存储桶需要携带下载文件的签名。
请求头
此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。
通用请求参数
名称
描述
类型
是否必选
ObjectKey
对象文件名，例如 folder/document.pdf
String
是
ci-process
数据万象处理能力，文档预览固定为 doc-preview
String
是
srcType
源数据的后缀类型，当前文档转换根据 COS 对象的后缀名来确定源数据类型。当 COS 对象没有后缀名时，可以设置该值
String
否
page
需转换的文档页码，默认从1开始计数；表格文件中 page 表示转换的第 X 个 sheet 的第 X 张图
Int
否
dstType
转换输出目标文件类型：
png，转成 png 格式的图片文件
jpg，转成 jpg 格式的图片文件
如果传入的格式未能识别，默认使用 jpg 格式
String
否
password
Office 文档的打开密码，如果需要转换有密码的文档，请设置该字段
String
否
comment
是否隐藏批注和应用修订，默认为0
0：隐藏批注，应用修订
1：显示批注和修订
Int
否
适用于表格文件（Excel）的参数
名称
描述
类型
是否必选
sheet
表格文件参数，转换第 X 个表，默认为1
Int
否
excelPaperDirection
表格文件转换纸张方向，0代表垂直方向，1代表水平方向，默认为0
Int
否
excelPaperSize
设置纸张（画布）大小，对应信息为： 0 → A4 、 1 → A2 、 2 → A0 ，默认 A4 纸张 （需配合  excelRow  或  excelCol  一起使用）
Int
否
适用于转码成  png/jpg 图片的参数
名称
描述
类型
是否必选
ImageParams
转换后的图片处理参数，支持 基础图片处理 所有处理参数，多个处理参数可通过 管道操作符 分隔，从而实现在一次访问中按顺序对图片进行不同处理。
String
否
quality
生成预览图的图片质量，取值范围为 [1, 100]，默认值100。 例如取值为100，代表生成图片质量为100%。
Int
否
scale
预览图片的缩放参数，取值范围为 [10, 200]， 默认值100。 例如取值为200，代表图片缩放比例为200% 即放大两倍。
Int
否
imageDpi
按指定 dpi 渲染图片，该参数与  scale  共同作用，取值范围  96-600 ，默认值为  96 。转码后的图片单边宽度需小于65500像素。
Int
否
注意：
目前支持的输入文件类型包含如下格式：
演示文件：pptx、ppt、pot、potx、pps、ppsx、dps、dpt、pptm、potm、ppsm。
文字文件：doc、dot、wps、wpt、docx、dotx、docm、dotm。
表格文件：xls、xlt、et、ett、xlsx、xltx、csv、xlsb、xlsm、xltm、ets。
表格文件，一张表可能分割为多页转换，生成多张图片。
其他格式文件： pdf、 lrc、 c、 cpp、 h、 asm、 s、 java、 asp、 bat、 bas、 prg、 cmd、 rtf、 txt、 log、 xml、 htm、 html。
输入文件大小限制在200MB 之内。
输入文件页数限制在5000页之内。
同步接口适用于百页内的 PDF 文件或预览少数页的情况，若文件较大建议使用异步接口。
请求体
该请求的请求体为空。
响应
响应头
此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。
响应参数说明
参数名称
描述
类型
X-Total-Page
在 http header 中返回文档总页数（表格文件表示当前 sheet 转换后的总图片数），异常时为空
Int
Content-Type
根据图片实际的格式，返回不同的值，例如 image/jpeg、image/webp，异常时保持现有值即可
String
X-ErrNo
当异常时返回错误码，可在 http header 中查看
String
X-Total-Sheet
表格文件返回参数，在 http header 中返回文档中总表数
Int
X-Sheet-Name
表格文件返回参数，在 http header 中返回当前 sheet 名
String
错误码
该请求无特有错误信息，常见的错误信息请参见 错误码 文档。
实际案例
案例一：普通文档预览
请求
GET /sample.pdf?ci-process=doc-preview&page=1 HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
响应1：成功预览
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 645
Date: Tue, 03 Apr 2018 09:06:16 GMT
X-Total-Page: 100
﻿
[转码后图片 data]
响应2：文件不存在
HTTP/1.1 404 OK
Connection: close
Content-Length: 455
Content-Type: application/xml
Date: Thu, 09 Apr 2020 13:44:52 GMT
X-ErrNo: -3004
响应3：指定页码不存在
HTTP/1.1 404 OK
Connection: close
Content-Length: 455
Content-Type: application/xml
Date: Thu, 09 Apr 2020 13:44:52 GMT
X-ErrNo: -3013
案例二：文档预览并进行缩放和添加文字水印的图片处理
请求
GET /sample.pdf?ci-process=doc-preview&page=1&ImageParams=imageMogr2/thumbnail/!50p|watermark/2/text/5pWw5o2u5LiH6LGh/fill/I0ZGRkZGRg==/fontsize/30/dx/20/dy/20 HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
响应1：成功预览
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 645
Date: Tue, 03 Apr 2018 09:06:16 GMT
X-Total-Page: 100
﻿
[转码后图片 data]
响应2：文件不存在
HTTP/1.1 404 OK
Connection: close
Content-Length: 455
Content-Type: application/xml
Date: Thu, 09 Apr 2020 13:44:52 GMT
X-ErrNo: -3004
响应3：指定页码不存在
HTTP/1.1 404 OK
Connection: close
Content-Length: 455
Content-Type: application/xml
Date: Thu, 09 Apr 2020 13:44:52 GMT
X-ErrNo: -3015
﻿

名称	描述	类型	是否必选
ObjectKey	对象文件名，例如 folder/document.pdf	String	是
ci-process	数据万象处理能力，文档预览固定为 doc-preview	String	是
srcType	源数据的后缀类型，当前文档转换根据 COS 对象的后缀名来确定源数据类型。当 COS 对象没有后缀名时，可以设置该值	String	否
page	需转换的文档页码，默认从1开始计数；表格文件中 page 表示转换的第 X 个 sheet 的第 X 张图	Int	否
dstType	转换输出目标文件类型： png，转成 png 格式的图片文件 jpg，转成 jpg 格式的图片文件如果传入的格式未能识别，默认使用 jpg 格式	String	否
password	Office 文档的打开密码，如果需要转换有密码的文档，请设置该字段	String	否
comment	是否隐藏批注和应用修订，默认为0 0：隐藏批注，应用修订 1：显示批注和修订	Int	否

参数名称	描述	类型
X-Total-Page	在 http header 中返回文档总页数（表格文件表示当前 sheet 转换后的总图片数），异常时为空	Int
Content-Type	根据图片实际的格式，返回不同的值，例如 image/jpeg、image/webp，异常时保持现有值即可	String
X-ErrNo	当异常时返回错误码，可在 http header 中查看	String
X-Total-Sheet	表格文件返回参数，在 http header 中返回文档中总表数	Int
X-Sheet-Name	表格文件返回参数，在 http header 中返回当前 sheet 名	String

文档转码同步请求

本页目录：

功能描述

授权说明

服务开通

使用限制

费用说明

请求

请求示例

请求头

通用请求参数

适用于表格文件（Excel）的参数

适用于转码成 png/jpg 图片的参数

请求体

响应

响应头

响应参数说明

错误码

实际案例

案例一：普通文档预览

请求

响应1：成功预览

响应2：文件不存在

响应3：指定页码不存在

案例二：文档预览并进行缩放和添加文字水印的图片处理

请求

响应1：成功预览

响应2：文件不存在

响应3：指定页码不存在