271 lines
7.6 KiB
Markdown
271 lines
7.6 KiB
Markdown
# WPS365 在线表格API集成使用说明
|
||
|
||
## 概述
|
||
|
||
本功能实现了WPS365在线表格（KSheet）的完整API集成，支持用户授权、文档查看和编辑等功能。
|
||
|
||
## 功能特性
|
||
|
||
1. **OAuth用户授权**：支持WPS365标准的OAuth 2.0授权流程
|
||
2. **Token管理**：自动保存和管理访问令牌，支持Token刷新
|
||
3. **文件管理**：获取文件列表、文件信息
|
||
4. **工作表管理**：获取工作表列表、创建数据表
|
||
5. **单元格编辑**：支持读取和更新单元格数据，支持批量更新
|
||
|
||
## 配置说明
|
||
|
||
### 1. 在WPS365开放平台注册应用
|
||
|
||
1. 访问 [WPS365开放平台](https://open.wps.cn/)
|
||
2. 注册成为服务商并创建应用
|
||
3. 获取 `app_id` 和 `app_key`
|
||
4. 配置授权回调地址（需要与配置文件中的 `redirect-uri` 一致）
|
||
|
||
### 1.1 配置应用权限（重要！）
|
||
|
||
在WPS365开放平台的应用配置中，需要确保开启以下权限：
|
||
|
||
#### 基础权限
|
||
- **文件读取权限** (`file.read` 或 `file.readwrite`)
|
||
- **用户信息权限** (`user.info`)
|
||
|
||
#### 在线表格（KSheet）相关权限
|
||
根据图片中的应用能力配置页面，如果需要读取在线表格内容，建议：
|
||
|
||
1. **进入"应用能力"配置页面**
|
||
- 在左侧导航栏选择"应用能力" > "应用能力"
|
||
|
||
2. **确保相关能力已开启**
|
||
- 虽然图片中显示的是"多维表格"插件相关能力，但读取在线表格内容主要依赖：
|
||
- **文件读取权限**（在"权限管理"中配置）
|
||
- **API调用权限**（确保应用有调用OpenAPI的权限）
|
||
|
||
3. **权限管理配置**
|
||
- 进入"开发配置" > "权限管理"
|
||
- 确保添加了以下权限：
|
||
- `ksheet:read` - 读取在线表格数据
|
||
- `ksheet:write` - 写入在线表格数据（如果需要编辑）
|
||
- `file:read` - 读取文件
|
||
- `file:write` - 写入文件（如果需要编辑）
|
||
|
||
4. **事件与回调配置**
|
||
- 进入"开发配置" > "事件与回调"
|
||
- 配置回调地址：`https://your-domain.com/wps365-callback`
|
||
- 确保回调地址验证通过（支持GET和POST请求）
|
||
|
||
### 2. 更新配置文件
|
||
|
||
编辑 `application-dev.yml`（或对应的环境配置文件），添加WPS365配置：
|
||
|
||
```yaml
|
||
wps365:
|
||
# 应用ID（从WPS365开放平台获取）
|
||
app-id: YOUR_APP_ID
|
||
# 应用密钥（从WPS365开放平台获取）
|
||
app-key: YOUR_APP_KEY
|
||
# 授权回调地址（需要在WPS365开放平台配置）
|
||
# 注意：使用 /wps365-callback 路径，避免前端路由拦截
|
||
redirect-uri: https://your-domain.com/wps365-callback
|
||
# API基础地址（一般不需要修改）
|
||
api-base-url: https://open.wps.cn/api/v1
|
||
# OAuth授权地址（一般不需要修改）
|
||
oauth-url: https://open.wps.cn/oauth2/v1/authorize
|
||
# 获取Token地址（一般不需要修改）
|
||
token-url: https://open.wps.cn/oauth2/v1/token
|
||
# 刷新Token地址（一般不需要修改）
|
||
refresh-token-url: https://open.wps.cn/oauth2/v1/token
|
||
```
|
||
|
||
**重要提示**：
|
||
- 回调地址使用 `/wps365-callback` 而不是 `/jarvis/wps365/oauth/callback`
|
||
- 这样可以避免前端路由拦截，确保OAuth回调能正常访问
|
||
- 在WPS365开放平台配置时，只需配置域名（如：`jarvis.van333.cn`），回调路径会自动使用配置中的完整URL
|
||
|
||
## API接口说明
|
||
|
||
### 1. 获取授权URL
|
||
|
||
**接口**: `GET /jarvis/wps365/authUrl`
|
||
|
||
**参数**:
|
||
- `state` (可选): 状态参数，用于防止CSRF攻击
|
||
|
||
**返回**: 授权URL，用户需要访问此URL完成授权
|
||
|
||
**示例**:
|
||
```javascript
|
||
// 前端调用
|
||
import { getWPS365AuthUrl } from '@/api/jarvis/wps365'
|
||
|
||
const response = await getWPS365AuthUrl()
|
||
const authUrl = response.data
|
||
// 打开授权页面
|
||
window.open(authUrl, '_blank')
|
||
```
|
||
|
||
### 2. OAuth回调处理
|
||
|
||
**接口**: `GET /wps365-callback`
|
||
|
||
**参数**:
|
||
- `code`: 授权码（由WPS365回调时自动传入）
|
||
- `state`: 状态参数（可选）
|
||
- `error`: 错误码（授权失败时）
|
||
- `error_description`: 错误描述（授权失败时）
|
||
|
||
**说明**:
|
||
- 此接口处理WPS365的授权回调，自动获取并保存Token
|
||
- 返回HTML页面，显示授权结果
|
||
- 使用 `/wps365-callback` 路径避免前端路由拦截
|
||
- 授权成功后会显示成功页面，3秒后自动关闭窗口
|
||
|
||
### 3. 获取Token状态
|
||
|
||
**接口**: `GET /jarvis/wps365/tokenStatus`
|
||
|
||
**参数**:
|
||
- `userId`: 用户ID
|
||
|
||
**返回**: Token状态信息（是否授权、是否有效等）
|
||
|
||
### 4. 刷新Token
|
||
|
||
**接口**: `POST /jarvis/wps365/refreshToken`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"refreshToken": "refresh_token_value"
|
||
}
|
||
```
|
||
|
||
### 5. 获取用户信息
|
||
|
||
**接口**: `GET /jarvis/wps365/userInfo`
|
||
|
||
**参数**:
|
||
- `userId`: 用户ID
|
||
|
||
### 6. 获取文件列表
|
||
|
||
**接口**: `GET /jarvis/wps365/files`
|
||
|
||
**参数**:
|
||
- `userId`: 用户ID
|
||
- `page`: 页码（默认1）
|
||
- `pageSize`: 每页数量（默认20）
|
||
|
||
### 7. 获取工作表列表
|
||
|
||
**接口**: `GET /jarvis/wps365/sheets`
|
||
|
||
**参数**:
|
||
- `userId`: 用户ID
|
||
- `fileToken`: 文件token
|
||
|
||
### 8. 读取单元格数据
|
||
|
||
**接口**: `GET /jarvis/wps365/readCells`
|
||
|
||
**参数**:
|
||
- `userId`: 用户ID
|
||
- `fileToken`: 文件token
|
||
- `sheetIdx`: 工作表索引（从0开始）
|
||
- `range`: 单元格范围（如：A1:B10，可选）
|
||
|
||
### 9. 更新单元格数据
|
||
|
||
**接口**: `POST /jarvis/wps365/updateCells`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"userId": "user_id",
|
||
"fileToken": "file_token",
|
||
"sheetIdx": 0,
|
||
"range": "A1:B2",
|
||
"values": [
|
||
["值1", "值2"],
|
||
["值3", "值4"]
|
||
]
|
||
}
|
||
```
|
||
|
||
### 10. 批量更新单元格数据
|
||
|
||
**接口**: `POST /jarvis/wps365/batchUpdateCells`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"userId": "user_id",
|
||
"fileToken": "file_token",
|
||
"sheetIdx": 0,
|
||
"updates": [
|
||
{
|
||
"range": "A1:B2",
|
||
"values": [["值1", "值2"], ["值3", "值4"]]
|
||
},
|
||
{
|
||
"range": "C1:D2",
|
||
"values": [["值5", "值6"], ["值7", "值8"]]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
### 1. 用户授权流程
|
||
|
||
1. 前端调用 `/jarvis/wps365/authUrl` 获取授权URL
|
||
2. 在新窗口打开授权URL，用户完成授权
|
||
3. WPS365会回调到配置的 `redirect-uri`，自动处理授权码
|
||
4. 系统自动获取并保存Token到Redis
|
||
|
||
### 2. 编辑文档流程
|
||
|
||
1. 调用 `/jarvis/wps365/files` 获取文件列表
|
||
2. 选择要编辑的文件，调用 `/jarvis/wps365/sheets` 获取工作表列表
|
||
3. 调用 `/jarvis/wps365/readCells` 读取现有数据
|
||
4. 修改数据后，调用 `/jarvis/wps365/updateCells` 更新数据
|
||
|
||
### 3. Token刷新
|
||
|
||
- Token过期前，系统会自动尝试刷新
|
||
- 也可以手动调用 `/jarvis/wps365/refreshToken` 刷新Token
|
||
|
||
## 注意事项
|
||
|
||
1. **用户权限**：只有文档的所有者或被授予编辑权限的用户才能编辑文档
|
||
2. **Token管理**：Token存储在Redis中，有效期30天。过期后需要重新授权
|
||
3. **API限制**：注意WPS365的API调用频率限制
|
||
4. **文件Token**：WPS365使用 `file_token` 而不是文件ID，需要从文件列表中获取
|
||
|
||
## 前端页面
|
||
|
||
访问 `/jarvis/wps365` 可以打开WPS365管理页面，包含：
|
||
- 授权状态显示
|
||
- 用户信息查看
|
||
- 文件列表浏览
|
||
- 在线编辑表格功能
|
||
|
||
## 错误处理
|
||
|
||
- **未授权**：返回错误提示，引导用户完成授权
|
||
- **Token过期**：自动尝试刷新Token，刷新失败则提示重新授权
|
||
- **权限不足**：返回错误码10003，提示用户没有编辑权限
|
||
|
||
## 技术实现
|
||
|
||
- **后端**：Spring Boot + Redis（Token存储）
|
||
- **前端**：Vue.js + Element UI
|
||
- **HTTP客户端**：HttpURLConnection（不使用代理，直接连接）
|
||
|
||
## 参考文档
|
||
|
||
- [WPS365开放平台文档](https://open.wps.cn/)
|
||
- [用户授权流程](https://open.wps.cn/documents/app-integration-dev/wps365/server/certification-authorization/user-authorization/flow)
|
||
- [KSheet API文档](https://developer.kdocs.cn/server/ksheet/)
|
||
|