Projector 是我们新推出的高速文档转换服务，相对于原有的动态文档转换服务，有以下优势：
- Projector 的转换速度提升了 200% ~ 400%
- 通过自研引擎解决了部分文档在原有的转换服务转换失败的问题
- 提升了转换内容的准确性，可以解析原有的转换任务无法解析的内容
- 可以支持用户停止进行中的任务和调整任务优先级
- 支持更多动画特效、滤镜等效果的解析
- 在自研引擎的支持下现在可以解析所有的 pptx 文档内容，理论上可以完美还原
但是目前 Projector API 仍有部分限制：
- Projector API 生成的转换任务 uuid 无法调用旧版本进行查询进度，同时旧版本文档转换服务生成的 uuid 也无法通过 Projector API查询进度，两者相互独立。如果想通过 Projector API 查询已有的转换服务进度请联系我们
- Projector API 暂时不支持资源包功能，但是资源路径固定，用户可以自行下载
- 虽然 Projector API 文档转网页服务支持 ppt 与 pptx 格式，但是由于 ppt 格式本身问题，仍然需要在后端转换为 pptx 进行解析，该过程仍有一定的失败率，建议直接使用 pptx 格式的文档
¶ Projector API 使用说明
调用 Projector 服务需要涉及三个 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 的用户才能查询对应的任务进度。
转换结果同时支持使用 fastboard SDK 、 @netless/slide 与 @netless/projector-plugin 来渲染为 canvas 版本的页面（支持切页动画），几个方案不同点在于：
- fastboard SDK 是白板多窗口场景下的文档转换渲染方案。
- @netless/slide 是纯净的文档转换渲染依赖，不包含白板、状态同步等等内容。
- @netless/projector-plugin 是基于 @netless/slide 开发的 white sdk 的插件，支持状态同步，但是只能在单窗口场景下工作
如果你只想单独使用 ppt，那么请使用
@netless/slide, 但是这需要你自己编写事件同步、状态保存等额外的代码以实现多人同步的效果；而fastboard SDK与@netless/projector-plugin基于白板，已经实现了 ppt 的多人同步，且不需要额外开发，但是与白板内容强绑定
由于 sdktoken 的权限过大，我们不建议将 sdktoken 暴露到前端，建议使用 sdktoken 签出 tasktoken，将 tasktoken 传到前端使用，只有拥有 tasktoken 的用户才能查询对应的任务进度。
发起转换以及签出 tasktoken 建议都在后端进行
旧版本的 taskUUID 无法在 Projector api 进行查询任务结果等操作，但同样的账户token新旧版本是互通的
以下所有API region参数和header请求头参数，目前只支持cn-hz和us-sv两个参数，其他地区我们在逐步上线中
¶ POST 发起文档转换
在调用以下 api 之前，请确保您已经在 console 平台上开通了
文档转网页或是文档转图片服务
https://api.netless.link/v5/projector/tasks
¶ Request
¶ Headers
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| token | required |
string |
SDK Token（只读以上权限） |
| region | required |
string |
数据中心 ID |
¶ Body Parameters
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| resource | required |
string |
转换任务源文件 url |
| type | optional |
string |
"static" 或 "dynamic", 如果不传默认为 "dynamic" |
| scale | optional |
number |
仅type="static"时生效，文档转图片时指定的清晰度，取值 0.1 到 3 之间，默认为 1.2 |
| outputFormat | optional |
string |
仅type="static"时生效，文档转图片时指定的输出图片格式，可选值为 png, jpg, jpeg |
| preview | optional |
boolean |
是否生成预览图，仅type="dynamic"时生效 |
| webhookEndpoint | optional |
string |
webhook 回调地址 |
| webhookRetry | optional |
number |
webhook 回调失败重试次数(默认3，最大10) |
| imageCompressionLevel | optional |
enum |
仅type="dynamic"时输出图片压缩等级(默认0，最大4) |
指定imageCompressionLevel参数可以压缩图片输出的大小，0为不压缩 4为压缩等级最高。可用于在弱网环境下改善转换后的PPT首次加载时间. 压缩等级太高会影响PPT的展示效果,如无必要尽量不要使用。
点此查看imageCompressionLevel参数详细说明
压缩等级详细参数:
0: 使用原图 质量最好
1: 使用调色盘限制最大颜色数量为256, 质量100
2: 使用调色盘限制最大颜色数量为192, 质量80
3: 使用调色盘限制最大颜色数量为128, 质量60
4: 使用调色盘限制最大颜色数量为64, 质量40
图片最后的大小一般与压缩等级的升高而变小,但有极少的情况压缩后图片反而会变大
压缩等级对比图:
第一张图为4K图像转换为ppt画布大小, 第二张图为RGB色彩图.因色彩较多,能准确看出压缩前后质量变化,但并不具有代表性,正常PPT中很少出现.
-
等级0: (689KB, 291KB)
-
等级1: (533KB, 220KB)
-
等级2: (514KB, 219KB)
-
等级3: (217KB, 101KB)
-
等级4: (217KB, 101KB)
¶ 201: Created
{
"uuid": "2fa009xxxxxxxxxxxxxxxxxca93da2ad", // task uuid
"status": "Waiting" // 返回任务提交成功是否
}
¶ GET 查询任务转换进度
https://api.netless.link/v5/projector/tasks/{uuid}
¶ Request
¶ Headers
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| token | required |
string |
Task Token |
| region | required |
string |
数据中心 ID |
¶ Path Parameters
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| uuid | required |
string |
Task uuid |
¶ Response
¶ 200: Ok
{
"uuid":"da4c1b9ae************92af4ef22b8",
"status":"Converting", // task 状态，枚举：Waiting, Converting, Finished, Fail
"type": "dynamic", // 枚举，"dynamic" | "static"
"convertedPercentage":100, // 任务进度，100则为完成
"prefix":"https://xxxx.com/dynamicConvert" // 转换结果文件地址前缀路径
"pageCount": 10, // 文档页数，当文件转换失败时没有该字段
"previews": {
"1": "https://xxxx.xx.xx/1.xxx",
"2": "https://xxxx.xx.xx/2.xxx"
...
}, // 文档预览图地址，当文件转换失败时没有该字段，当发起转换任务时 preview 为 true 且 type 为 dynamic 时才会存在，每页会有一张预览图
"note": "https://xxx.xx.xx/note.json"， // 文档提取出的备注内容，只包含有备注的页面
"images": {
"1": {
"width": 720,
"height": 1080,
"url": "https://xxxx.xx.xx/1.xxx",
},
"2": {
"width": 720,
"height": 1080,
"url": "https://xxxx.xx.xx/2.xxx",
}
}, // 文档转图片结果地址，当文件转换失败时没有该字段，当发起转换任务时 type 为 static 时 才会存在，每页有一张图片
"errorCode": "20xxxxx", // 错误码，当任务转换失败时会存在
"errorMessage": "xxx", // 错误，当任务转换失败时会存在
}
查询转换任务进度接口仅支持查询七天内创建的转换任务。
为了避免转换状态信息或结果丢失，声网推荐你在转换完毕或者失败后，及时自行存储任务信息，或通过 Webhook 回调获取任务状态更变的通知。
¶ GET 列出 App 下所有任务
https://api.netless.link/v5/projector/tasks
¶ Request
¶ Headers
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| token | required |
string |
SDK Token（只读以上权限） |
| region | required |
string |
数据中心 ID |
¶ Response
¶ 200: Ok
[
{
taskId: 'xxx', // 任务的task uuid
status: 1 // 1：任务在进行中；0：任务正在排队
},
{
....
}
]
¶ DELETE 取消任务
取消任务只能取消在排队中的任务，无法取消已经在进行中的任务 列出AppID下所有任务 返回的数据中 status 状态代表任务是否在进行中
https://api.netless.link/v5/projector/tasks/{uuid}
¶ Request
¶ Headers
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| token | required |
string |
SDK Token（只读以上权限） |
| region | required |
string |
数据中心 ID |
¶ Path Parameters
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| uuid | required |
string |
Task uuid |
¶ Response
¶ 200: Ok
{
taskId: 'xxx', // 任务的task uuid
success: true // 是否取消成功
}
¶ PUT 设置任务优先级
设置任务优先级只能将任务移动到排队的任务最前面或者最后面
https://api.netless.link/v5/projector/tasks/{uuid}/priority
¶ Path Parameters
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| uuid | required |
string |
Task uuid |
¶ Request
¶ Headers
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| token | required |
string |
SDK Token（只读以上权限） |
| region | required |
string |
数据中心 ID |
¶ Body Parameters
| Key | 是否必填 | 类型 | 备注 |
|---|---|---|---|
| priority | required |
string |
枚举，只能选择 highest 或 lowest |
¶ Response
¶ 200: Ok
{
uuid: 'xxx', // 任务的task uuid
success: true // 是否设置成功
}
¶ Projector Webhook 回调
1.webhook回调地址是 发起文档转换 api中webhookEndpoint参数决定，如果只传了webhookEndpoint不传webhookRetry，webhookRetry为默认3，最大次数不会超过10，即使传入的参数大于10也会被设置为10
2.响应以http状态码是否为200为准，正常返回为200.反之为失败. 返回内容会被忽略
3.回调webhook，有一定的概率重复回调，需要做好幂等处理
请求方式：POST
{
code: 0 ,// 错误码，成功为0
message: "success", // 错误消息。成功为success
data: {
"taskId": "da4c1b9ae************92af4ef22b8", // task uuid
"taskType": "dynamic_conversion", // 枚举，dynamic_conversion 或 static_conversion
"prefixUrl": "https://xxxx.com/dynamicConvert", // 转换结果文件地址前缀路
"pageCount": 10, // 文档页数，当文件转换失败时没有该字段
"previews": {
"1": "https://xxxx.xx.xx/1.png",
"2": "https://xxxx.xx.xx/2.png"
...
}, // 文档预览图地址，当文件转换失败时没有该字段，当发起转换任务时 preview 为 true 时才会存在，每页会有一张预览图
"images": {
"1": {
"width": 720,
"height": 1080,
"url": "https://xxxx.xx.xx/1.xxx",
},
"2": {
"width": 720,
"height": 1080,
"url": "https://xxxx.xx.xx/2.xxx",
}
}, // 文档转图片结果地址，当文件转换失败时没有该字段，当发起转换任务时 type 为 static 时 才会存在，每页有一张图片
"note": "https://xxx.xx.xx/note.json"， // 文档提取出的备注内容，只包含有备注的页面
"noticeTimestamp": 1231369699739 // 通知时间戳
}
}
¶ Projector API 异常错误码
以下异常为用户传入的文件、存储配置等可能造成的异常信息，如果用户得到的异常状态码无法在下方找到，即为内部错误，请将联系工作人员并将异常信息发给他们进行排查。
| 错误码 | 异常消息 | 说明 |
|---|---|---|
| 2010201 | unsupported file format | 用户传入了无法支持的文件格式(png jpg jpeg mp3 mp4等) |
| 2010202 | dynamic conversion only support pptx | 除无法支持的文件格式和 pptx 格式以外调用了动态转换 |
| 2010203 | resource invalid | 资源无效（请检查链接是否可以访问） |
| 2010204 | the number of tasks exceeds limit | 转换队列排队过多（请通过删除任务 api 删掉部分任务，或者等待之前的任务转换完成后再发起转换） |
| 2010605 | task not found | 未找到要查询的任务（查询任务参数是否正确） |
| 2011201 | task timeout | 任务超时 |
| 2010606 | team not found | 找不到用户信息（token 错误） |
| 2010607 | modify priority for running task is not allowed | 无法修改正在运行的任务优先级 |
| 2011301 | task not found | 传入的 taskid 查询不到任务 |
| 2030100 | download from OSS file failed | 源文件下载失败(检查文件是否已经上传) |
| 2030101 | unzip file failed, unsupported file in PPT | 不支持的PPT格式(检查是否能使用PowerPoint打开此文件) |
| 2030102 | can't find media file from unzip PPT | 解压后找不到媒体文件(检查ppt媒体文件位置,是否使用了外链,移动ppt后媒体是否能正常播放) |
| 2030200 | read xml file failed | 解压后的XML文件异常(可能是使用了非 PowerPoint 编辑导致) |
| 2030201 | formula resolve failed, please check animation of PPT | XML中的公式解析错误(检查或删除PPT内的动画重试) |
| 2030202 | unsupported formula type, please check animation of PPT | XML中的公式类型错误(检查或删除PPT内的动画重试) |
| 2040005 | task timeout | 图片转换任务超时（文档内的图片可能异常或者过大，联系工作人员定位） |
| 2050099 | unknown error | 未知的文档转图片异常(可能是使用了非 PowerPoint 编辑导致) |
| 2050100 | unsupported file type | 不支持的文件格式（动态转换仅支持 ppt 或 pptx） |
| 2050101 | file download failed | 源文件下载失败 |
| 2050102 | file is empty | 文件内容为空（本地打开检查文件是否有内容） |
| 2050107 | file url encode failed | 文件 url 编码失败（请检查文件路径是否正常） |
| 2050201 | init presentation parser failed | 初始化 ppt 解析异常(可能是使用了非 PowerPoint 编辑导致) |
| 2050299 | unknown parsing error | 未知的文档解析异常(可能是使用了非 PowerPoint 编辑导致) |
| 2050401. | generate preview failed | 预览图生成失败(可能是使用了非 PowerPoint 编辑导致) |
| 2060402 | fonts in the rules that are not provided | 找不到指定字体，请联系工作人员 |
| 2090304 | upload file to custom storage failed | 上传文件到用户存储失败（请检查存储配置是否正确） |
| 2090305 | not supported storage provider | 不支持的云存储服务商 |
| 2110099 | unknown error | 未知的文档转图片异常(可能是使用了非 PowerPoint 编辑导致) |
| 2110100 | unsupported file type | 用户传入了无法支持的文件格式（静态转换仅支持 ppt/pptx/doc/docx/pdf 格式） |
| 2110101 | download file failed | 文件下载失败（请检查文件地址是否有效） |
| 2110102 | file is empty | 文件内容为空（本地打开检查文件是否有内容） |
| 2110107 | file url encode failed | 文件 url 编码失败（请检查文件路径是否正常） |
| 2110108 | get file extension failed | 获取文件格式失败（请检查文件是否是仅直接修改了后缀名，本身仍是不支持的文件格式） |
| 2110201 | init presentation parser failed | 未知的ppt文档解析异常(可能是使用了非 PowerPoint 编辑导致) |
| 2110202 | init word parser failed | 未知的 doc 文档解析异常(可能是使用了非微软 Word 编辑导致) |
| 2120201 | file is empty | pdf文件内容为空（本地打开检查文件是否有内容） |
| 2120301 | download file failed | pdf文件下载失败（请检查文件地址是否有效） |