全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 更多
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 智能硬件

ConvertOfficeFormat

更新时间:2018-04-16 20:44:41

描述

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

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

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

目前支持的OFFICE(或其它)文件类型有:

  1. 演示文件:pptx”, “ppt”, “pot”, “potx”, “pps”, “ppsx”, “dps”, “dpt”, “pptm”, “potm”, “ppsm”
  2. 表格文件:”xls”, “xlt”, “et”, “ett”, “xlsx”, “xltx”, “csv”, “xlsb”, “xlsm”, “xltm”
  3. 文字文件:”doc”, “dot”, “wps”, “wpt”, “docx”, “dotx”, “docm”, “dotm”
  4. 其他格式文件:”pdf”,”lrc”, “c”, “cpp”, “h”, “asm”, “s”, “java”, “asp”, “bat”, “bas”, “prg”, “cmd”,”rtf”, “txt”, “log”, “xml”, “htm”, “html”

目前支持的目的类型为:

  1. vector向量模式,需要使用特定的js渲染引擎进行预览
  2. jpg模式
  3. png模式
  4. 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 会给您返回异步通知,比如文件转换的页数,通知的消息格式为:

  1. {
  2. events”: [
  3. {
  4. eventName”: NewTask:TaskFinished”,
  5. eventSource”: acs:imm”,
  6. imm”: {
  7. taskId”: 23468948-33EA-28A0-CA35-452ACE867326”,
  8. tgtLoc”: oss://test-imm/converttasks/aaa-23468948-33EA-28A0-CA35-452ACE867326/”,
  9. status”: Finished”,
  10. "pageCount": "32",
  11. percent”: 100
  12. }
  13. }
  14. ]
  15. }

示例

请求示例

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

成功返回示例

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

特殊错误码

错误代码 错误信息 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 目标文位置无效

相关文档

文档转换和预览架构

文档转换使用介绍

文档预览使用介绍

本文导读目录