233 lines
5.7 KiB
Markdown
233 lines
5.7 KiB
Markdown
# 腾讯文档 V3 写入数据问题分析
|
||
|
||
## 🔴 问题现象
|
||
|
||
尝试使用腾讯文档 V3 API 的 `batchUpdate` 接口写入单元格数据时，始终返回错误：
|
||
|
||
```json
|
||
{
|
||
"code": 400001,
|
||
"message": "request name error"
|
||
}
|
||
```
|
||
|
||
**尝试过的请求类型**：
|
||
1. ❌ `updateCells` - 报错：request name error
|
||
2. ❌ `updateCellsRequest` - 报错：request name error
|
||
3. 🔄 `repeatCellRequest` - 正在测试
|
||
|
||
---
|
||
|
||
## 🔍 根本问题分析
|
||
|
||
### 观察到的现象
|
||
|
||
1. **读取数据成功**：
|
||
```
|
||
GET /openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}
|
||
✅ 成功返回数据
|
||
```
|
||
|
||
2. **批量更新失败**：
|
||
```
|
||
POST /openapi/spreadsheet/v3/files/{fileId}/batchUpdate
|
||
❌ request name error
|
||
```
|
||
|
||
3. **官方文档示例**：
|
||
- ✅ `addSheetRequest` - 添加工作表（结构操作）
|
||
- ✅ `deleteDimensionRequest` - 删除维度（结构操作）
|
||
- ❓ `updateCellsRequest` - **官方文档未提及**
|
||
|
||
### 可能的原因
|
||
|
||
#### 原因 1：V3 API 不支持单元格数据写入
|
||
|
||
腾讯文档 V3 API 的 `batchUpdate` 接口可能**只支持结构性操作**，不支持数据写入：
|
||
|
||
| 支持的操作 | 说明 |
|
||
|-----------|------|
|
||
| ✅ addSheetRequest | 添加工作表 |
|
||
| ✅ deleteSheetRequest | 删除工作表 |
|
||
| ✅ deleteDimensionRequest | 删除行/列 |
|
||
| ✅ insertDimensionRequest | 插入行/列 |
|
||
| ✅ mergeCellsRequest | 合并单元格 |
|
||
| ❌ updateCellsRequest | **数据写入（不支持？）** |
|
||
| ❌ writeCellsRequest | **数据写入（不支持？）** |
|
||
|
||
#### 原因 2：V3 API 文档不完整
|
||
|
||
腾讯文档官方文档可能没有公开所有可用的请求类型，或者写入数据的接口使用不同的端点。
|
||
|
||
#### 原因 3：需要使用 V2 API
|
||
|
||
腾讯文档 V2 API 可能有专门的写入接口，但 V2 API 已被标记为"已废弃"。
|
||
|
||
---
|
||
|
||
## 💡 可能的解决方案
|
||
|
||
### 方案 1：使用 repeatCellRequest（当前尝试）
|
||
|
||
```json
|
||
{
|
||
"requests": [
|
||
{
|
||
"repeatCellRequest": {
|
||
"range": {
|
||
"sheetId": "BB08J2",
|
||
"startRowIndex": 2,
|
||
"endRowIndex": 3,
|
||
"startColumnIndex": 12,
|
||
"endColumnIndex": 13
|
||
},
|
||
"cell": {
|
||
"cellValue": {
|
||
"text": "https://3.cn/2ume-Ak1"
|
||
}
|
||
},
|
||
"fields": "cellValue"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**说明**：`repeatCell` 通常用于在范围内重复填充相同的单元格内容，可能可以用于单个单元格写入。
|
||
|
||
---
|
||
|
||
### 方案 2：使用 V2 API（如果 V1/V3 都不支持）
|
||
|
||
腾讯文档 V2 API 可能有不同的接口结构。需要查看 V2 文档。
|
||
|
||
**优点**：
|
||
- 可能有专门的数据写入接口
|
||
- 可能更简单直接
|
||
|
||
**缺点**：
|
||
- V2 API 已标记为"已废弃"
|
||
- 未来可能不再维护
|
||
|
||
---
|
||
|
||
### 方案 3：使用 append 接口追加数据
|
||
|
||
如果目标是追加新数据（而不是更新现有单元格），可以使用 `appendDimension` 或类似接口。
|
||
|
||
**限制**：
|
||
- 只能追加，不能更新指定位置的单元格
|
||
- 不适用于我们的场景（需要更新指定行的物流列）
|
||
|
||
---
|
||
|
||
### 方案 4：联系腾讯文档官方支持
|
||
|
||
**如果以上方案都不行**，需要：
|
||
1. 查看腾讯文档开放平台的完整 API 文档
|
||
2. 在官方论坛/社区提问
|
||
3. 联系技术支持获取帮助
|
||
|
||
---
|
||
|
||
## 🧪 测试步骤
|
||
|
||
### 测试 repeatCellRequest
|
||
|
||
1. **重启应用**
|
||
|
||
2. **发送测试请求**：
|
||
```bash
|
||
curl -X POST 'http://localhost:30313/jarvis/tencentDoc/fillLogisticsByOrderNo' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"accessToken": "YOUR_ACCESS_TOKEN",
|
||
"fileId": "DUW50RUprWXh2TGJK",
|
||
"sheetId": "BB08J2",
|
||
"headerRow": 2
|
||
}'
|
||
```
|
||
|
||
3. **查看日志**：
|
||
```
|
||
写入表格数据（batchUpdate）- range: M3
|
||
请求体: {
|
||
"requests": [
|
||
{
|
||
"repeatCellRequest": {
|
||
"range": {...},
|
||
"cell": {...},
|
||
"fields": "cellValue"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
4. **预期结果**：
|
||
- ✅ 如果成功：`{"ret":0, "msg":"Succeed"}`
|
||
- ❌ 如果失败：继续尝试其他方案
|
||
|
||
---
|
||
|
||
## 📚 参考资料
|
||
|
||
### 官方文档
|
||
|
||
- [批量更新接口](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/update.html)
|
||
- [Request 类型说明](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/request.html)
|
||
- [在线表格总览](https://docs.qq.com/open/document/app/openapi/v3/sheet/)
|
||
|
||
### 需要确认的问题
|
||
|
||
1. ❓ 腾讯文档 V3 API 是否支持单元格数据写入？
|
||
2. ❓ 如果支持，正确的请求类型名称是什么？
|
||
3. ❓ 是否需要使用不同的 API 端点？
|
||
4. ❓ 是否需要特殊权限或配置？
|
||
|
||
---
|
||
|
||
## 🎯 下一步行动
|
||
|
||
### 优先级 1：测试 repeatCellRequest
|
||
|
||
当前代码已修改为使用 `repeatCellRequest`，需要测试是否可行。
|
||
|
||
### 优先级 2：查找完整的 Request 类型列表
|
||
|
||
需要找到腾讯文档 V3 API 支持的**所有** Request 类型的完整列表，确认是否有数据写入相关的类型。
|
||
|
||
### 优先级 3：考虑备选方案
|
||
|
||
如果 batchUpdate 确实不支持数据写入：
|
||
1. 查找是否有其他 V3 API 端点支持写入
|
||
2. 考虑使用 V2 API
|
||
3. 联系官方技术支持
|
||
|
||
---
|
||
|
||
## 💬 给用户的建议
|
||
|
||
**当前状态**：
|
||
- ✅ 数据读取完全正常
|
||
- ✅ 数据库匹配完全正常
|
||
- ❌ 数据写入遇到 API 限制
|
||
|
||
**如果 repeatCellRequest 也失败**：
|
||
|
||
建议联系腾讯文档开放平台技术支持，询问：
|
||
1. V3 API 如何写入单元格数据？
|
||
2. 是否有相关的官方示例代码？
|
||
3. batchUpdate 支持哪些 Request 类型？
|
||
|
||
**腾讯文档开放平台**：
|
||
- 官网：https://docs.qq.com/open/
|
||
- 反馈入口：https://docs.qq.com/open/feedback
|
||
|
||
---
|
||
|
||
**文档版本**：1.0
|
||
**创建时间**：2025-11-05
|
||
**状态**：🔄 问题分析中，正在测试 repeatCellRequest
|
||
|