在教学场景中,有时我们会希望在房间中展示教案(如幻灯片、文档等)。这些教案通常是以 ppt、pptx、word、pdf 等格式存在的文件。为了将某个教案文件展示在房间中,需要进行如下操作。
oss,即对象存储服务(Object Storage Service)。它可以提供安全、高可靠、低成本的数据存储能力,可以创建、修改、上传、下载、删除对象。目前主流的云服务厂商都提供自己的 oss 服务(如阿里云的 oss、AWS 的 S3、七牛云的云存储)。
你需要先将教案文档文件上传到你的 oss,然后对公网暴露一个可访问的 URL 地址,确保该地址能被 Netless 服务器访问到。之后,该 URL 就可以在下一章节中发起文档转换任务了。
Netless 的文档转换服务只需要一个公网可访问的 URL 地址即可。理论上,你可以自己搭建一个 Nginx 服务器以代替 oss 服务,但我们不建议你这么做。目前主流云服务厂商提供的 oss 服务安全、可靠、低成本、免运维,何苦自己搭建 Nginx 服务器呢?
我们以阿里云为例,来创建 oss 服务(其他云服务平台大同小异。你可以阅读阿里云的官方文档,《开通OSS服务》、《创建存储空间》。
之后,需要为刚创建的 oss bucket 开启公共读权限,以确保 Netless 服务可以访问存储于此的教案文档文件 URL。
当然,根据你的业务逻辑和选择的云服务厂商的方案。你并非一定要通过将 bucket 设置成「公共读」。你也可以根据业务需求,使用其他方案,也是可以。只要能确保 Netless 服务有权通过 URL 访问教案文档文件即可。
Netless 文档转化任务会通过你提供的 URL,从源 oss 中读取你刚上传的教案文档文件,然后转化成图片或 HTML 文件,最后存储到目标 oss 中。
文档转换分为「转图片」和「转网页」两种,具体区别如下。
模式 | 支持格式 | 支持动画 | 产物 |
---|---|---|---|
转图片 | pptx、ppt、word、pdf | 不支持 | 图片 |
转网页 | pptx | 支持 | HTML |
在使用文档转换服务之前,需要配置目标 oss,用于存储转换后的文件。
目标 oss 也应该配置成公共读(或以上)的权限,以确保客户端 SDK 可以访问到它。此外,如果该 oss 与你的 Web 应用的域名不同,应该为配置适当的跨域设置。没有配置,或错误的配置跨域可能导致你的 Web 应用服务无法读取转换后的教案文档文件。
首先,进入 Netless 应用管理页面,找到你想配置的项目,点击「配置」按钮进入配置界面。
之后为「文档转图片」和「文档转网页」分别配置 oss。首先,点击「新增存储配置」。
之后选择 oss 的供应商(这里以阿里云为例)。
然后根据界面提示,填写 oss bucket 的配置项(其中的存储路径是资源存放于 bucket 中的路径,默认是根目录),最后点「启动服务」完成设置。
特别的,选择使用七牛云的存储服务时,需要额外配置一个外链域名的字段,否则 Netless 将无法访问该存储服务内的资源。
将其填入 Netless 控制台的这里。
之后,每当你需要转换教案文档文件时。你需要从源 oss 获取文档文件的 URL,然后调用 Netless 的服务端 API(具体参考《PPT 转换》)。
具体来说,你需要先创建一个转换任务。然后获取转换任务的 uuid
,并创建与之相伴的 taskToken
。然后用 uuid
和 taskToken
作为参数轮询该任务的状态。如果发现任务成功,则说明转换后的内容(图片或网页)已经存储到了目标 oss 中。如果发现任务失败,则走异常流程。
建议为你的轮询流程设计留一个超时逻辑。
如果用户为文档转图片或文档转网页服务选择了自定义的存储,那么文档转换生成的结果资源文件将会存放到用户配置的存储中,因此在资源上传的过程中有极低概率会因为网络原因导致上传失败;且前端 sdk 会从用户存储中读取资源,因此可能需要用户自行做资源下载的加速。
如果用户的自定义存储使用阿里云杭州区的 oss,那么我们可以通过内网进行资源上传,不会因为网络文档导致上传失败。(支持内网上传的存储区域后续会持续增加)
在转换成功后(参考《查询转换进度 | PPT 转换》,可以从服务端得到一个 JSON。其中,.progress.convertedFileList
是一个数组,用于描述转换后的文档的每一页的情况。
数组的每一个元素是形如如下的 object。
{
"width": 1024, // 当页宽度
"height": 960, // 当页高度
"conversionFileUrl": "xxxx://xxxx.xxx.xx/xxxx.xxx", // 转换结果文件地址
"preview": "xxxx://xxxx.xxx.xx/xxxx.xxx", // 可选,预览图地址,当发起转换时 body 参数 preview 为 true 且 type 为 dynamic 时该字段才会存在
}
我们可以将这个数组直接返回给客户端,也可以把它存储到数据库,等到客户端对业务服务器发起请求时,从数据库读取并返回给客户端。
在客户端收到这个数组后,将每一页的信息翻译成场景对象,并调用 Netless SDK 的方法插入到房间中即可。
{
name: "page-name-xxx",
ppt: {
src: conversionFileUrl, // 之前提到的对象中获取
preview: preview,
width: width,
height: height,
},
}
Netless 基于多场景,我们可以设计多页白板功能、PPT 演讲功能。具体请参考 《场景管理》。