CreateOfficeConversionTask
描述
该接口实现文档格式的转换(典型如 OFFICE 文档格式),用于文档预览、打印等场景。
它采用异步请求方式执行,执行完毕返回 TaskId,使用 GetOfficeConversionTask 接口来查询该 TaskId,可以查看任务执行结果(注意:任务执行信息只保存7天,请及时获取任务执行信息)。也可以使用通知机制,传入 NotifyTopicName 和 NotifyEndpoint,从而及时通知任务执行信息。请参考 SDK 示例代码。
请求参数
名称 | 类型 | 是否必填 | 描述 |
---|---|---|---|
Project | String | 是 | 项目名 |
Action | String | 是 | CreateOfficeConversionTask |
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 时才会生效 |
NotifyTopicName | String | 否 | 异步反向通知的 TopicName,例如:topic1 |
NotifyEndpoint | String | 否 | 异步反向通知的 Endpoint,文件转换状态可以通过该 Endpoint 异步通知到调用者,需要先开通 MNS 服务,新建 topic,queue,并配置好订阅关系。 例如:http://1111111111.mns.cn-shanghai.aliyuncs.com,注意MNS的region必须和和IMM保持一致 |
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] |
IdempotentToken | String | 否 | 幂等标识,建议使用 UUID 格式。参考关于幂等。 |
目前支持的 输入文件类型 包含如下 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
模式,按文件样式每页生成生成一个 txt 文件。
返回参数
名称 | 类型 | 描述 |
---|---|---|
RequestId | String | 用户发送的每次接口调用请求,无论成功与否,系统都会返回一个唯一识别码 RequestId 给用户 |
TaskId | String | 任务 ID |
TgtLoc | String | 输出目标文件的位置,和请求参数中的 TgtUri 相同 |
Status | String | 任务状态:
|
CreateTime | String | 任务创建时间,例如”2018-07-17T09:35:33.466Z” |
基于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
注意:只支持演示类型和文字类型的源文件
关于幂等(重复请求处理)
当传入 IdempotentToken (幂等标识)时,若两次请求完全一致(包括 IdempotentToken 本身),则会返回相同结果(即返回相同的 TaskId )。该功能用于避免多次执行同样的任务,消耗额外计算资源。
IdempotentToken 建议使用 UUID 格式,如 d1fdd246-e187-11e8-9f32-f2801f1b9fd1 。不同请求请生成独立的 IdempotentToken 。
IdempotentToken 有效期约为 43200 秒,但原则上不建议复用同一个 IdempotentToken 。
IMM 尽力保证幂等有效。但当出现 ServiceUnavailable 等 HTTP 状态码为 5xx 的状况时,IdempotentToken 可能失效。在这种状态下,可能会重复创建该任务。
转换生成目标文件
生成的目标文件会持久化保存,推荐为某个桶下的 /imm-format-convert-tgt/${name} 路径,从而便于维护管理。
您可以主动删除转换后的目标文件,如果不主动删除则会长期保留以备使用,但是会占用存储空间。如果希望自动的删除目标文件,您也可以在 /imm-format-convert-tgt 前缀下配置 OSS 的生命周期,这样目标文件在到期后,会根据策略被清除。
自定义目标文件名称
当前文档转换通过设置 TgtFilePrefix 和 TgtFileSuffix 来支持自定义文件名称
TgtFileSuffix 中 def 为保留字,表示采用默认的后缀名。
假设 TgtType 为 jpg ,则目标文件名称规则如下:
- TgtFilePrefix 和 TgtFileSuffix 都为空的条件下,目标文件名称为:[x].jpg
- TgtFilePrefix 为空,TgtFileSuffix 为 aa,则目标文件名称为:[x]aa
- TgtFilePrefix 为 aa,TgtFileSuffix 为空,则目标文件名称为:aa[x]
- TgtFilePrefix 为 aa,TgtFileSuffix 为 bb,则目标文件名称为:aa[x]bb
- TgtFilePrefix 为 aa,TgtFileSuffix 为 def,则目标文件名称为:aa[x].jpg
备注:[x]表示多个目标文件,从1开始,如果转换后的文件有8页,则所有的目标文件为:aa[1]bb,aa[2]bb,…, aa[8]bb
MNS通知
输入参数里面如果设置了 NotifyTopicName 和 NotifyEndpoint 支持 MNS事件通知,那么 IMM 会给您返回异步通知,比如文件转换的页数,通知的消息格式为:
转换成功消息
{
"events": [
{
"eventName": "FormatConvertJob:JobFinished",
"eventSource": "acs:imm",
"eventTime": "2018-11-19T08:46:37.35Z",
"imm": {
"taskId": "2E468123-3DEA-29A0-CA35-452ACE867326",
"code": "NoError",
"pageCount": "32",
"percent": "100"
}
}
]
}
转换失败消息
{
"events": [
{
"eventName": "FormatConvertJob:JobError",
"eventSource": "acs:imm",
"eventTime": "2018-11-19T08:46:37.35Z",
"imm": {
"taskId": "2E468123-3DEA-29A0-CA35-452ACE867326",
"code": "FailedToDownloadSrcFile",
"pageCount": "0",
"percent": "0"
}
}
]
}
示例
请求示例
POST https://imm.cn-shanghai.aliyuncs.com
?Action=CreateOfficeConversionTask
&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",
"TaskId": "23468948-33EA-28A0-CA35-452ACE867326",
"TgtLoc": "oss://bucket1/imm-format-convert-tgt/session123/",
"Status": "Running",
"CreateTime": "2018-07-20T06:51:17.5Z"
}
相关文档
版权声明
本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。
评论