全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 钉钉智能硬件

ConvertOfficeFormat

更新时间:2017-12-27 20:40:41

描述

提交 OFFICE 文档格式转换任务,将 OFFICE 文档转换为 JPG。采用异步请求方式执行,执行完毕返回 TaskId,用于查询任务状态。也可以使用通知机制,传入 NotifyTopicName 和 NotifyEndpoint,从而及时通知任务执行信息。

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

目前支持的 OFFICE 文件类型有:ppt/pptx, doc/docx, xls/xlsx。

请求参数

名称 类型 是否必填 描述
Project String 项目名
Action String ConvertOfficeFormat
SrcUri String 源数据的存储位置,
OSS 资源采用如下格式”oss://bucket1/object”
TgtType String 转换输出目标文件类型,目前支持 JPG 格式
TgtUri String 转换输出内容到目标位置,建议 TgtUri 和 SrcUri 在同一个桶,便于权限管理
例如 OSS 桶的指定前缀”oss://bucket1/converttasks/session123/“
ImageSpec String 输出图片的格式,缺省为 1024 像素,
长宽不同时按照最先到达边界的条件进行等比例控制
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/,那么生成的目标文件为:

/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/image_1024.0000.jpg
/bucket1/imm-format-convert-tgt/session123/${ExternalID }-${JodId}/image_1024.0001.jpg

其中image_1024表示输出像素的规格(参考 ImageSpec 参数),0000表示第 0 张图片。

重复请求处理

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

如果两次执行操作的内容相同或者重复请求(内容相同,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 目标文位置无效
本文导读目录