文档转换同步请求
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 种格式:
- 演示文件:
pptx
、ppt
、pot
、potx
、pps
、ppsx
、dps
、dpt
、pptm
、potm
、ppsm
。 - 表格文件:
xls
、xlt
、et
、ett
、xlsx
、xltx
、csv
、xlsb
、xlsm
、xltm
。 - 文字文件:
doc
、dot
、wps
、wpt
、docx
、dotx
、docm
、dotm
。 - 其他格式文件:
pdf
、lrc
、c
、cpp
、h
、asm
、s
、java
、asp
、bat
、bas
、prg
、cmd
、rtf
、txt
、log
、xml
、htm
、html
。
目前支持的 输出文件类型 有如下 4 种:
vector
向量模式,使用智能媒体管理产品提供的 前端渲染引擎,更好的支持翻页、缩放。jpg
模式,按文件样式每页生成一张 jpg 图片。png
模式,按文件样式每页生成一张 png 图片。pdf
模式,每个文件生成一个 pdf 文件。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,则目标文件名称规则如下:
- TgtFilePrefix 和 TgtFileSuffix 都为空的条件下,目标文件名称为:[x].jpg
- TgtFilePrefix 为空,TgtFileSuffix 为 aa,则目标文件名称为:[x]aa
- TgtFilePrefix 为 aa,TgtFileSuffix 为空,则目标文件名称为:aa[x]
- TgtFilePrefix 为 aa,TgtFileSuffix 为 bb,则目标文件名称为:aa[x]bb
备注:[x] 表示多个目标文件,从1开始,如果转换后的文件有8页,则所有的目标文件为:
aa[1]bb,aa[2]bb,…,aa[8]bb示例
请求示例
POST https://imm.cn-shanghai.aliyuncs.com
?Action=ConvertOfficeFormat
&Project=test
&SrcUri="oss://bucket1/test.pptx"
&TgtType=vector
&TgtUri="oss://bucket1/imm-format-convert-tgt/session123/"
...
此处的示例,目的是展示关键参数,还需要其他的公共参数才能正常调用,推荐使用 SDK 来发送 API。
成功返回示例
{
"RequestId": "FF3B7D81-66AE-47E0-BF69-157DCF187514",
"PageCount": 10
}
特殊错误码
如果转换出错,在返回的 JSON 中会包含如下字段
{
"RequestId": "7DA1FCD1-004C-4EB4-B039-C6BBDCEB0701",
"HostId": "imm.cn-shanghai.aliyuncs.com",
"Code": "DocumentConvertFailed.NeedPassword",
"Message": "The conversion has been failed, need password to open file."
}
错误代码 | 说明 |
---|---|
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 |
参考文档
版权声明
本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。
评论