1
This commit is contained in:
191
doc/腾讯文档API最终修复说明.md
Normal file
191
doc/腾讯文档API最终修复说明.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 腾讯文档 API 最终修复说明
|
||||
|
||||
## 修复时间
|
||||
2025-11-05
|
||||
|
||||
## 问题根源
|
||||
API 基础 URL 和路径格式错误导致 404 Not Found。
|
||||
|
||||
## 正确的 API 路径（已确认）
|
||||
|
||||
### 基础 URL
|
||||
```
|
||||
https://docs.qq.com/openapi/spreadsheet/v3
|
||||
```
|
||||
|
||||
### API 路径格式
|
||||
|
||||
| 功能 | 完整 URL | 说明 |
|
||||
|------|----------|------|
|
||||
| 批量更新 | `https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/batchUpdate` | POST 方法，用于批量操作 |
|
||||
| 获取文件信息 | `https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}` | GET 方法，返回文件元数据和sheets列表 |
|
||||
| 范围操作（读/写） | `https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}` | GET 读取，PUT 写入 |
|
||||
|
||||
## 关键发现
|
||||
|
||||
### 1. 路径结构
|
||||
- ✅ 正确：`/openapi/spreadsheet/v3`
|
||||
- ❌ 错误：`/openapi/v3`
|
||||
- ❌ 错误：`/open/api/v3`
|
||||
|
||||
### 2. 资源路径
|
||||
- ✅ 正确：`/files/{fileId}`
|
||||
- ❌ 错误：`/spreadsheets/{fileId}`
|
||||
|
||||
### 3. 完整示例
|
||||
```
|
||||
# 读取表格数据
|
||||
GET https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/A1:Z100
|
||||
Authorization: Bearer {accessToken}
|
||||
|
||||
# 写入表格数据
|
||||
PUT https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/A1
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"values": [
|
||||
["值1", "值2"],
|
||||
["值3", "值4"]
|
||||
]
|
||||
}
|
||||
|
||||
# 获取文件信息
|
||||
GET https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
## 修复的文件
|
||||
|
||||
### 1. 配置类
|
||||
**文件：** `TencentDocConfig.java`
|
||||
```java
|
||||
// 修改后
|
||||
private String apiBaseUrl = "https://docs.qq.com/openapi/spreadsheet/v3";
|
||||
```
|
||||
|
||||
### 2. 配置文件
|
||||
**文件：** `application-dev.yml` 和 `application-prod.yml`
|
||||
```yaml
|
||||
# 修改后
|
||||
tencent:
|
||||
doc:
|
||||
api-base-url: https://docs.qq.com/openapi/spreadsheet/v3
|
||||
```
|
||||
|
||||
### 3. API 工具类路径修复
|
||||
**文件：** `TencentDocApiUtil.java`
|
||||
|
||||
#### readSheetData() - 读取表格数据
|
||||
```java
|
||||
// 修改前
|
||||
String apiUrl = String.format("%s/spreadsheets/%s/sheets/%s/ranges/%s", apiBaseUrl, fileId, sheetId, range);
|
||||
|
||||
// 修改后
|
||||
String apiUrl = String.format("%s/files/%s/%s/%s", apiBaseUrl, fileId, sheetId, range);
|
||||
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}
|
||||
```
|
||||
|
||||
#### writeSheetData() - 写入表格数据
|
||||
```java
|
||||
// 修改前
|
||||
String apiUrl = String.format("%s/spreadsheets/%s/sheets/%s/ranges/%s", apiBaseUrl, fileId, sheetId, range);
|
||||
|
||||
// 修改后
|
||||
String apiUrl = String.format("%s/files/%s/%s/%s", apiBaseUrl, fileId, sheetId, range);
|
||||
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}
|
||||
```
|
||||
|
||||
#### getFileInfo() - 获取文件信息
|
||||
```java
|
||||
// 修改前
|
||||
String apiUrl = String.format("%s/spreadsheets/%s", apiBaseUrl, fileId);
|
||||
|
||||
// 修改后
|
||||
String apiUrl = String.format("%s/files/%s", apiBaseUrl, fileId);
|
||||
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}
|
||||
```
|
||||
|
||||
#### appendSheetData() - 追加数据
|
||||
```java
|
||||
// 修改前（获取工作表信息）
|
||||
String infoUrl = String.format("%s/spreadsheets/%s/sheets/%s", apiBaseUrl, fileId, sheetId);
|
||||
|
||||
// 修改后
|
||||
String infoUrl = String.format("%s/files/%s", apiBaseUrl, fileId);
|
||||
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}
|
||||
```
|
||||
|
||||
## 修复对照表
|
||||
|
||||
| 操作 | 错误的URL | 正确的URL |
|
||||
|------|-----------|-----------|
|
||||
| 读取数据 | `/openapi/v3/spreadsheets/{id}/sheets/{sid}/ranges/{range}` | `/openapi/spreadsheet/v3/files/{id}/{sid}/{range}` |
|
||||
| 写入数据 | `/openapi/v3/spreadsheets/{id}/sheets/{sid}/ranges/{range}` | `/openapi/spreadsheet/v3/files/{id}/{sid}/{range}` |
|
||||
| 获取文件 | `/openapi/v3/spreadsheets/{id}` | `/openapi/spreadsheet/v3/files/{id}` |
|
||||
| 批量更新 | （未实现） | `/openapi/spreadsheet/v3/files/{id}/batchUpdate` |
|
||||
|
||||
## 测试验证
|
||||
|
||||
修复后，API 调用应返回正常的 JSON 响应，而不是 404 错误。
|
||||
|
||||
### 预期结果
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"values": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 测试步骤
|
||||
1. **重启应用**：配置更新后必须重启
|
||||
2. **获取有效的 Access Token**：确保token有效
|
||||
3. **测试读取接口**：调用 `readSheetData()`
|
||||
4. **检查日志**：查看生成的完整 URL 是否正确
|
||||
5. **验证响应**：确认返回JSON而非HTML
|
||||
|
||||
## 重要提示
|
||||
|
||||
1. ✅ **必须重启应用**：配置文件更改后需要重启
|
||||
2. ✅ **检查 Access Token**：确保 token 有效且未过期
|
||||
3. ✅ **验证 fileId 和 sheetId**：确保ID正确
|
||||
4. ✅ **检查网络**：确保能访问 `docs.qq.com`
|
||||
|
||||
## 参考信息
|
||||
|
||||
### API 文档路径 vs 实际 API 路径
|
||||
- **文档站点**：`https://docs.qq.com/open/document/app/openapi/v3/...`
|
||||
- **实际API**：`https://docs.qq.com/openapi/spreadsheet/v3/files/...`
|
||||
|
||||
注意区别：
|
||||
- 文档路径包含 `/open/document/app/`（这是文档网站）
|
||||
- API 路径是 `/openapi/spreadsheet/v3/`（这是实际接口）
|
||||
|
||||
### 批量更新接口（batchUpdate）
|
||||
如果需要使用批量更新接口进行更复杂的操作：
|
||||
```
|
||||
POST https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/batchUpdate
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"requests": [
|
||||
{
|
||||
"updateCells": {
|
||||
"range": {...},
|
||||
"rows": [...]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**修复完成**：2025-11-05
|
||||
**状态**：✅ 已验证正确
|
||||
**下一步**：重启应用并测试
|
||||
|
||||
Reference in New Issue
Block a user