全部产品
云市场

文档转换同步请求

更新时间:2019-04-01 10:17:27

ConvertOfficeFormat

该接口实现 OFFICE 文档格式的转换,用于文档打印、预览等场景。

它采用 同步请求 方式执行,执行完毕返回转换成功的页数。注意,同步转换超时时间为 5秒,如果大于 5秒 的转换需要使用异步接口 CreateOfficeConversionTask

请求参数

名称 类型 是否必填 描述
Project String 项目名
Action String ConvertOfficeFormat
SrcUri String 源数据的存储位置,
OSS 资源采用如下格式”oss://bucket1/object”
SrcType String 源数据的后缀类型,当前文档转换根据 OSS 对象的后缀名来确定源数据类型,当 OSS 对象没有后缀名时,可以设置该值
TgtType String 转换输出目标文件类型:
vector,转成向量文件,需要使用 js 引擎来进行渲染
png,转成 png 格式的图片文件
jpg,转成 jpg 格式的图片文件
pdf,转成 pdf 文件
text,转成只包含文本内容的文件,主要用来提取文件的文本内容,注意只支持演示和表格文件类型
TgtUri String 转换输出内容到目标位置,建议 TgtUri 和 SrcUri 在同一个桶,便于权限管理
例如 OSS 桶的指定前缀”oss://bucket1/converttasks/session123/“
Password String Office 文档的打开密码,如果需要转换有密码的文档,请设置该字段
StartPage int 从第 x 页开始转换,默认为1
EndPage int 转换至第 x 页,默认为200,如果需要转换全部页,设置为-1
MaxSheetRow int 表格文件转换最大行数,默认为1000。如果需要转换所有行,设置为-1
MaxSheetCol int 表格文件转换最大列数,默认为100,如果需要转换所有行,设置为-1
MaxSheetCount int 表格文件转换最多 sheet 数,如果需要转换所有Sheet,设置为-1
FitToPagesTall bool 表格文件转 pdf 时,将行全部输出到一页,默认为 false,只有设置 TgtType 为 pdf 时才会生效
FitToPagesWide bool 表格文件转 pdf 时,将列全部输出在一页,默认为 false,只有设置 TgtType 为 pdf 时才会生效
TgtFilePrefix String 转换后的文件名称前缀,在目标类型为 jpg, png, pdf 时才生效,可以是英文,数字,横划线,下划线,长度不超过256个字符,参考自定义目标文件名称
TgtFileSuffix String 转换后的文件名称后缀,在目标类型为 jpg, png, pdf 时才生效,可以是英文,数字,横划线,下划线,点号,长度不超过256个字符,参考自定义目标文件名称
TgtFilePages String 转换后输出指定文件页数,在目标类型为 jpg, png, pdf时才生效,默认输出所有页。例如:[1, 2, 100],只会输出1,2,100页到 TgtUri,最多指定100个页数,如果超过100页,请分多次转换进行提交
PdfVector bool pdf 转换成 vector 时,是否使用向量模式,默认为 false
true:使用向量模式,预览效果比较清晰,转换耗时较长
false:使用图片模式,预览效果一般,转换耗时较短
Hidecomments bool word, ppt 转换成 vector, jpg, png 时,是否隐藏批注和应用修订,默认为 false
true:隐藏批注,应用修订
false:显示批注和修订
DisplayDpi int 转换 jpg,png 时,设置图片分辨率,取值范围[96, 2048]

目前支持的 输入文件类型 包含如下 48 种格式:

  1. 演示文件:pptxpptpotpotxppsppsxdpsdptpptmpotmppsm
  2. 表格文件:xlsxltetettxlsxxltxcsvxlsbxlsmxltm
  3. 文字文件:docdotwpswptdocxdotxdocmdotm
  4. 其他格式文件: pdflrcccpphasmsjavaaspbatbasprgcmdrtftxtlogxmlhtmhtml

目前支持的 输出文件类型 有如下 4 种:

  1. vector 向量模式,使用智能媒体管理产品提供的 前端渲染引擎,更好的支持翻页、缩放。
  2. jpg 模式,按文件样式每页生成一张 jpg 图片。
  3. png 模式,按文件样式每页生成一张 png 图片。
  4. pdf 模式,每个文件生成一个 pdf 文件。
  5. text 模式,按文件样式每页生成一个 text 文件

返回参数

名称 类型 描述
RequestId String 用户发送的每次接口调用请求,无论成功与否,系统都会返回一个唯一识别码 RequestId 给用户
PageCount Integer 转换成功的页数

基于TgtUri返回TgtLoc,在OSS对象存储中的命名规则

基于 TgtUri 参数指定的前缀,比如/bucket1/imm-format-convert-tgt/session123/,根据转换目标类型的不同,那么生成的目标文件也有所不同:

  • 目标类型为 vector 时

    • 如果源文件为非 excel 类型

    /bucket1/imm-format-convert-tgt/session123/doc/meta.json
    /bucket1/imm-format-convert-tgt/session123/doc/fp1.json
    /bucket1/imm-format-convert-tgt/session123/doc/fp2.json
    /bucket1/imm-format-convert-tgt/session123/doc/fp[...].json
    /bucket1/imm-format-convert-tgt/session123/doc/I/1
    /bucket1/imm-format-convert-tgt/session123/doc/I/2
    /bucket1/imm-format-convert-tgt/session123/doc/I/[...]

    • 如果源文件为 excel 类型

    /bucket1/imm-format-convert-tgt/session123/doc/meta.json
    /bucket1/imm-format-convert-tgt/session123/doc/s1/meta.json
    /bucket1/imm-format-convert-tgt/session123/doc/s1/fp1.json
    /bucket1/imm-format-convert-tgt/session123/doc/s1/fp2.json
    /bucket1/imm-format-convert-tgt/session123/doc/s1/fp[...].json
    /bucket1/imm-format-convert-tgt/session123/doc/s2/meta.json
    /bucket1/imm-format-convert-tgt/session123/doc/s2/fp1.json
    /bucket1/imm-format-convert-tgt/session123/doc/s2/fp2.json
    /bucket1/imm-format-convert-tgt/session123/doc/s2/fp[...].json
    /bucket1/imm-format-convert-tgt/session123/doc/s[...] /meta.json
    /bucket1/imm-format-convert-tgt/session123/doc/s[...]/fp1.json
    /bucket1/imm-format-convert-tgt/session123/doc/s[...]/fp2.json
    /bucket1/imm-format-convert-tgt/session123/doc/s[...]/fp[...].json

    注意:vector 模式需要使用特定的 js 引擎进行渲染。

  • 目标类型为 jpg 时

    • 如果源文件为非 excel 类型

    /bucket1/imm-format-convert-tgt/session123/1.jpg
    /bucket1/imm-format-convert-tgt/session123/2.jpg
    /bucket1/imm-format-convert-tgt/session123/[...].jpg

    • 如果源文件为 excel 类型

    /bucket1/imm-format-convert-tgt/session123/s1/1.jpg
    /bucket1/imm-format-convert-tgt/session123/s1/2.jpg
    /bucket1/imm-format-convert-tgt/session123/s1/[...].jpg
    /bucket1/imm-format-convert-tgt/session123/s2/1.jpg
    /bucket1/imm-format-convert-tgt/session123/s2/2.jpg
    /bucket1/imm-format-convert-tgt/session123/s2/[...].jpg
    /bucket1/imm-format-convert-tgt/session123/s[...]/1.jpg
    /bucket1/imm-format-convert-tgt/session123/s[...]/2.jpg
    /bucket1/imm-format-convert-tgt/session123/s[...]/[...].jpg

    注意:源文件为 excel 类型时,会先根据 excel 的表格数,生成对应数量的文件夹,再在对应的文件夹下,生成对应数量的 jpg 文件

  • 目标类型为 png 时

    • 如果源文件为非 excel 类型

    /bucket1/imm-format-convert-tgt/session123/1.png
    /bucket1/imm-format-convert-tgt/session123/2.png
    /bucket1/imm-format-convert-tgt/session123/[...].png

    • 如果源文件为 excel 类型

    /bucket1/imm-format-convert-tgt/session123/s1/1.png
    /bucket1/imm-format-convert-tgt/session123/s1/2.png
    /bucket1/imm-format-convert-tgt/session123/s1/[...].png
    /bucket1/imm-format-convert-tgt/session123/s2/1.png
    /bucket1/imm-format-convert-tgt/session123/s2/2.png
    /bucket1/imm-format-convert-tgt/session123/s2/[...].png
    /bucket1/imm-format-convert-tgt/session123/s[...]/1.png
    /bucket1/imm-format-convert-tgt/session123/s[...]/2.png
    /bucket1/imm-format-convert-tgt/session123/s[...]/[...].png

    注意:源文件为 excel 类型时,会先根据 excel 的表格数,生产对应数量的文件夹,再在对应的文件夹下,生成对应数量的 png 文件

  • 目标类型为 pdf 时

    /bucket1/imm-format-convert-tgt/session123/1.pdf

    注意:转换 pdf 时,无论源文件是什么类型,都只会生成一个 pdf 文件

  • 目标类型为 text 时

    /bucket1/imm-format-convert-tgt/session123/1.text
    /bucket1/imm-format-convert-tgt/session123/2.text
    /bucket1/imm-format-convert-tgt/session123/[...].text

    注意:只支持演示类型和文字类型的源文件

重复请求处理

基于幂等性的要求, 两次相同操作以最后执行的请求为准。

如果两次执行操作的内容相同或者重复请求(内容相同,SignatureNonce 也相同),并且系统已经存在该任务,则后续的请求直接返回成功,避免消耗计算资源做相同的任务。

转换生成目标文件

生成的目标文件会持久化保存,推荐为某个桶下的 /imm-format-convert-tgt/${name} 路径,从而便于维护管理。

您可以主动删除转换后的目标文件,如果不主动删除则会长期保留以备使用,但是会占用存储空间。如果希望自动的删除目标文件,您也可以在 /imm-format-convert-tgt 前缀下配置 OSS 的生命周期,这样目标文件在到期后,会根据策略被清除。

自定义目标文件名称

当前文档转换通过设置 TgtFilePrefix 和 TgtFileSuffix 来支持自定义文件名称

假设 TgtType 为 jpg,则目标文件名称规则如下:

  1. TgtFilePrefix 和 TgtFileSuffix 都为空的条件下,目标文件名称为:[x].jpg
  2. TgtFilePrefix 为空,TgtFileSuffix 为 aa,则目标文件名称为:[x]aa
  3. TgtFilePrefix 为 aa,TgtFileSuffix 为空,则目标文件名称为:aa[x]
  4. TgtFilePrefix 为 aa,TgtFileSuffix 为 bb,则目标文件名称为:aa[x]bb

备注:[x] 表示多个目标文件,从1开始,如果转换后的文件有8页,则所有的目标文件为:

aa[1]bb,

aa[2]bb,

…,

aa[8]bb

示例

请求示例

  1. POST https://imm.cn-shanghai.aliyuncs.com
  2. ?Action=ConvertOfficeFormat
  3. &Project=test
  4. &SrcUri="oss://bucket1/test.pptx"
  5. &TgtType=vector
  6. &TgtUri="oss://bucket1/imm-format-convert-tgt/session123/"
  7. ...

此处的示例,目的是展示关键参数,还需要其他的公共参数才能正常调用,推荐使用 SDK 来发送 API。

成功返回示例

  1. {
  2. "RequestId": "FF3B7D81-66AE-47E0-BF69-157DCF187514",
  3. "PageCount": 10
  4. }

特殊错误码

如果转换出错,在返回的 JSON 中会包含如下字段

  1. {
  2. "RequestId": "7DA1FCD1-004C-4EB4-B039-C6BBDCEB0701",
  3. "HostId": "imm.cn-shanghai.aliyuncs.com",
  4. "Code": "DocumentConvertFailed.NeedPassword",
  5. "Message": "The conversion has been failed, need password to open file."
  6. }
错误代码 说明
OSSAccessError OSS 访问失败,请检查 SrcUri,TgtUri 对应的 bucket,路径是否存在,所在 Region 是否和 IMM Region 一致
InvalidParameter.SrcType.NotSupported 不支持的文件类型,当前文档转换根据文件后缀名来判断文件类型,请检查文件后缀名,SrcType 参数
DocumentConvertFailed.ExceedFileSizeLimit 当前文档转换默认支持 40 MB 文件大小,超过该大小的文件转换时会抛出该错误
DocumentConvertFailed.OpenFileError 转换时,打开文件失败,请检查源文档后缀和内容是否匹配
DocumentConvertFailed.ExportFileError 转换时,处理文件内容失败,请检查源文档是否能够正常打开
DocumentConvertFailed.NeedPassword 该文档需要密码才能打开,请设置 Password 参数
ExecutionTimeout 执行超时,请检查文档大小,页数,如果确实需要转换,请使用异步接口 CreateOfficeConversionTask
InternalError 内部错误,请开工单并提供 RequestId

参考文档

智能媒体管理 Host 的预览服务

文档转换和预览架构

文档转换使用介绍

文档预览使用介绍

若在使用中有疑问,请参考 FAQ,或者进入 钉钉用户群 实时交流。