调用CreateOfficeConversionTask接口采用异步请求方式进行文档(例如Office文档)格式的转换,执行完成后返回TaskId。

注意事项

执行完成后,使用GetOfficeConversionTask接口查询返回的TaskId,可以查看任务执行结果。任务执行信息只保存7天,请及时获取任务执行信息,您也可以使用通知机制,传入NotifyTopicName和NotifyEndpoint,及时通知任务执行信息。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String CreateOfficeConversionTask

操作接口名称,系统规定参数,固定取值为CreateOfficeConversionTask。

Project String immdoctest

项目名称。

SrcUri String oss://bucket1/object

源数据的存储位置。

OSS地址规则为oss://bucket/object,其中bucket为和当前项目处于同一区域的OSS Bucket名称,object为文件路径。

TgtUri String oss://bucket1/imm-format-convert-tgt/session123/

转换后输出内容的目标位置,建议TgtUri和SrcUri在同一个OSS Bucket中,便于权限管理。

生成的目标文件会持久化保存,推荐设置为OSS Bucket下的/imm-format-convert-tgt/${name}路径,便于维护管理。

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

RegionId String cn-hangzhou

项目所在地域的ID。

地域Endpoint格式为imm.RegionId.aliyuncs.com,例如当RegionId为cn-hangzhou时,地域Endpoint为imm.cn-hangzhou.aliyuncs.com。

TgtType String vector

转换输出的目标文件类型。包括如下选项:

  • vector:转换为向量格式的文件,需要使用预览引擎进行渲染后才能预览。
  • png:转换为PNG格式的图片文件。
  • jpg:转换为JPG格式的图片文件。
  • pdf:转换为PDF文件。
  • text:转换为只包含文本内容的文件,主要用于提取文件的文本内容。
    说明 源数据类型只支持演示文档和文字文档类型。
NotifyTopicName String topic1

异步反向通知的TopicName。

NotifyEndpoint String http://1111111111.mns.cn-hangzhou.aliyuncs.com

异步反向通知的Endpoint,文档转换状态可以通过该Endpoint异步通知给调用者。使用此功能需要先开通MNS服务,新建topic和queue,并配置订阅关系。

说明 MNS服务和智能媒体管理必须处于同一地域。
SrcType String doc

当OSS对象没有后缀名时,可以设置此参数。

源数据的后缀类型。默认根据OSS对象的后缀名确定源数据的类型。

StartPage Long 1

文档转换的起始页,默认值为1。

EndPage Long 10

文档转换的结束页,默认值为200。如果需要转换所有页,设置此参数为-1。

MaxSheetRow Long 10

表格文档转换的最大行数,默认值为1000。如果需要转换所有行,设置此参数为-1。

MaxSheetCol Long 10

表格文档转换的最大列数,默认值为100。如果需要转换所有列,设置此参数为-1。

MaxSheetCount Long 3

表格文档转换的最大Sheet数。如果需要转换所有Sheet,设置此参数为-1。

SheetOnePage Boolean false

当TgtType设置为pdf时,此参数才生效。

表格文档转换为pdf时,是否将Sheet的所有内容输出到一页。

ModelId String

模型ID。此参数暂不可用。

Password String ********

文档的打开密码。如果需要转换有密码的文档,请设置此参数。

TgtFilePrefix String aa

当TgtType设置为jpg、png、pdf时,此参数才生效。

转换后的文件名称前缀,可以是英文、数字、横划线和下划线,且长度不超过256个字符。

通过设置TgtFilePrefix和TgtFileSuffix,可以实现自定义转换后的文件名称。

如果TgtType设置为jpg,TgtFilePrefix和TgtFileSuffix设置不同时,目标文件的名称规则如下:

  • 当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开始。如果TgtFilePrefix为aa,TgtFileSuffix为bb,且转换后的文件有3页,则所有的目标文件为aa[1]bb、aa[2]bb、aa[3]bb。

TgtFileSuffix String bb

当TgtType设置为jpg、png、pdf时,此参数才生效。

转换后的文件名称后缀,可以是英文、数字、横划线和下划线,且长度不超过256个字符。其中def为保留字,表示采用默认的后缀名。

通过设置TgtFilePrefix和TgtFileSuffix,可以实现自定义转换后的文件名称。

如果TgtType设置为jpg,TgtFilePrefix和TgtFileSuffix设置不同时,目标文件的名称规则如下:

  • 当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开始。如果TgtFilePrefix为aa,TgtFileSuffix为bb,且转换后的文件有3页,则所有的目标文件为aa[1]bb、aa[2]bb、aa[3]bb。

TgtFilePages String 1, 2, 100

当TgtType设置为jpg、png、pdf时,此参数才生效。

转换后输出指定文件页数,最多指定100个页数,如果超过100页,请分多次转换进行提交,默认输出所有页。例如当TgtFilePages设置为"1, 2, 100"时,只会输出第1、2、100页到目标位置。

FitToPagesTall Boolean false

当TgtType设置为pdf时,此参数才生效。

表格文档转换为pdf时,将行全部输出到一页,默认值为false。

FitToPagesWide Boolean false

当TgtType设置为pdf时,此参数才生效。

表格文件转pdf时,将列全部输出在一页,默认值为false。

IdempotentToken String d1fdd246-e187-11e8-9f32-f2801f1b9fd1

幂等标识,建议使用UUID格式。不同请求请生成独立的幂等标识。幂等标识的有效期约为43200秒,但不建议复用同一个幂等标识。

当传入幂等标识时,如果两次请求完全一致(包括IdempotentToken本身),则会返回相同结果,即返回相同的TaskId。该功能用于避免多次执行同样的任务,消耗额外计算资源。

说明 当出现ServiceUnavailable等HTTP状态码为5xx的异常时,IdempotentToken可能失效。此时可能会重复创建该任务。
PdfVector Boolean false

当PDF转换为VECTOR时,是否使用向量模式,默认值为false。包括如下选项:

  • true:使用向量模式,预览效果比较清晰,但是转换耗时较长。
  • false:使用图片模式,预览效果一般,但是转换耗时较短。
Hidecomments Boolean false

当WORD、PPT转换为VECTOR、JPG、PNG时,是否隐藏批注和应用修订,默认值为false。包括如下选项:

  • true:隐藏批注和应用修订。
  • false:显示批注和修订。
DisplayDpi Integer 1024

当源数据类型转换为JPG、PNG时,此参数才生效。

图片分辨率,单位为PPI,取值范围为96~2048。

MNS通知

请求参数中如果设置了NotifyTopicName和NotifyEndpoint支持MNS事件通知,则智能媒体管理会为您返回异步通知,例如文档转换的页数,通知的消息格式为:

  • 转换成功消息
    
    {
        "events": [
            {
                "eventName": "FormatConvertJob:JobFinished",
                "eventSource": "acs:imm",
                "eventTime": "2020-11-11T06:51:17.35Z",
                "imm": {
                    "taskId": "formatconvert-00bec802-073a-4b61-ba3b-39bc2fdd169b",
                    "code": "NoError",
                    "pageCount": "32",
                    "percent": "100"
                }
            }
        ]
    }
    
  • 转换失败消息

{
    "events": [
        {
            "eventName": "FormatConvertJob:JobError",
            "eventSource": "acs:imm",
            "eventTime": "2020-11-11T06:51:17.35Z",
            "imm": {
                "taskId": "formatconvert-00bec802-073a-4b61-ba3b-39bc2fdd169b",
                "code": "FailedToDownloadSrcFile",
                "pageCount": "0",
                "percent": "0"
            }
        }
    ]
}

返回数据

名称 类型 示例值 描述
CreateTime String 2020-11-11T06:51:17.5Z

任务的创建时间。

Percent Integer 0

任务进度的百分比。当前只有0和100两个结果。

只有当转换成功时,此参数的返回值才为100,其他情况均为0。

RequestId String FF3B7D81-66AE-47E0-BF69-157DCF187514

当次请求的Request ID。

Status String Running

任务运行状态。包括如下选项:

  • Running:任务运行中。
  • Finished:任务执行完成,转换成功。
  • Failed:任务执行完成,转换失败。
TaskId String formatconvert-00bec802-073a-4b61-ba3b-39bc2fdd169b

任务ID。

异步文档格式转换任务的TaskId可以通过智能媒体管理控制台对应项目的任务查询页签获取。

TgtLoc String oss://bucket1/imm-format-convert-tgt/session123/

输出目标文件的位置,和请求参数中的TgtUri相同。

示例

请求示例

http(s)://[Endpoint]/?Action=CreateOfficeConversionTask
&Project=immdoctest
&SrcUri=oss://bucket1/object
&TgtUri=oss://bucket1/imm-format-convert-tgt/session123/
&<公共请求参数>

正常返回示例

XML格式

<Status>Running</Status>
<TaskId>formatconvert-00bec802-073a-4b61-ba3b-39bc2fdd169b</TaskId>
<RequestId>FF3B7D81-66AE-47E0-BF69-157DCF187514</RequestId>
<Percent>0</Percent>
<CreateTime>2020-11-11T06:51:17.5Z</CreateTime>
<TgtLoc>oss://bucket1/imm-format-convert-tgt/session123/</TgtLoc>

JSON格式

{
    "Status": "Running",
    "TaskId": "formatconvert-00bec802-073a-4b61-ba3b-39bc2fdd169b",
    "RequestId": "FF3B7D81-66AE-47E0-BF69-157DCF187514",
    "Percent": 0,
    "CreateTime": "2020-11-11T06:51:17.5Z",
    "TgtLoc": "oss://bucket1/imm-format-convert-tgt/session123/"
}

相关文档