› 推特 ›阿里云技术文档›正文

CreateOfficeConversionTask_文档转换异步请求_文档管理操作_API手册_智能媒体管理

admin 阿里云技术文档 2020-02-11 201 0
阿里云服务器优惠

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 种格式：

  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。

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

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

返回参数

名称 类型 描述
RequestId String 用户发送的每次接口调用请求，无论成功与否，系统都会返回一个唯一识别码 RequestId 给用户
TaskId String 任务 ID
TgtLoc String 输出目标文件的位置，和请求参数中的 TgtUri 相同
Status String 任务状态：
  • Running
  • Finished
  • Failed
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 ，则目标文件名称规则如下：

  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
  5. TgtFilePrefix 为 aa，TgtFileSuffix 为 def，则目标文件名称为：aa[x].jpg

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

MNS通知

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

转换成功消息

  1. {
  2.     "events": [
  3.         {
  4.             "eventName": "FormatConvertJob:JobFinished",
  5.             "eventSource": "acs:imm",
  6.             "eventTime": "2018-11-19T08:46:37.35Z",
  7.             "imm": {
  8.                 "taskId": "2E468123-3DEA-29A0-CA35-452ACE867326",
  9.                 "code": "NoError",
  10.                 "pageCount": "32",
  11.                 "percent": "100"
  12.             }
  13.         }
  14.     ]
  15. }

转换失败消息

  1. {
  2.     "events": [
  3.         {
  4.             "eventName": "FormatConvertJob:JobError",
  5.             "eventSource": "acs:imm",
  6.             "eventTime": "2018-11-19T08:46:37.35Z",
  7.             "imm": {
  8.                 "taskId": "2E468123-3DEA-29A0-CA35-452ACE867326",
  9.                 "code": "FailedToDownloadSrcFile",
  10.                 "pageCount": "0",
  11.                 "percent": "0"
  12.             }
  13.         }
  14.     ]
  15. }

示例

请求示例

  1. POST https://imm.cn-shanghai.aliyuncs.com
  2. ?Action=CreateOfficeConversionTask
  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.     "TaskId": "23468948-33EA-28A0-CA35-452ACE867326",
  4.     "TgtLoc": "oss://bucket1/imm-format-convert-tgt/session123/",
  5.     "Status": "Running",
  6.     "CreateTime": "2018-07-20T06:51:17.5Z"
  7. }

相关文档

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

文档转换和预览架构

文档转换使用介绍

文档预览使用介绍

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

版权声明

本文仅代表作者观点，不代表本站立场。
本文系作者授权发表，未经许可，不得转载。

评论

-----