1
This commit is contained in:
Leo
271
doc/WPS365读取在线表格配置指南.md
Normal file
271
doc/WPS365读取在线表格配置指南.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# WPS365 读取在线表格内容配置指南
|
||||
|
||||
## 概述
|
||||
|
||||
本指南详细说明如何配置WPS365应用，以实现读取自己创建的在线表格内容。
|
||||
|
||||
## 一、WPS365开放平台配置步骤
|
||||
|
||||
### 1. 应用基础配置
|
||||
|
||||
1. **登录WPS365开放平台**
|
||||
- 访问：https://open.wps.cn/
|
||||
- 使用WPS账号登录
|
||||
|
||||
2. **创建应用**
|
||||
- 进入"应用管理"
|
||||
- 点击"创建应用"
|
||||
- 填写应用名称（如：Jarvis同步WPS）
|
||||
- 选择应用类型：**服务端应用**
|
||||
|
||||
3. **获取应用凭证**
|
||||
- 记录 `AppID`（应用ID）
|
||||
- 记录 `AppKey`（应用密钥，注意保密）
|
||||
|
||||
### 2. 配置回调地址
|
||||
|
||||
1. **进入"开发配置" > "事件与回调"**
|
||||
2. **配置回调地址**
|
||||
- 回调地址：`https://jarvis.van333.cn/wps365-callback`
|
||||
- 点击"验证"按钮，确保验证通过
|
||||
- 如果验证失败，检查：
|
||||
- 回调接口是否支持GET和POST请求
|
||||
- 是否能正确处理challenge参数
|
||||
- 前端白名单是否已配置
|
||||
|
||||
### 3. 配置权限（关键步骤）
|
||||
|
||||
#### 3.1 进入权限管理
|
||||
|
||||
1. 在左侧导航栏选择 **"开发配置" > "权限管理"**
|
||||
2. 查看当前应用的权限列表
|
||||
|
||||
#### 3.2 添加必要权限
|
||||
|
||||
需要添加以下权限才能读取在线表格内容：
|
||||
|
||||
**基础权限：**
|
||||
- ✅ `file.read` - 读取文件权限
|
||||
- ✅ `file.readwrite` - 读取和写入文件权限（如果只需要读取，可以只选read）
|
||||
- ✅ `user.info` - 获取用户信息权限
|
||||
|
||||
**在线表格（KSheet）权限：**
|
||||
- ✅ `ksheet:read` - 读取在线表格数据
|
||||
- ✅ `ksheet:write` - 写入在线表格数据（如果需要编辑功能）
|
||||
|
||||
**权限说明：**
|
||||
- 这些权限决定了你的应用能访问哪些资源
|
||||
- 用户授权时，会看到这些权限的说明
|
||||
- 只有用户同意授权后，应用才能访问对应的资源
|
||||
|
||||
#### 3.3 权限申请流程
|
||||
|
||||
1. 在权限管理页面，点击"添加权限"
|
||||
2. 搜索并选择上述权限
|
||||
3. 提交权限申请（部分权限可能需要审核）
|
||||
4. 等待审核通过
|
||||
|
||||
### 4. 应用能力配置（可选）
|
||||
|
||||
根据图片显示，WPS365开放平台提供了多种应用能力：
|
||||
|
||||
**协作与会话：**
|
||||
- WPS协作机器人
|
||||
- 工作台小组件
|
||||
- WPS协作网页应用
|
||||
|
||||
**多维表格：**
|
||||
- 记录卡片插件
|
||||
- 字段插件
|
||||
- 视图插件
|
||||
- 仪表盘插件
|
||||
- 数据连接器插件
|
||||
- 自动化插件
|
||||
|
||||
**注意：**
|
||||
- 如果只是读取在线表格内容，通常不需要开启这些插件能力
|
||||
- 这些能力主要用于扩展表格功能，不是读取数据的必要条件
|
||||
- 读取数据主要依赖API权限，而不是这些插件能力
|
||||
|
||||
## 二、后端配置
|
||||
|
||||
### 1. 更新配置文件
|
||||
|
||||
在 `application-dev.yml` 中添加配置：
|
||||
|
||||
```yaml
|
||||
wps365:
|
||||
# 应用ID（从WPS365开放平台获取）
|
||||
app-id: YOUR_APP_ID
|
||||
# 应用密钥（从WPS365开放平台获取）
|
||||
app-key: YOUR_APP_KEY
|
||||
# 授权回调地址
|
||||
redirect-uri: https://jarvis.van333.cn/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
|
||||
```
|
||||
|
||||
### 2. 确认授权范围（Scope）
|
||||
|
||||
当前代码中使用的授权范围：
|
||||
```java
|
||||
scope=file.readwrite,user.info
|
||||
```
|
||||
|
||||
如果需要更细粒度的权限控制，可以修改为：
|
||||
```java
|
||||
scope=file.read,ksheet:read,user.info // 只读权限
|
||||
// 或
|
||||
scope=file.readwrite,ksheet:readwrite,user.info // 读写权限
|
||||
```
|
||||
|
||||
## 三、使用流程
|
||||
|
||||
### 1. 用户授权
|
||||
|
||||
1. 调用 `/jarvis/wps365/authUrl` 获取授权URL
|
||||
2. 用户访问授权URL，同意授权
|
||||
3. WPS365回调到 `/wps365-callback`，自动保存Token
|
||||
|
||||
### 2. 获取文件列表
|
||||
|
||||
```javascript
|
||||
// 调用接口获取文件列表
|
||||
GET /jarvis/wps365/files?userId=xxx&page=1&pageSize=20
|
||||
```
|
||||
|
||||
### 3. 获取工作表列表
|
||||
|
||||
```javascript
|
||||
// 获取指定文件的工作表列表
|
||||
GET /jarvis/wps365/sheets?userId=xxx&fileToken=xxx
|
||||
```
|
||||
|
||||
### 4. 读取单元格数据
|
||||
|
||||
```javascript
|
||||
// 读取指定范围的单元格数据
|
||||
GET /jarvis/wps365/readCells?userId=xxx&fileToken=xxx&sheetIdx=0&range=A1:Z100
|
||||
```
|
||||
|
||||
**参数说明：**
|
||||
- `userId`: 用户ID（授权后获取）
|
||||
- `fileToken`: 文件Token（从文件列表中获取）
|
||||
- `sheetIdx`: 工作表索引（从0开始）
|
||||
- `range`: 单元格范围（如：A1:Z100，可选，不填则读取整个工作表）
|
||||
|
||||
## 四、常见问题
|
||||
|
||||
### Q1: 提示"权限不足"或"无权限访问"
|
||||
|
||||
**解决方案：**
|
||||
1. 检查WPS365开放平台的权限配置
|
||||
2. 确认已添加 `file.read` 和 `ksheet:read` 权限
|
||||
3. 重新授权（删除旧Token，重新获取授权）
|
||||
|
||||
### Q2: 无法读取自己创建的表格
|
||||
|
||||
**可能原因：**
|
||||
1. 文件Token不正确
|
||||
2. 工作表索引错误
|
||||
3. 用户对文件没有读取权限（即使是自己创建的，也需要授权给应用）
|
||||
|
||||
**解决方案：**
|
||||
1. 确认文件Token是从文件列表中正确获取的
|
||||
2. 使用 `/jarvis/wps365/sheets` 接口确认工作表索引
|
||||
3. 确保用户已授权应用访问该文件
|
||||
|
||||
### Q3: 读取返回空数据
|
||||
|
||||
**可能原因：**
|
||||
1. 指定的单元格范围没有数据
|
||||
2. 工作表索引错误
|
||||
3. API返回格式与预期不符
|
||||
|
||||
**解决方案：**
|
||||
1. 尝试读取更大的范围（如：A1:Z1000）
|
||||
2. 检查工作表索引是否正确
|
||||
3. 查看后端日志，确认API返回的具体内容
|
||||
|
||||
## 五、API接口说明
|
||||
|
||||
### 读取单元格数据接口
|
||||
|
||||
**接口地址：** `GET /jarvis/wps365/readCells`
|
||||
|
||||
**请求参数：**
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| userId | String | 是 | 用户ID |
|
||||
| fileToken | String | 是 | 文件Token |
|
||||
| sheetIdx | Integer | 否 | 工作表索引，默认0 |
|
||||
| range | String | 否 | 单元格范围，如：A1:B10 |
|
||||
|
||||
**返回示例：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "读取单元格数据成功",
|
||||
"data": {
|
||||
"values": [
|
||||
["列1", "列2", "列3"],
|
||||
["数据1", "数据2", "数据3"],
|
||||
["数据4", "数据5", "数据6"]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 六、完整示例
|
||||
|
||||
### 前端调用示例
|
||||
|
||||
```javascript
|
||||
import {
|
||||
getWPS365AuthUrl,
|
||||
getWPS365FileList,
|
||||
getWPS365SheetList,
|
||||
readWPS365Cells
|
||||
} from '@/api/jarvis/wps365'
|
||||
|
||||
// 1. 获取授权URL
|
||||
const authResponse = await getWPS365AuthUrl()
|
||||
window.open(authResponse.data, '_blank')
|
||||
|
||||
// 2. 等待授权完成后，获取文件列表
|
||||
const fileListResponse = await getWPS365FileList({
|
||||
userId: 'your_user_id',
|
||||
page: 1,
|
||||
pageSize: 20
|
||||
})
|
||||
|
||||
// 3. 选择要读取的文件，获取工作表列表
|
||||
const fileToken = fileListResponse.data.files[0].file_token
|
||||
const sheetListResponse = await getWPS365SheetList('your_user_id', fileToken)
|
||||
|
||||
// 4. 读取第一个工作表的数据
|
||||
const dataResponse = await readWPS365Cells({
|
||||
userId: 'your_user_id',
|
||||
fileToken: fileToken,
|
||||
sheetIdx: 0,
|
||||
range: 'A1:Z100'
|
||||
})
|
||||
|
||||
console.log('表格数据：', dataResponse.data.values)
|
||||
```
|
||||
|
||||
## 七、注意事项
|
||||
|
||||
1. **权限范围**：确保在WPS365开放平台配置了正确的权限
|
||||
2. **文件Token**：使用fileToken而不是fileId来访问文件
|
||||
3. **工作表索引**：工作表索引从0开始，不是从1开始
|
||||
4. **单元格范围**：范围格式为 `A1:B10`，不区分大小写
|
||||
5. **Token有效期**：Token会过期，需要定期刷新或重新授权
|
||||
6. **数据量限制**：一次读取的数据量不要太大，建议分批读取
|
||||
|
||||
@@ -21,6 +21,38 @@
|
||||
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配置：
|
||||
|
||||
Reference in New Issue
Block a user