控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

同步请求接口

最近更新时间:2021-09-24 11:11:54

功能描述

文档预览功能支持对多种文件类型生成图片格式预览,并可对转换后的图片同步进行基础处理操作,可以解决文档内容的页面展示问题,满足 PC、App 等多个用户端的文档在线浏览需求,适用于在线教育、企业 OA、网站转码等业务场景。

说明:

  • 使用时您需要先开通服务,详情请参见 设置文档预览。开通服务后,对于当前存储桶中的文档资源,使用相应的文档预览 API 接口即可实现同步或异步文档预览请求。
  • 文档预览为付费功能,由数据万象收取,每个账户每月拥有三千页免费额度,超出后进行计费。具体费用请参见 文档处理费用
  • 文档转码的转换逻辑与本地的打印逻辑相同,如果您需要改变转换方向(例如将列数较多的 excel 文件横向输出到一页),需要更改源文件打印设置。

请求

请求示例

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
ImageParams 转换后的图片处理参数,支持 基础图片处理 所有处理参数,多个处理参数可通过 管道操作符 分隔,从而实现在一次访问中按顺序对图片进行不同处理 String
sheet 表格文件参数,转换第 X 个表,默认为1 Int
dstType 转换输出目标文件类型:
  • png,转成 png 格式的图片文件
  • jpg,转成 jpg 格式的图片文件
  • pdf,转成pdf 格式文件
    如果传入的格式未能识别,默认使用 jpg 格式
  • String
    password Office 文档的打开密码,如果需要转换有密码的文档,请设置该字段 String
    comment 是否隐藏批注和应用修订,默认为 0。
  • 0:隐藏批注,应用修订
  • 1:显示批注和修订
  • Int
    excelPaperDirection 表格文件转换纸张方向,0代表垂直方向,非0代表水平方向,默认为0 Int
    quality 生成预览图的图片质量,取值范围为 [1, 100],默认值100。 例如取值为100,代表生成图片质量为100% Int
    scale 预览图片的缩放参数,取值范围为 [10, 200], 默认值100。 例如取值为200,代表图片缩放比例为200% 即放大两倍 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页之内。

    请求体

    该请求的请求体为空。

    响应

    响应头

    此接口仅返回公共响应头部,详情请参见 公共响应头部 文档。

    响应参数说明

    参数名称 描述 类型
    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: -3013

    目录