ConvertOfficeFormat_Office文档格式转换_Engine处理引擎操作_API手册

描述

提交 OFFICE 文档格式转换任务，将 OFFICE（或其它）文档转换为可预览的文件类型。

采用异步请求方式执行，执行完毕返回 TaskId，用于查询任务状态。也可以使用通知机制，传入 NotifyTopicName 和 NotifyEndpoint，从而及时通知任务执行信息。

采用 SignatureNonce 来区分不同的任务请求，为了更好的支持幂等性，对于相同的请求，以最后被执行的请求为准。

目前支持的OFFICE（或其它）文件类型有：

演示文件：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”

目前支持的目的类型为：

vector向量模式，需要使用特定的js渲染引擎进行预览
jpg模式
png模式
pdf模式

请求参数

名称	类型	是否必填	描述
Project	String	是	项目名
Action	String	是	ConvertOfficeFormat
SrcUri	String	是	源数据的存储位置， OSS 资源采用如下格式”oss://bucket1/object”
SrcType	String	否	源数据的后缀类型，当前文档转换根据 OSS 对象的后缀名来确定源数据类型，当OSS 对象没有后缀名时，可以设置该值
TgtType	String	是	转换输出目标文件类型，合法的值为”vector”, “jpg”, “pdf”, “vector”，不区分大小写
TgtUri	String	是	转换输出内容到目标位置，建议 TgtUri 和 SrcUri 在同一个桶，便于权限管理例如 OSS 桶的指定前缀”oss://bucket1/converttasks/session123/“
NotifyTopicName	String	否	异步反向通知的 TopicName
NotifyEndpoint	String	否	异步反向通知的 Endpoint，文件转换状态可以通过该 Endpoint 异步通知到调用者
ExternalID	String	否	任务的外部标签，用于区分不同的任务

返回参数

名称	类型	描述
RequestId	String	用户发送的每次接口调用请求，无论成功与否，系统都会返回一个唯一识别码 RequestId 给用户
TaskId	String	任务 ID
TgtLoc	String	输出目标文件的位置，输入参数 ExternalID 不为空，以 TgtUri/{ExternalID}-${TaskdId} 为前缀，输入参数 ExternalID 为空，以 TgtUri/${TaskdId} 为前缀，便于名字空间隔离
Status	String	任务状态： Running Finished Failed
CreateTime	String	任务创建时间，例如”2017-12-14 10:28:35.360268 +0800 CST”

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

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

目标类型为vector时
- 如果源文件为非excel类型
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/meta.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/fp1.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/fp2.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/fp[...].json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/I/1
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/I/2
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/I/[...]
- 如果源文件为excel类型
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/meta.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s1/meta.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s1/fp1.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s1/fp2.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s1/fp[...].json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s2/meta.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s2/fp1.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s2/fp2.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s2/fp[...].json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s[...]/meta.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s[...]/fp1.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s[...]/fp2.json
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/doc/s[...]/fp[...].json

注意：vector模式需要使用特定的js引擎进行渲染。
目标类型为jpg时
- 如果源文件为非excel类型
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/1.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/2.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/[...].jpg
- 如果源文件为excel类型
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s1/1.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s1/2.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s1/[...].jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s2/1.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s2/2.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s2/[...].jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s[...]/1.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s[...]/2.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s[...]/[...].jpg

注意：源文件为excel类型时，会先根据excel的表格数，生成对应数量的文件夹，再在对应的文件夹下，生成对应数量的jpg文件
目标类型为png时
- 如果源文件为非excel类型
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/1.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/2.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/[...].png
- 如果源文件为excel类型
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s1/1.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s1/2.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s1/[...].png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s2/1.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s2/2.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s2/[...].png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s[...]/1.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s[...]/2.png
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/s[...]/[...].png

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

/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/1.pdf

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

重复请求处理

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

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

转换生成目标文件

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

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

MNS通知

输入参数里面如果设置了 NotifyTopicName 和 NotifyEndpoint 支持 MNS事件通知，那么 IMM 会给您返回异步通知，比如文件转换的页数，通知的消息格式为：

{
    “events”: [
        {
            “eventName”: “NewTask:TaskFinished”,
            “eventSource”: “acs:imm”,
            “imm”: {
                “taskId”: “23468948-33EA-28A0-CA35-452ACE867326”,
                “tgtLoc”: “oss://test-imm/converttasks/aaa-23468948-33EA-28A0-CA35-452ACE867326/”,
                “status”: “Finished”,
                "pageCount": "32",
                “percent”: “100”
            }
        }
    ]
}

示例

请求示例

POST https://imm.cn-shanghai.aliyuncs.com?Action=ConvertOfficeFormat
&Project=test
&SrcUri="oss://bucket1/test.pptx"
&TgtType=jpg
&TgtUri="oss://bucket1/imm-format-convert-tgt/session123/"
&ExternalID=aaa

成功返回示例

{
    "RequestId": "FF3B7D81-66AE-47E0-BF69-157DCF187514",
    "TaskId": "23468948-33EA-28A0-CA35-452ACE867326",
    "TgtLoc": "oss://bucket1/imm-format-convert-tgt/session123/aaa-23468948-33EA-28A0-CA35-452ACE867326/",
    "Status": "Running",
    "CreateTime": "2017-11-14 10:28:35.360268 +0800 CST"
}

特殊错误码

错误代码	错误信息	HTTP 状态码	说明
InvalidSourceType	The source type is not supported	400	源文件格式不支持
InvalidSourceURI	The source URI is not valid.	400	源文件的 URI 无效
EmptySrcFile	The source file is empty	400	源文件为空
InvalidTgtType	The target type is not supported	400	目标文件格式不支持
InvalidTgtURI	The traget URI is not valid	400	目标文位置无效

ConvertOfficeFormat

描述