使用文档转换服务
本文介绍如何使用声网互动白板提供文档转换服务。
功能概述
声网互动白板支持以下两种文档转换服务，转换后的图片或网页可作为演示资料在互动白板中展示:
- 静态文档转换：将 PPT、PPTX、DOC、DOCX 和 PDF 格式（以
%PDF开头）的文件转换成静态图片，简称为“文档转图片”。 - 动态文档转换：将 PPT 和 PPTX 的文件转换为动态 HTML 网页，简称为“文档转网页”。
前提条件
使用互动白板文档转换服务前，你需要先参考开启互动白板配套服务完成以下配置：
- 配置互动白板数据中心
- 启用文档转图片或文档转网页服务
- 开通并配置第三方云存储
实现文档转换
下图展示了使用文档转换服务的基本流程：
上传文件
发起文档转换任务前，你需要将待转换的文档上传至第三方云存储空间或你自己的 Nginx 服务器，生成一个声网互动白板服务可访问 URL 地址，确保可通过该 URL 地址访问待转换的文档。
使用文档转换服务
文档转换服务由声网互动白板服务端提供，需要由你的业务服务端根据 App 客户端的需求，调用 RESTful API 向互动白板服务端发起文档转换请求。
声网推荐你在阅读本节的同时在新标签页打开文档转换服务端 API 参考以获得更好的开发体验：
- 详细的 API 参数说明、调用示例和调用注意事项
- 使用 API 文档右侧的“Try it”功能快捷调用 RESTful API
- 一键生成不同语言的 RESTful API 调用代码
1. 发起文档转换
发起文档转换任务需要传入待转换文件的 URL 地址、转换任务类型等参数，详见发起文档转换。以 cURL 为例：
curl --request POST \
--url https://api.netless.link/v5/projector/tasks \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'region: cn-hz' \
--header 'token: NETLESSSDK_YWs9xxxxxxM2MjRi' \
--data '{
"resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx",
"type": "dynamic",
"preview": true,
"webhookEndpoint": "https://example.com/agoracallback",
"webhookRetry": 3,
"imageCompressionLevel": 0
}'
成功调用该 API 后，响应包体中会返回本次文档转换任务的 UUID (uuid)，即文档转换任务的唯一标识符，用于后续生成 Task Token 以及在白板中展示转换后的文档。
2. 生成 Task Token
使用上一步中获得的文档转换任务 UUID 生成 Task Token，详见生成 Task Token。以 cURL 为例：
curl --request POST \
--url https://api.netless.link/v5/tokens/tasks/uuid \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'region: cn-hz' \
--header 'token: NETLESSSDK_YWs9xxxxxxM2MjRi' \
--data '{
"role": "string",
"lifespan": 36000,
"ak": "i1xxxxx_xxxx47"
}'
成功调用该 API 后，响应包体中会返回本次文档转换任务对应的 Task Token，用于后续调用其他转码服务端 API。
3. 查询文档转换任务进度
查询七天内创建的文档转换任务的进度需要传入步骤 1 中返回的任务 UUID，详见查询文档转换任务进度。以 cURL 为例：
声网建议你设计轮询机制定时调用查询文档转换任务进度 API，以实时获取转换任务的状态。
curl --request GET \
--url https://api.netless.link/v5/projector/tasks/uuid \
--header 'Accept: application/json' \
--header 'region: cn-hz' \
--header 'token: NETLESSSDK_YWs9xxxxxxM2MjRi' \
成功调用该 API 后，响应包体中会返回转换结果文件地址前缀路径 (prefixUrl)，用于后续展示转码后页面。
4. 按需调用其他 API
声网还提供了以下文档转换服务端端 API，你可以根据业务需要选择调用：
- 查询待文档转换任务：列出未完成转换的所有任务。
- 取消指定的文档转换任务：取消指定任务 UUID 对应的文档转换任务。
- 设置文档转换任务优先级：将待进行的指定文档转换任务移动至任务队列最前或最后面。
展示转码后文档
转换结果同时支持使用 Fastboard SDK 、@netless/slide 与 @netless/projector-plugin 渲染为 canvas 页面，几个方案不同点在于：
- Fastboard SDK 是互动白板多窗口场景下的文档转换渲染方案。
- @netless/slide 是纯净的文档转换渲染依赖，不包含互动白板、状态同步等内容。该方案需要你自己编写事件同步、状态保存等额外的代码以实现多人同步的效果，适用于单独使用 PPT 的场景。
- @netless/projector-plugin 是基于 @netless/slide 开发的互动白板 SDK 的插件，支持状态同步，但是只能在单窗口场景下工作。
参考信息
开发注意事项
-
使用静态文档转换服务，你需要注意：
- 源文件最好在 50 页以内，超过 100 页可能会出现转换超时。
- 源文件内包含的图片分辨率越高，转换速度越慢。
- 在 PPT、PPTX、DOC、DOCX、PDF 格式的源文件中，PDF 文件的转换结果最为准确。如果转换后的文件样式过于不准确，可以将源文件转成 PDF 格式后重新转换。
- 本功能基于 Aspose 实现，因此声网目前无法及时响应定制化需求。建议你在使用前先做充分的测试，如果不符合预期请使用三方转换服务。
- 暂不支持资源包功能，但资源路径固定，用户可以自行下载。
-
使用动态文档转换服务，你需要注意：
- 暂不支持 WPS 格式的文件转换。即使将 WPS 转成 PPTX 后再进行文件转换，也不能保证成功解析。
- 暂不支持资源包功能，但资源路径固定，用户可以自行下载。
- 如果转换结果出现了字体缺失现象，可以使用 SDK 中的自定义字体功能，或者联系技术支持。
- 由于 PPT 格式本身的问题，PPT 文件仍然需要在后端转换为 PPTX 进行解析，该过程仍有一定的失败率，建议直接使用 PPTX 格式的文档。
文档转换服务按 QPS 计费
QPS（Queries-Per-Second）指每秒查询率。文档转换服务的 QPS 默认值为 1，代表只能同时处理一个文档转换请求，即在前一个转换完成后才会进行第二个任务的转换。
如果默认的 QPS 无法满足你的需求，你可以联系联系销售，申请调整该项目的 QPS 配置并按 QPS 计费。QPS 计费方案细节详见文档转换服务按 QPS 计费。
文档转换 Webhook 回调
互动白板的消息通知服务可以在业务层维护一个实时同步的状态机，实现实时监听文档转换任务的进度和运行状态信息，详见Webhook 回调事件。