采用异步请求方式进行文档(例如Office文档)格式的转换,执行完成后返回TaskId。
接口说明
注意事项
执行完成后,使用GetOfficeConversionTask接口查询返回的TaskId,可以查看任务执行结果。任务执行信息只保存7天,请及时获取任务执行信息,您也可以使用通知机制,传入NotifyTopicName和NotifyEndpoint,及时通知任务执行信息。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
Project | string | 是 | 项目名称。 | immdoctest |
SrcUri | string | 是 | 源数据的存储位置。 OSS地址规则为 | oss://bucket1/object |
TgtType | string | 否 | 转换输出的目标文件类型。包括如下选项:
| vector |
TgtUri | string | 是 | 转换后输出内容的目标位置,建议TgtUri和SrcUri在同一个OSS Bucket中,便于权限管理。 生成的目标文件会持久化保存,推荐设置为OSS Bucket下的/imm-format-convert-tgt/${name}路径,便于维护管理。 您可以主动删除转换后的目标文件,如果不主动删除则会长期保留以备使用,但是会占用存储空间。如果希望自动的删除目标文件,您也可以在/imm-format-convert-tgt前缀下配置OSS的生命周期。 | oss://bucket1/imm-format-convert-tgt/session123/ |
NotifyTopicName | string | 否 | 异步反向通知的TopicName。 | topic1 |
NotifyEndpoint | string | 否 | 异步反向通知的Endpoint,文档转换状态可以通过该Endpoint异步通知给调用者。使用此功能需要先开通MNS服务,新建topic和queue,并配置订阅关系。 说明MNS服务和智能媒体管理必须处于同一地域。 | http://1111111111.mns.cn-hangzhou.aliyuncs.com |
SrcType | string | 否 | 当OSS对象没有后缀名时,可以设置此参数。 源数据的后缀类型。默认根据OSS对象的后缀名确定源数据的类型。 | doc |
StartPage | long | 否 | 文档转换的起始页,默认值为1。 | 1 |
EndPage | long | 否 | 文档转换的结束页,默认值为200。如果需要转换所有页,设置此参数为-1。 | 10 |
MaxSheetRow | long | 否 | 表格文档转换的最大行数,默认值为1000。如果需要转换所有行,设置此参数为-1。 | 10 |
MaxSheetCol | long | 否 | 表格文档转换的最大列数,默认值为100。如果需要转换所有列,设置此参数为-1。 | 10 |
MaxSheetCount | long | 否 | 表格文档转换的最大Sheet数。如果需要转换所有Sheet,设置此参数为-1。 | 3 |
SheetOnePage | boolean | 否 | 当TgtType设置为pdf时,此参数才生效。 表格文档转换为pdf时,是否将Sheet的所有内容输出到一页。 | false |
ModelId | string | 否 | 模型ID。此参数暂不可用。 | 无 |
Password | string | 否 | 文档的打开密码。如果需要转换有密码的文档,请设置此参数。 | ******** |
TgtFilePrefix | string | 否 | 当TgtType设置为jpg、png、pdf时,此参数才生效。 转换后的文件名称前缀,可以是英文、数字、横划线和下划线,且长度不超过256个字符。 通过设置TgtFilePrefix和TgtFileSuffix,可以实现自定义转换后的文件名称。 如果TgtType设置为jpg,TgtFilePrefix和TgtFileSuffix设置不同时,目标文件的名称规则如下:
其中[x]表示多个目标文件,从1开始。如果TgtFilePrefix为aa,TgtFileSuffix为bb,且转换后的文件有3页,则所有的目标文件为aa[1]bb、aa[2]bb、aa[3]bb。 | aa |
TgtFileSuffix | string | 否 | 当TgtType设置为jpg、png、pdf时,此参数才生效。 转换后的文件名称后缀,可以是英文、数字、横划线和下划线,且长度不超过256个字符。其中def为保留字,表示采用默认的后缀名。 通过设置TgtFilePrefix和TgtFileSuffix,可以实现自定义转换后的文件名称。 如果TgtType设置为jpg,TgtFilePrefix和TgtFileSuffix设置不同时,目标文件的名称规则如下:
其中[x]表示多个目标文件,从1开始。如果TgtFilePrefix为aa,TgtFileSuffix为bb,且转换后的文件有3页,则所有的目标文件为aa[1]bb、aa[2]bb、aa[3]bb。 | bb |
TgtFilePages | string | 否 | 当TgtType设置为jpg、png、pdf时,此参数才生效。 转换后输出指定文件页数,最多指定100个页数,如果超过100页,请分多次转换进行提交,默认输出所有页。例如当TgtFilePages设置为"1, 2, 100"时,只会输出第1、2、100页到目标位置。 | 1, 2, 100 |
FitToPagesTall | boolean | 否 | 当TgtType设置为pdf时,此参数才生效。 表格文档转换为pdf时,将行全部输出到一页,默认值为false。 | false |
FitToPagesWide | boolean | 否 | 当TgtType设置为pdf时,此参数才生效。 表格文件转pdf时,将列全部输出在一页,默认值为false。 | false |
IdempotentToken | string | 否 | 幂等标识,建议使用UUID格式。不同请求请生成独立的幂等标识。幂等标识的有效期约为43200秒,但不建议复用同一个幂等标识。 当传入幂等标识时,如果两次请求完全一致(包括IdempotentToken本身),则会返回相同结果,即返回相同的TaskId。该功能用于避免多次执行同样的任务,消耗额外计算资源。 说明当出现ServiceUnavailable等HTTP状态码为5xx的异常时,IdempotentToken可能失效。此时可能会重复创建该任务。 | d1fdd246-e187-11e8-9f32-f2801f1b9fd1 |
PdfVector | boolean | 否 | 当PDF转换为VECTOR时,是否使用向量模式,默认值为false。包括如下选项:
| false |
Hidecomments | boolean | 否 | 当WORD、PPT转换为VECTOR、JPG、PNG时,是否隐藏批注和应用修订,默认值为false。包括如下选项:
| false |
DisplayDpi | integer | 否 | 当源数据类型转换为JPG、PNG时,此参数才生效。 图片分辨率,默认值为96,单位为PPI,取值范围为96~2048。 | 1024 |
UserData | string | 否 | 用户自定义数据,在mns通知中原样返回。 | {"fileid": "123"} |
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"
}
}
]
}
返回参数
示例
正常返回示例
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/"
}
错误码
访问错误中心查看更多错误码。