397 lines
10 KiB
Markdown
397 lines
10 KiB
Markdown
# 腾讯文档 API 读取失败诊断指南
|
||
|
||
## 问题描述
|
||
当调用腾讯文档读取接口时，返回错误：
|
||
```json
|
||
{
|
||
"msg": "无法读取表头，请检查headerRow参数",
|
||
"code": 500
|
||
}
|
||
```
|
||
|
||
请求参数：
|
||
```json
|
||
{
|
||
"fileId": "DUW50RUprWXh2TGJK",
|
||
"sheetId": "BB08J2",
|
||
"headerRow": 1,
|
||
"orderNoColumn": 3,
|
||
"logisticsLinkColumn": 13
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 已添加的调试功能
|
||
|
||
我已经在代码中添加了详细的日志记录，现在会输出以下信息：
|
||
|
||
### 1. Service 层日志
|
||
- 开始读取表格数据的参数
|
||
- 获取用户信息的响应
|
||
- Open ID 提取结果
|
||
- API 调用参数
|
||
- API 返回结果
|
||
|
||
### 2. Controller 层日志
|
||
- 读取表头的范围
|
||
- 表头数据的完整响应
|
||
- values 数组是否为空
|
||
|
||
---
|
||
|
||
## 诊断步骤
|
||
|
||
### 步骤 1：查看应用日志
|
||
|
||
启用 DEBUG 级别日志：
|
||
|
||
**application-dev.yml**：
|
||
```yaml
|
||
logging:
|
||
level:
|
||
com.ruoyi.jarvis.service.impl.TencentDocServiceImpl: DEBUG
|
||
com.ruoyi.jarvis.util.TencentDocApiUtil: DEBUG
|
||
com.ruoyi.web.controller.jarvis.TencentDocController: DEBUG
|
||
```
|
||
|
||
重启应用后，再次调用 API，查看日志输出。
|
||
|
||
### 步骤 2：分析日志信息
|
||
|
||
#### 2.1 检查用户信息获取
|
||
查找日志：
|
||
```
|
||
正在获取用户信息...
|
||
用户信息响应: {"ret":0,"msg":"Succeed","data":{...}}
|
||
```
|
||
|
||
**可能的问题**：
|
||
- ❌ 如果看到 `401 Unauthorized`：Access Token 无效或过期
|
||
- ❌ 如果看到 `ret != 0`：业务逻辑错误
|
||
- ❌ 如果 `data` 为 null：响应格式不正确
|
||
|
||
**解决方案**：
|
||
1. 检查 Access Token 是否有效
|
||
2. 使用 Refresh Token 刷新 Access Token
|
||
3. 重新进行 OAuth2 授权
|
||
|
||
#### 2.2 检查 Open ID 获取
|
||
查找日志：
|
||
```
|
||
成功获取 Open ID: bcb50c8a4b724d86bbcf6fc64c5e2b22
|
||
```
|
||
|
||
**可能的问题**：
|
||
- ❌ 如果看到 `openID 字段不存在`：响应结构解析错误
|
||
- ❌ 如果 openID 为空：用户信息不完整
|
||
|
||
**解决方案**：
|
||
1. 检查用户信息响应的完整内容
|
||
2. 确认响应格式是否为：`{"ret":0,"msg":"Succeed","data":{"openID":"xxx",...}}`
|
||
3. 注意字段名是 `openID`（大写 ID）
|
||
|
||
#### 2.3 检查 API 调用
|
||
查找日志：
|
||
```
|
||
读取表格数据 - fileId: DUW50RUprWXh2TGJK, sheetId: BB08J2, range: A1:Z1, apiUrl: https://docs.qq.com/openapi/spreadsheet/v3/files/DUW50RUprWXh2TGJK/BB08J2/A1:Z1
|
||
```
|
||
|
||
**可能的问题**：
|
||
- ❌ 如果看到 `404 Not Found`：文件 ID 或工作表 ID 错误
|
||
- ❌ 如果看到 `403 Forbidden`：没有访问权限
|
||
- ❌ 如果看到 `400 Bad Request`：请求参数格式错误
|
||
|
||
**解决方案**：
|
||
1. **验证 File ID**：
|
||
- 打开腾讯文档，从 URL 中获取正确的 File ID
|
||
- URL 格式：`https://docs.qq.com/sheet/DUW50RUprWXh2TGJK?tab=BB08J2`
|
||
- File ID 是 `sheet/` 后面到 `?` 之前的部分
|
||
|
||
2. **验证 Sheet ID**：
|
||
- Sheet ID 是 URL 中 `tab=` 后面的部分
|
||
- 例如：`BB08J2`
|
||
|
||
3. **检查文档权限**：
|
||
- 确认授权用户有权限访问该文档
|
||
- 在腾讯文档中检查分享设置
|
||
|
||
#### 2.4 检查 API 响应
|
||
查找日志：
|
||
```
|
||
表头数据响应: {"values":[["列1","列2","列3"]]}
|
||
```
|
||
或
|
||
```
|
||
表头数据中values数组为空，完整响应: {...}
|
||
```
|
||
|
||
**可能的问题**：
|
||
|
||
##### 问题 A：API 返回成功但 values 为空
|
||
```json
|
||
{
|
||
"values": []
|
||
}
|
||
```
|
||
或
|
||
```json
|
||
{}
|
||
```
|
||
|
||
**原因**：
|
||
1. 指定的行数据确实为空
|
||
2. Range 格式不正确
|
||
3. 权限不足，只能看到空数据
|
||
|
||
**解决方案**：
|
||
1. 手动在腾讯文档中检查第 1 行是否有数据
|
||
2. 尝试不同的 range：
|
||
- `A1:A1`（单个单元格）
|
||
- `A1:E1`（前 5 列）
|
||
- `A1`（从 A1 开始的所有数据）
|
||
|
||
##### 问题 B：API 返回错误
|
||
可能的错误响应：
|
||
```json
|
||
{
|
||
"error": "invalid_token",
|
||
"error_description": "Invalid access token"
|
||
}
|
||
```
|
||
|
||
**原因**：
|
||
- Access Token 无效或过期
|
||
- Open ID 不正确
|
||
- Client ID（App ID）不正确
|
||
|
||
**解决方案**：
|
||
1. 刷新 Access Token
|
||
2. 重新获取 Open ID
|
||
3. 检查配置文件中的 App ID
|
||
|
||
---
|
||
|
||
## 常见问题和解决方案
|
||
|
||
### 问题 1：Access Token 过期
|
||
|
||
**症状**：
|
||
```
|
||
getUserInfo 返回 401 Unauthorized
|
||
```
|
||
|
||
**解决方案**：
|
||
```java
|
||
// 使用 Refresh Token 刷新 Access Token
|
||
JSONObject newTokens = tencentDocService.refreshAccessToken(refreshToken);
|
||
String newAccessToken = newTokens.getString("access_token");
|
||
String newRefreshToken = newTokens.getString("refresh_token");
|
||
|
||
// 保存新的 tokens
|
||
// ...
|
||
```
|
||
|
||
### 问题 2：文档权限不足
|
||
|
||
**症状**：
|
||
```
|
||
调用腾讯文档API失败: HTTP 403 Forbidden
|
||
```
|
||
|
||
**解决方案**：
|
||
1. 在腾讯文档中打开该文档
|
||
2. 点击右上角"分享"按钮
|
||
3. 确认授权用户的微信/QQ 账号有访问权限
|
||
4. 如果是企业文档，需要确认企业权限设置
|
||
|
||
### 问题 3：File ID 或 Sheet ID 错误
|
||
|
||
**症状**：
|
||
```
|
||
调用腾讯文档API失败: HTTP 404 Not Found
|
||
```
|
||
|
||
**解决方案**：
|
||
1. 重新从浏览器地址栏复制完整 URL
|
||
2. 正确提取 File ID 和 Sheet ID：
|
||
|
||
```
|
||
URL: https://docs.qq.com/sheet/DUW50RUprWXh2TGJK?tab=BB08J2
|
||
↑ ↑
|
||
File ID Sheet ID
|
||
(18个字符) (6个字符)
|
||
```
|
||
|
||
3. File ID 通常以 `D` 开头，长度约 18 个字符
|
||
4. Sheet ID 通常是 6 个大写字母和数字的组合
|
||
|
||
### 问题 4：Range 格式错误
|
||
|
||
**症状**：
|
||
```
|
||
values 数组为空，但手动检查文档有数据
|
||
```
|
||
|
||
**可能的原因**：
|
||
- Range 格式不符合腾讯文档 API 规范
|
||
- 行号从 0 开始而不是从 1 开始
|
||
|
||
**测试不同的 Range 格式**：
|
||
```bash
|
||
# 测试 1：单个单元格
|
||
curl "http://localhost:8080/api/test/read?fileId=XXX&sheetId=YYY&range=A1"
|
||
|
||
# 测试 2：单行范围
|
||
curl "http://localhost:8080/api/test/read?fileId=XXX&sheetId=YYY&range=A1:Z1"
|
||
|
||
# 测试 3：多行范围
|
||
curl "http://localhost:8080/api/test/read?fileId=XXX&sheetId=YYY&range=A1:Z10"
|
||
|
||
# 测试 4：使用行号 0（如果API是从0开始）
|
||
curl "http://localhost:8080/api/test/read?fileId=XXX&sheetId=YYY&range=A0:Z0"
|
||
```
|
||
|
||
### 问题 5：鉴权头设置错误
|
||
|
||
**症状**：
|
||
```
|
||
调用腾讯文档API失败: HTTP 401 Unauthorized
|
||
```
|
||
|
||
**检查**：
|
||
确认代码中使用了正确的鉴权方式：
|
||
```java
|
||
conn.setRequestProperty("Access-Token", accessToken);
|
||
conn.setRequestProperty("Client-Id", clientId);
|
||
conn.setRequestProperty("Open-Id", openId);
|
||
```
|
||
|
||
而不是：
|
||
```java
|
||
conn.setRequestProperty("Authorization", "Bearer " + accessToken); // ❌ 错误
|
||
```
|
||
|
||
---
|
||
|
||
## 快速诊断脚本
|
||
|
||
创建一个测试接口来诊断问题：
|
||
|
||
```java
|
||
@GetMapping("/test/diagnose")
|
||
public Map<String, Object> diagnose(@RequestParam String accessToken) {
|
||
Map<String, Object> result = new LinkedHashMap<>();
|
||
|
||
try {
|
||
// 1. 测试获取用户信息
|
||
System.out.println("\n=== 步骤1：获取用户信息 ===");
|
||
JSONObject userInfo = TencentDocApiUtil.getUserInfo(accessToken);
|
||
result.put("1_userInfo", userInfo);
|
||
System.out.println("✓ 用户信息: " + userInfo.toJSONString());
|
||
|
||
// 2. 提取 Open ID
|
||
System.out.println("\n=== 步骤2：提取 Open ID ===");
|
||
JSONObject data = userInfo.getJSONObject("data");
|
||
String openID = data != null ? data.getString("openID") : null;
|
||
result.put("2_openID", openID);
|
||
System.out.println("✓ Open ID: " + openID);
|
||
|
||
// 3. 测试读取文档
|
||
String testFileId = "DUW50RUprWXh2TGJK";
|
||
String testSheetId = "BB08J2";
|
||
String testRange = "A1:Z1";
|
||
|
||
System.out.println("\n=== 步骤3：读取表格数据 ===");
|
||
System.out.println("File ID: " + testFileId);
|
||
System.out.println("Sheet ID: " + testSheetId);
|
||
System.out.println("Range: " + testRange);
|
||
|
||
JSONObject readResult = tencentDocService.readSheetData(
|
||
accessToken, testFileId, testSheetId, testRange
|
||
);
|
||
result.put("3_readResult", readResult);
|
||
System.out.println("✓ 读取结果: " + readResult.toJSONString());
|
||
|
||
// 4. 检查 values 数组
|
||
System.out.println("\n=== 步骤4：检查 values 数组 ===");
|
||
JSONArray values = readResult != null ? readResult.getJSONArray("values") : null;
|
||
result.put("4_values", values);
|
||
result.put("4_valuesCount", values != null ? values.size() : 0);
|
||
System.out.println("✓ Values 数组大小: " + (values != null ? values.size() : 0));
|
||
if (values != null && !values.isEmpty()) {
|
||
System.out.println("✓ 第一行数据: " + values.getJSONArray(0).toJSONString());
|
||
}
|
||
|
||
result.put("status", "success");
|
||
result.put("message", "所有测试通过");
|
||
|
||
} catch (Exception e) {
|
||
result.put("status", "error");
|
||
result.put("error", e.getMessage());
|
||
result.put("stackTrace", Arrays.toString(e.getStackTrace()));
|
||
System.err.println("✗ 诊断失败: " + e.getMessage());
|
||
e.printStackTrace();
|
||
}
|
||
|
||
return result;
|
||
}
|
||
```
|
||
|
||
**使用方法**：
|
||
```bash
|
||
curl "http://localhost:8080/test/diagnose?accessToken=YOUR_ACCESS_TOKEN"
|
||
```
|
||
|
||
---
|
||
|
||
## 检查清单
|
||
|
||
执行以下检查清单，确保所有配置正确：
|
||
|
||
### 配置检查
|
||
- [ ] `application-dev.yml` 中 `app-id` 配置正确
|
||
- [ ] `application-dev.yml` 中 `app-secret` 配置正确
|
||
- [ ] `application-dev.yml` 中 `api-base-url` 为 `https://docs.qq.com/openapi/spreadsheet/v3`
|
||
- [ ] 日志级别设置为 DEBUG
|
||
|
||
### 授权检查
|
||
- [ ] Access Token 未过期（有效期3天）
|
||
- [ ] 授权用户有访问该文档的权限
|
||
- [ ] 文档没有被删除或移动
|
||
|
||
### 参数检查
|
||
- [ ] File ID 正确（从 URL 中复制）
|
||
- [ ] Sheet ID 正确（从 URL 的 tab 参数中复制）
|
||
- [ ] headerRow 参数正确（通常为 1）
|
||
- [ ] Range 格式正确（如 `A1:Z1`）
|
||
|
||
### 代码检查
|
||
- [ ] 使用查询参数方式调用 `/oauth/v2/userinfo?access_token=xxx`
|
||
- [ ] 正确解析用户信息：`userInfo.getJSONObject("data").getString("openID")`
|
||
- [ ] 使用三个鉴权头：`Access-Token`, `Client-Id`, `Open-Id`
|
||
|
||
---
|
||
|
||
## 联系支持
|
||
|
||
如果以上步骤都无法解决问题，请提供以下信息：
|
||
|
||
1. **完整的日志输出**（DEBUG 级别）
|
||
2. **请求参数**：
|
||
- File ID
|
||
- Sheet ID
|
||
- Header Row
|
||
- Range
|
||
3. **腾讯文档 URL**（用于验证 ID 是否正确）
|
||
4. **错误信息**（完整的堆栈跟踪）
|
||
5. **用户信息响应**（脱敏后的 JSON）
|
||
6. **API 调用响应**（完整的 JSON）
|
||
|
||
---
|
||
|
||
**诊断指南版本**：1.0
|
||
**创建时间**：2025-11-05
|
||
**适用场景**：腾讯文档 API 读取失败问题排查
|
||
|