文档转换服务

Agora 互动白板提供文档转换服务，支持将 PPT 和 PPTX 格式的文件转换成动态 HTML 网页，转换后的网页可直接访问或作为演示资料在互动白板中展示。

功能概述

文档转换是指将用 Microsoft Office 编辑的 PPT 和 PPTX 格式的文件，转换成 HTML 网页。转换后的文件会保留源文件里的动画效果。

新旧版本对比

新版本文档转换采用自研引擎，相较于旧版文档转换服务，有以下优势：

• 支持独立接入。新版本文档转换服务不再与互动白板绑定，支持接入第三方白板类产品。

• 更快的转换速度。转换速度提升 200% ~ 400%。

• 更强的内容解析能力。不仅支持解析旧版转换服务无法解析的内容，还支持解析更多动画特效、滤镜等效果，理论上可以解析所有 PPTX 文档内容。

• 更高的稳定性。解决了部分文档在原有的转换服务转换失败的问题。

• 新功能。支持用户暂停进行中的任务和调整任务优先级。

但目前新版文档转换仍有部分限制：

• 新版本文档转换服务生成的转换任务 uuid 无法调用旧版本进行查询进度，同时旧版本文档转换服务生成的 uuid 也无法通过新版查询进度，两者相互独立。如果想通过新版本文档转换服务查询旧版本转换服务进度请提交工单联系技术支持。

• 新版本文档转换服务暂时不支持文档转图片。如有文档转图片需求，请参考旧版文档转换服务 API。

• 新版本文档转换服务暂时不支持资源包功能，但资源路径固定，用户可以自行下载。

注意事项

使用新版文档转换服务，你需要注意：

• 暂不支持 WPS 格式的文件转换。即使将 WPS 转成 PPTX 后再进行文件转换，也不能保证成功解析。

• 如果转换结果字体缺失，可以使用 SDK 中的自定义字体功能，或者提交工单联系技术支持。

• 转换结果同时支持使用 Fastboard SDK 、 @netless/slide 与 @netless/projector-plugin 渲染为 canvas 版本的页面，几个方案不同点在于：

  • Fastboard SDK 是互动白板多窗口场景下的文档转换渲染方案。

  • @netless/slide 是纯净的文档转换渲染依赖，不包含互动白板、状态同步等内容。该方案需要你自己编写事件同步、状态保存等额外的代码以实现多人同步的效果，适用于单独使用 PPT 的场景。

  • @netless/projector-plugin 是基于 @netless/slide 开发的互动白板 SDK 的插件，支持状态同步，但是只能在单窗口场景下工作。

前提条件

使用互动白板文档转换服务前，你需要先完成以下准备工作。

开通第三方云存储账号

Agora 互动白板使用第三方云存储服务存储转换后的文件。因此，使用 Agora 互动白板文档转换服务前，请确保你已开通第三方云存储服务。

开启文档转换服务

参考以下步骤在 Agora 控制台开启互动白板文档转换服务并添加存储配置：

1. 进入 Agora 控制台的项目管理页面，选择已开通互动白板服务的项目，点击编辑。

2. 在编辑项目页面，找到白板，点击配置。

3. 在配套服务下，选择数据中心，点击配置。该数据中心必须与你调用创建房间 API 时在 region 字段中填入的数据中心一致；否则，服务配置不生效。
   

4. 在服务配置下，找到文档转网页，选择已启用。新版本文档转图片功能正在研发中，如有文档转图片需求，请参考旧版文档转换服务概述。
   

5. 设置存储空间：

   • 点击存储方框右侧的箭头，在下拉列表中选择你已配置的第三方存储空间。
   • 点击创建，新增一个存储空间配置。你需要填写以下信息：
     • 名称：（必填）存储空间的名称。
     • 供应商：（必填）第三方云存储服务的供应商。
     • 区域：（必填）创建 Bucket 时指定的数据中心所在区域。
     • accessKey：（必填）存储服务供应商提供的访问密钥中的 Access Key，用于识别访问者的身份。
     • secretKey：（必填）存储服务供应商提供的访问密钥中的 Secret Key，用于验证签名的密钥。
     • bucket：（必填）Bucket 的名称。
     • 存储路径：资源在 Bucket 中的存放路径，默认为根目录。
     • 外链域名：对外服务的访问域名。如果使用七牛云 OSS，该字段为必填，否则 Agora 将无法访问该存储服务内的资源。该字段必须包含协议头，比如 https:// 或 http://。
   • 要获取第三方存储空间的配置信息，请参考对应的云存储服务供应商的官方文档。
   • 第三方存储空间应开启公共读或更高权限，以确保你的 app 客户端可以访问其中的文件。

6. 点击保存，仔细阅读弹窗提示后点击确定。

上传文件

发起文档转换任务前，你需要将待转换的文档上传至第三方云存储空间或你自己的 Nginx 服务器，生成一个 Agora 互动白板服务可访问 URL 地址，确保 Agora 互动白板服务可通过该 URL 地址访问待转换的文档。

使用文档转换服务

文档转换服务由 Agora 互动白板服务端提供，需要由你的业务服务端根据 app 客户端的需求，调用 RESTful API 向互动白板服务端发起文档转换请求，如下图所示：

• 调用 RESTful API 发起文档转换任务时，你需要传入待转换文件的 URL 地址等参数。详见发起文档转换 API。
• 调用 RESTful API 查询转换任务进度时，你需要传入转换任务的 UUID 和用转换任务 UUID 生成的 Task Token。详见查询文档转换任务进度 API。
• 建议你设计轮询机制定时调用查询转换任务进度 API，以实时获取转换任务的状态。