调用转换服务需要涉及三个 api 和两个 token,以下是使用流程说明:
1.使用 sdktoken 调用 发起文档转换 api,发起文档转换任务并得到 taskuuid
2.使用 sdktoken 和 taskuuid 调用 生成 Task Token api,得到 tasktoken
3.使用 tasktoken 和 taskuuid 调用 查询任务转换进度 api,查询任务进度
4.目前转换服务支持的海外区域包括 us-sv / sg / in-mum,对应 美国硅谷 / 新加坡 / 印度孟买,请根据实际需要选择
由于 sdktoken 的权限过大,我们不建议将 sdktoken 暴露到前端,建议使用 sdktoken 签出 tasktoken,将 tasktoken 传到前端使用,只有拥有 tasktoken 的用户才能查询对应的任务进度。
发起转换以及签出 tasktoken 建议都在后端进行
目前转换服务仅支持 190 页以内的文档。更多页文档请等待后续的功能更新
POST
发起文档转换在调用以下 api 之前,请确保您已经在 console 平台上开通了
文档转网页
或是文档转图片
服务
https://api.netless.link/v5/services/conversion/tasks
当请求中的 type 为 dynamic 时将调用 文档转网页(动态文档转换)服务,当 type 为 static 时将调用 文档转图片(静态文档转换)服务,请确保调用时对应服务已开通,否则 api 将会报错
文档转网页服务是将 ppt 转换为网页元素进行展示,但是由于部分动画效果无法使用 dom 实现(比如切页动画等效果),同时渲染时如果内容过于复杂会导致卡顿,因此我们额外提供了 canvas 版本的 ppt 转换(转换时 canvasVersion=true
)。
相对于非 canvas 转换,canvas 版本的转换支持了切页动画,优化了渲染效果和性能,但是转换速度会降低。目前正在进行转换速度优化。
目前设置 canvasVersion=true
的转换结果同时支持使用 白板 SDK 渲染为 html dom 版本的页面(无法展示切页动画);或是通过 fastboard SDK 来渲染为 canvas 版本的页面(支持切页动画)。
但是 canvasVersion=false
或者是未设置该参数的情况下只能使用 白板 SDK 渲染为 html dom 版本的页面, fastboard SDK无法读取该任务数据。
Key | 是否必填 | 类型 | 备注 |
---|---|---|---|
token | required |
string |
SDK Token(只读以上权限) |
region | required |
string |
数据中心 ID |
Key | 是否必填 | 类型 | 备注 |
---|---|---|---|
resource | required |
string |
转换任务源文件 url |
type | required |
string |
转换任务类型,枚举:dynamic, static |
preview | optional |
boolean |
是否需要生成预览图,默认为 false |
scale | optional |
number |
图片缩放比例,取值 0.1 到 3 之间的范围,默认为 1.2 |
outputFormat | optional |
string |
输出图片格式,默认为 png,可选参数为 png/jpg/jpeg/webp |
pack | optional |
boolean |
是否要生成资源包 |
canvasVersion | optional |
boolean |
是否生成 canvas 版本 ppt 所需的资源,默认为 false |
只有动态文档转换支持预览图功能,即 type == "dynamic" 时,同时生成预览图需要消耗较长时间,请根据业务需要选择
只有静态文档转换支持缩放功能,即 type == "static" 时,不传为默认值。该值会改变生成的图片大小
只有静态文档转换支持自定义输出格式,即 type == "static" 时,不传为 png,jpg 与 jpeg 输出格式都为 jpeg
只有静态文档转换支持 pack 参数,即 type == "static" 时,不传为 false,如果为 true 那么会在图片资源的上一级目录下生成一个 {uuid}.zip 的资源包,打包了所有图片。动态转换默认会生成 zip 资源包
canvasVersion 为 true 时会延长转换时间,如果没有使用 canvas 版本的 ppt 时请勿设置
{
"uuid": "2fa009xxxxxxxxxxxxxxxxxca93da2ad", // task uuid
"type": "dynamic", // task 类型,枚举:dynamic, static
"status": "Waiting" // task 状态,枚举:Waiting, Converting, Finished, Fail
}
GET
查询任务转换进度 https://api.netless.link/v5/services/conversion/tasks/{uuid}
Key | 是否必填 | 类型 | 备注 |
---|---|---|---|
token | required |
string |
Task Token |
region | required |
string |
数据中心 ID |
Key | 是否必填 | 类型 | 备注 |
---|---|---|---|
uuid | required |
string |
Task uuid |
Key | 是否必填 | 类型 | 备注 |
---|---|---|---|
type | required |
string |
转换任务类型,枚举:dynamic, static |
{
"uuid": "2fa009xxxxxxxxxxxxxxxxxca93da2ad", // task uuid
"type": "dynamic", // task 类型,枚举:dynamic, static
"status": "Waiting", // task 状态,枚举:Waiting, Converting, Finished, Fail
"failedReason": "", // 任务失败后的原因
"progress": {
"totalPageSize": 10, // 转换文档总页数
"convertedPageSize": 3, // 已经转换完成的页数
"convertedPercentage": 30, // 转换进度百分比
"convertedFileList": [{ // 转换结果列表
"width": 1024, // 当页跨度
"height": 960, // 当页高度
"conversionFileUrl": "xxxx://xxxx.xxx.xx/xxxx.xxx", // 转换结果文件地址
"preview": "xxxx://xxxx.xxx.xx/xxxx.xxx", // 预览图地址,当发起转换时 body 参数 preview 为 true 且 type 为 dynamic 时该字段才会存在
},{...}],
"currentStep": "Extracting" // 当前转换任务步骤,只有 type == dynamic 时才有该字段
}
}
由于动态转换步骤较多,我们添加了当前步骤字段,用于表示任务进度,可枚举值有 "Extracting"(资源提取) | "Packaging"(资源打包) | "GeneratingPreview"(生成预览图) | "MediaTranscode"(媒体转码)
在使用https://api.netless.link/v5/services/conversion/tasks
新建转换任务时可能遇见的异常情况:
在PPT中查找不满足条件的svg文件并手动替换,查找方法如下
1. 解压ppt
unzip ./ppt名字.pptx
如果已经在此目录解压过 需要输入 A
并按下回车键继续
ppt/media
中查找DOCTYPE
筛选出的svg就是不支持的文件ppt
文件夹中查找第2步找到svg图片的名字, 查看文件名并对比
slide1.xml.rels
代表第一页ppt中被使用slide2.xml.rels
代表第二页ppt中被使用slideLayout1.xml.rels
代表第一页板式中(Layout)被使用masterMaster1.xml.rels
代表第一个母版中(Master)被使用