40 lines
2.8 KiB
Markdown
40 lines
2.8 KiB
Markdown
# WPS365 智能表格（AirSheet）接口说明
|
||
|
||
## 当前情况
|
||
|
||
- **智能表格（AirSheet）** 在 open.wps.cn 开放平台申请的权限为 `kso.airsheet.readwrite`，但 **openapi.wps.cn 下目前没有可用的 AirSheet REST 接口**：
|
||
- `https://openapi.wps.cn/api/v1/openapi/airsheet/{fileId}/...` → 404
|
||
- `https://openapi.wps.cn/v7/airsheet/{fileId}/...` → 404
|
||
|
||
因此直接按「智能表格」调 AirSheet 读/写会报 **读取AirSheet数据失败、statusCode=404**。
|
||
|
||
## 代码中的处理
|
||
|
||
- **读**：`readAirSheetCells` 会依次尝试
|
||
1）AirSheet 路径 → 2）**KSheet（在线表格）路径**（同一 `fileId` 当作 `file_token`）→ 3）v7 AirSheet。
|
||
若都 404，会抛出带说明的异常。
|
||
- **写**：`updateAirSheetCells` 同样会先试 AirSheet，再回退到 **KSheet 写入**，再试 v7。
|
||
|
||
即：当 AirSheet 接口 404 时，会自动用同一 ID 试 **在线表格（KSheet）** 接口；若文档在 WPS 文件列表里是以 KSheet 形式存在的，有可能用 KSheet 读/写成功。
|
||
|
||
## 建议用法（避免 404）
|
||
|
||
1. **优先用「文件列表」返回的 file_token 调 KSheet 接口**
|
||
- 调用 `GET /jarvis/wps365/files`（或等价的文件列表接口），拿到目标文档的 **file_token**。
|
||
- 用该 **file_token** 调用 **KSheet** 读/写接口，不要用浏览器地址栏或分享链接里的 ID 当作 file_token：
|
||
- 读：`GET /jarvis/wps365/readCells?userId=xxx&fileToken=文件列表返回的file_token&sheetIdx=0&range=A1:B5`
|
||
- 写：`POST /jarvis/wps365/updateCells`，body 里 `fileToken` 填文件列表返回的 file_token。
|
||
- 这样即使用户创建的是「智能表格」，只要在文件列表里存在且后端用 KSheet 能访问，就可正常读/写。
|
||
|
||
2. **确认文档来源**
|
||
- 若文档是在 **金山文档（kdocs.cn）** 创建的，当前项目用的是 **open.wps.cn（WPS365）** 的 OAuth 与 API，token 不能直接访问金山文档。
|
||
- 要在后端读/写金山文档里的表格，需要接 **金山文档开放平台（developer.kdocs.cn）** 的 KSheet 服务端 API，并使用该平台的鉴权方式。
|
||
|
||
3. **若必须用「智能表格」且仅支持 AirScript**
|
||
- 若官方仅提供通过 **AirScript（脚本）** 操作智能表格（例如 `POST https://www.kdocs.cn/api/v3/ide/file/:file_id/script/:script_id/sync_task`），则需在表格内编写脚本，后端只调该脚本接口，而不是直接调 REST 读单元格。
|
||
|
||
## 小结
|
||
|
||
- **404 原因**：openapi.wps.cn 下当前没有可用的智能表格（AirSheet）REST 读/写接口。
|
||
- **可行方案**：用 **文件列表接口拿 file_token**，用 **KSheet 读/写接口**（readCells / updateCells）操作该文档；若文档在金山文档，需改用金山文档开放平台的 API。
|