311 lines
6.1 KiB
Markdown
311 lines
6.1 KiB
Markdown
# 写入 API 字段名错误修复
|
||
|
||
## 🔴 问题现象
|
||
|
||
API 返回错误：
|
||
```json
|
||
{
|
||
"code": 400001,
|
||
"message": "request name error",
|
||
"details": {
|
||
"DebugInfo": {
|
||
"traceId": "ae0bfc4bfa674e258557e70b4f430a4c"
|
||
}
|
||
},
|
||
"internalCode": 0
|
||
}
|
||
```
|
||
|
||
**错误信息**：`request name error` - 请求名称错误
|
||
|
||
---
|
||
|
||
## 🔍 根本原因
|
||
|
||
根据[腾讯文档官方 batchUpdate 文档](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/update.html)，所有请求类型名称**必须以 `Request` 结尾**。
|
||
|
||
### 错误的请求体
|
||
|
||
```json
|
||
{
|
||
"requests": [
|
||
{
|
||
"updateCells": { // ❌ 错误：缺少 "Request" 后缀
|
||
"range": {...},
|
||
"rows": [...]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 正确的请求体
|
||
|
||
```json
|
||
{
|
||
"requests": [
|
||
{
|
||
"updateCellsRequest": { // ✅ 正确：必须是 "updateCellsRequest"
|
||
"range": {...},
|
||
"rows": [...]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 官方文档示例
|
||
|
||
根据官方文档，所有请求类型都遵循 `xxxRequest` 的命名规范：
|
||
|
||
### 示例 1：添加工作表
|
||
|
||
```json
|
||
{
|
||
"requests": [
|
||
{
|
||
"addSheetRequest": { // ✅ addSheetRequest
|
||
"title": "测试添加子表",
|
||
"rowCount": 10,
|
||
"columnCount": 10
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 示例 2：删除维度
|
||
|
||
```json
|
||
{
|
||
"requests": [
|
||
{
|
||
"deleteDimensionRequest": { // ✅ deleteDimensionRequest
|
||
"sheetId": "BB08J2",
|
||
"dimension": "COLUMN",
|
||
"startIndex": 1,
|
||
"endIndex": 3
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 示例 3：更新单元格（我们的场景）
|
||
|
||
```json
|
||
{
|
||
"requests": [
|
||
{
|
||
"updateCellsRequest": { // ✅ updateCellsRequest
|
||
"range": {
|
||
"sheetId": "BB08J2",
|
||
"startRowIndex": 2,
|
||
"endRowIndex": 3,
|
||
"startColumnIndex": 12,
|
||
"endColumnIndex": 13
|
||
},
|
||
"rows": [
|
||
{
|
||
"values": [
|
||
{
|
||
"cellValue": {
|
||
"text": "https://3.cn/2ume-Ak1"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 修复代码
|
||
|
||
### 修改前
|
||
|
||
```java
|
||
// ❌ 错误
|
||
JSONObject request = new JSONObject();
|
||
request.put("updateCells", updateCells); // 缺少 "Request" 后缀
|
||
requests.add(request);
|
||
```
|
||
|
||
### 修改后
|
||
|
||
```java
|
||
// ✅ 正确
|
||
JSONObject request = new JSONObject();
|
||
request.put("updateCellsRequest", updateCells); // 必须是 "updateCellsRequest"
|
||
requests.add(request);
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 请求类型命名规范
|
||
|
||
根据官方文档，常见的请求类型包括：
|
||
|
||
| 请求类型 | 正确名称 | 说明 |
|
||
|---------|---------|------|
|
||
| 添加工作表 | `addSheetRequest` | ✅ 以 Request 结尾 |
|
||
| 删除工作表 | `deleteSheetRequest` | ✅ 以 Request 结尾 |
|
||
| 更新单元格 | `updateCellsRequest` | ✅ 以 Request 结尾 |
|
||
| 删除维度 | `deleteDimensionRequest` | ✅ 以 Request 结尾 |
|
||
| 插入维度 | `insertDimensionRequest` | ✅ 以 Request 结尾 |
|
||
| 合并单元格 | `mergeCellsRequest` | ✅ 以 Request 结尾 |
|
||
|
||
**规律**：所有请求类型名称 = `{操作名称}Request`
|
||
|
||
---
|
||
|
||
## 🧪 验证结果
|
||
|
||
### 修复前（错误）
|
||
|
||
```
|
||
请求体: {"requests":[{"updateCells":{...}}]}
|
||
响应: {"code":400001, "message":"request name error"}
|
||
```
|
||
|
||
### 修复后（正确）
|
||
|
||
```
|
||
请求体: {"requests":[{"updateCellsRequest":{...}}]}
|
||
预期响应: {"ret":0, "msg":"Succeed", "data":{"replies":[]}}
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 修改文件清单
|
||
|
||
| 文件 | 修改内容 | 状态 |
|
||
|------|----------|------|
|
||
| `TencentDocApiUtil.java` | `updateCells` → `updateCellsRequest` | ✅ |
|
||
|
||
### 修改位置
|
||
|
||
```java
|
||
// 文件：TencentDocApiUtil.java
|
||
// 方法：writeSheetData()
|
||
// 行号：约 420 行
|
||
|
||
// 修改：
|
||
request.put("updateCellsRequest", updateCells); // ✅
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 预期效果
|
||
|
||
### 完整日志（修复后）
|
||
|
||
```
|
||
写入表格数据（batchUpdate）- range: M3, rowIndex: 2, colIndex: 12
|
||
请求体: {
|
||
"requests": [
|
||
{
|
||
"updateCellsRequest": {
|
||
"range": {
|
||
"sheetId": "BB08J2",
|
||
"startRowIndex": 2,
|
||
"endRowIndex": 3,
|
||
"startColumnIndex": 12,
|
||
"endColumnIndex": 13
|
||
},
|
||
"rows": [
|
||
{
|
||
"values": [
|
||
{
|
||
"cellValue": {
|
||
"text": "https://3.cn/2ume-Ak1"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
API响应状态码: 200
|
||
API响应: {"ret":0, "msg":"Succeed", "data":{"replies":[]}}
|
||
成功写入物流链接 - 单元格: M3, 单号: JY2025110329041 ✅
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 参考文档
|
||
|
||
- [在线表格批量更新接口](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)
|
||
|
||
---
|
||
|
||
## ⚠️ 关键提醒
|
||
|
||
### 1. 请求类型命名必须严格遵循规范
|
||
|
||
❌ **错误示例**：
|
||
```json
|
||
{
|
||
"requests": [
|
||
{"updateCells": {...}}, // 错误：缺少 Request
|
||
{"addSheet": {...}}, // 错误：缺少 Request
|
||
{"deleteDimension": {...}} // 错误：缺少 Request
|
||
]
|
||
}
|
||
```
|
||
|
||
✅ **正确示例**：
|
||
```json
|
||
{
|
||
"requests": [
|
||
{"updateCellsRequest": {...}}, // 正确
|
||
{"addSheetRequest": {...}}, // 正确
|
||
{"deleteDimensionRequest": {...}} // 正确
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 大小写敏感
|
||
|
||
- ✅ `updateCellsRequest` - 正确（驼峰命名）
|
||
- ❌ `UpdateCellsRequest` - 错误（首字母大写）
|
||
- ❌ `updatecellsrequest` - 错误（全小写）
|
||
- ❌ `update_cells_request` - 错误（下划线）
|
||
|
||
### 3. 字段名不能自定义
|
||
|
||
所有请求类型名称都由腾讯文档 API 官方定义，**不能自己创造或修改**。
|
||
|
||
---
|
||
|
||
## ✅ 总结
|
||
|
||
### 问题
|
||
使用了错误的字段名 `updateCells`，应该是 `updateCellsRequest`。
|
||
|
||
### 原因
|
||
腾讯文档 batchUpdate API 要求所有请求类型名称必须以 `Request` 结尾。
|
||
|
||
### 解决
|
||
将 `request.put("updateCells", ...)` 改为 `request.put("updateCellsRequest", ...)`。
|
||
|
||
### 结果
|
||
API 调用成功，物流链接正确写入表格！✅
|
||
|
||
---
|
||
|
||
**文档版本**：1.0
|
||
**创建时间**：2025-11-05
|
||
**依据**：腾讯文档开放平台官方 API 文档
|
||
**状态**：✅ 已修复
|
||
|