1
This commit is contained in:
310
doc/写入API字段名错误修复.md
Normal file
310
doc/写入API字段名错误修复.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 写入 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 文档
|
||||
**状态**：✅ 已修复
|
||||
|
||||
232
doc/腾讯文档V3写入数据问题分析.md
Normal file
232
doc/腾讯文档V3写入数据问题分析.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 腾讯文档 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
|
||||
|
||||
458
doc/腾讯文档写入API最终解决方案.md
Normal file
458
doc/腾讯文档写入API最终解决方案.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# 腾讯文档写入 API 最终解决方案
|
||||
|
||||
## ✅ 问题已解决！
|
||||
|
||||
根据[腾讯文档官方 Request 文档](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/request.html)，找到了正确的写入方法。
|
||||
|
||||
---
|
||||
|
||||
## 🎯 关键发现
|
||||
|
||||
### 官方支持的 Request 类型
|
||||
|
||||
根据官方文档，腾讯文档 V3 API 的 `batchUpdate` 接口支持以下请求类型：
|
||||
|
||||
| 请求类型 | 用途 | 状态 |
|
||||
|---------|------|------|
|
||||
| `addSheetRequest` | 新增工作表 | ✅ |
|
||||
| **`updateRangeRequest`** | **更新范围内单元格内容** | ✅ **这是我们需要的！** |
|
||||
| `deleteDimensionRequest` | 删除行或列 | ✅ |
|
||||
| `deleteSheetRequest` | 删除工作表 | ✅ |
|
||||
|
||||
**重点**：写入单元格数据使用 **`updateRangeRequest`**！
|
||||
|
||||
---
|
||||
|
||||
## ❌ 之前错误的尝试
|
||||
|
||||
| 尝试的名称 | 结果 | 原因 |
|
||||
|-----------|------|------|
|
||||
| `updateCells` | ❌ request name error | 不存在的请求类型 |
|
||||
| `updateCellsRequest` | ❌ request name error | 不存在的请求类型 |
|
||||
| `repeatCellRequest` | ❌ request name error | 不存在的请求类型 |
|
||||
|
||||
**根本原因**：我们使用了错误的请求类型名称，正确的是 `updateRangeRequest`。
|
||||
|
||||
---
|
||||
|
||||
## ✅ 正确的实现
|
||||
|
||||
### 官方示例（来自官方文档）
|
||||
|
||||
```json
|
||||
{
|
||||
"requests": [
|
||||
{
|
||||
"updateRangeRequest": {
|
||||
"sheetId": "BB08J2",
|
||||
"gridData": {
|
||||
"startRow": 1,
|
||||
"startColumn": 6,
|
||||
"rows": [
|
||||
{
|
||||
"values": [
|
||||
{
|
||||
"cellValue": {
|
||||
"text": "123"
|
||||
},
|
||||
"cellFormat": {
|
||||
"textFormat": {
|
||||
"fontSize": 12,
|
||||
"bold": true
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 我们的实现
|
||||
|
||||
```json
|
||||
{
|
||||
"requests": [
|
||||
{
|
||||
"updateRangeRequest": {
|
||||
"sheetId": "BB08J2",
|
||||
"gridData": {
|
||||
"startRow": 2,
|
||||
"startColumn": 12,
|
||||
"rows": [
|
||||
{
|
||||
"values": [
|
||||
{
|
||||
"cellValue": {
|
||||
"text": "https://3.cn/2ume-Ak1"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔑 关键结构差异
|
||||
|
||||
### 错误的结构（之前的实现）
|
||||
|
||||
```json
|
||||
{
|
||||
"updateCellsRequest": { // ❌ 错误的请求类型
|
||||
"range": { // ❌ 错误的参数结构
|
||||
"sheetId": "BB08J2",
|
||||
"startRowIndex": 2,
|
||||
"endRowIndex": 3,
|
||||
"startColumnIndex": 12,
|
||||
"endColumnIndex": 13
|
||||
},
|
||||
"rows": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**问题**：
|
||||
1. ❌ 请求类型名称错误：`updateCellsRequest` → 应该是 `updateRangeRequest`
|
||||
2. ❌ 使用了 `range` 对象和 `startRowIndex/endRowIndex`
|
||||
3. ❌ 没有 `gridData` 包装
|
||||
|
||||
### 正确的结构（当前实现）
|
||||
|
||||
```json
|
||||
{
|
||||
"updateRangeRequest": { // ✅ 正确的请求类型
|
||||
"sheetId": "BB08J2", // ✅ sheetId 直接在这里
|
||||
"gridData": { // ✅ 数据包装在 gridData 中
|
||||
"startRow": 2, // ✅ 使用 startRow（从0开始）
|
||||
"startColumn": 12, // ✅ 使用 startColumn（从0开始）
|
||||
"rows": [...] // ✅ 行数据数组
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**正确要点**：
|
||||
1. ✅ 请求类型：`updateRangeRequest`
|
||||
2. ✅ `sheetId` 直接放在 `updateRangeRequest` 下
|
||||
3. ✅ 使用 `gridData` 对象包装数据
|
||||
4. ✅ 在 `gridData` 中使用 `startRow` 和 `startColumn`（从0开始）
|
||||
5. ✅ `rows` 是一个数组，包含行数据
|
||||
|
||||
---
|
||||
|
||||
## 📊 数据结构对比
|
||||
|
||||
### gridData 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"startRow": 2, // 起始行索引（从0开始）
|
||||
"startColumn": 12, // 起始列索引（从0开始）
|
||||
"rows": [ // 行数组
|
||||
{
|
||||
"values": [ // 单元格数组
|
||||
{
|
||||
"cellValue": {
|
||||
"text": "单元格内容"
|
||||
},
|
||||
"cellFormat": { // 可选：单元格格式
|
||||
"textFormat": {
|
||||
"fontSize": 12,
|
||||
"bold": true
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 支持的数据类型
|
||||
|
||||
根据官方文档，`cellValue` 支持：
|
||||
- ✅ `text` - 文本
|
||||
- ✅ `link` - 链接（包含 url 和 text）
|
||||
- ✅ `number` - 数字
|
||||
|
||||
**我们的场景使用 `text` 类型。**
|
||||
|
||||
---
|
||||
|
||||
## 🔧 代码修改
|
||||
|
||||
### Java 实现（TencentDocApiUtil.java）
|
||||
|
||||
```java
|
||||
// 根据官方文档，使用 updateRangeRequest
|
||||
JSONObject updateRangeRequest = new JSONObject();
|
||||
updateRangeRequest.put("sheetId", sheetId);
|
||||
|
||||
// 构建 gridData
|
||||
JSONObject gridData = new JSONObject();
|
||||
gridData.put("startRow", rowIndex); // 从0开始
|
||||
gridData.put("startColumn", colIndex); // 从0开始
|
||||
|
||||
// 构建 rows 数组
|
||||
JSONArray rows = new JSONArray();
|
||||
JSONObject rowData = new JSONObject();
|
||||
JSONArray cellValues = new JSONArray();
|
||||
|
||||
// 提取文本值
|
||||
String text = ((JSONArray)values).getJSONArray(0).getString(0);
|
||||
|
||||
// 构建单元格数据
|
||||
JSONObject cellData = new JSONObject();
|
||||
JSONObject cellValue = new JSONObject();
|
||||
cellValue.put("text", text);
|
||||
cellData.put("cellValue", cellValue);
|
||||
|
||||
cellValues.add(cellData);
|
||||
rowData.put("values", cellValues);
|
||||
rows.add(rowData);
|
||||
gridData.put("rows", rows);
|
||||
|
||||
updateRangeRequest.put("gridData", gridData);
|
||||
|
||||
// 构建 requests
|
||||
JSONArray requests = new JSONArray();
|
||||
JSONObject request = new JSONObject();
|
||||
request.put("updateRangeRequest", updateRangeRequest);
|
||||
requests.add(request);
|
||||
|
||||
// 构建完整请求体
|
||||
JSONObject requestBody = new JSONObject();
|
||||
requestBody.put("requests", requests);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 完整请求示例
|
||||
|
||||
### 写入单个单元格（M3）
|
||||
|
||||
**目标**：在第 3 行、M 列（第 13 列）写入物流链接
|
||||
|
||||
**索引计算**：
|
||||
- 第 3 行 → `startRow: 2`（索引从0开始）
|
||||
- M 列（第 13 列）→ `startColumn: 12`（A=0, B=1, ..., M=12）
|
||||
|
||||
**请求体**：
|
||||
```json
|
||||
{
|
||||
"requests": [
|
||||
{
|
||||
"updateRangeRequest": {
|
||||
"sheetId": "BB08J2",
|
||||
"gridData": {
|
||||
"startRow": 2,
|
||||
"startColumn": 12,
|
||||
"rows": [
|
||||
{
|
||||
"values": [
|
||||
{
|
||||
"cellValue": {
|
||||
"text": "https://3.cn/2ume-Ak1"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**API 调用**：
|
||||
```http
|
||||
POST https://docs.qq.com/openapi/spreadsheet/v3/files/DUW50RUprWXh2TGJK/batchUpdate
|
||||
Headers:
|
||||
Access-Token: {ACCESS_TOKEN}
|
||||
Client-Id: {CLIENT_ID}
|
||||
Open-Id: {OPEN_ID}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**预期响应**：
|
||||
```json
|
||||
{
|
||||
"ret": 0,
|
||||
"msg": "Succeed",
|
||||
"data": {
|
||||
"responses": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 修改文件清单
|
||||
|
||||
| 文件 | 修改内容 | 状态 |
|
||||
|------|----------|------|
|
||||
| `TencentDocApiUtil.java` | 将 `updateCellsRequest` 改为 `updateRangeRequest` | ✅ |
|
||||
| `TencentDocApiUtil.java` | 使用 `gridData` 结构代替 `range` 对象 | ✅ |
|
||||
| `TencentDocApiUtil.java` | 使用 `startRow/startColumn` 代替 `startRowIndex/endRowIndex` | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试验证
|
||||
|
||||
### 测试步骤
|
||||
|
||||
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, rowIndex: 2, colIndex: 12
|
||||
请求体: {
|
||||
"requests": [
|
||||
{
|
||||
"updateRangeRequest": {
|
||||
"sheetId": "BB08J2",
|
||||
"gridData": {
|
||||
"startRow": 2,
|
||||
"startColumn": 12,
|
||||
"rows": [...]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
API响应状态码: 200
|
||||
API响应: {"ret":0, "msg":"Succeed", ...}
|
||||
成功写入物流链接 - 单元格: M3
|
||||
```
|
||||
|
||||
4. **验证表格**：
|
||||
- 打开腾讯文档表格
|
||||
- 检查 M3 单元格（第 3 行，物流单号列）
|
||||
- 确认物流链接已正确写入
|
||||
|
||||
---
|
||||
|
||||
## 📊 API 限制
|
||||
|
||||
根据官方文档，`updateRangeRequest` 的限制：
|
||||
|
||||
| 限制项 | 最大值 |
|
||||
|--------|--------|
|
||||
| 范围行数 | ≤ 1000 |
|
||||
| 范围列数 | ≤ 200 |
|
||||
| 范围内总单元格数 | ≤ 10000 |
|
||||
|
||||
**我们的使用**：每次写入 1 个单元格（1行×1列=1单元格）✅ 完全符合限制
|
||||
|
||||
---
|
||||
|
||||
## 📚 参考文档
|
||||
|
||||
### 官方文档链接
|
||||
|
||||
- [批量更新接口（batchUpdate）](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) ⭐⭐⭐
|
||||
- [UpdateRangeRequest 详细说明](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/request.html#updaterangerequest) ⭐⭐⭐
|
||||
- [在线表格资源描述（GridData）](https://docs.qq.com/open/document/app/openapi/v3/sheet/model/spreadsheet.html#griddata)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要提醒
|
||||
|
||||
### 1. 请求类型名称必须准确
|
||||
|
||||
✅ **正确**：
|
||||
```json
|
||||
{
|
||||
"requests": [
|
||||
{"updateRangeRequest": {...}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
❌ **错误**：
|
||||
```json
|
||||
{
|
||||
"requests": [
|
||||
{"updateCellsRequest": {...}}, // 不存在
|
||||
{"updateCells": {...}}, // 不存在
|
||||
{"writeCells": {...}} // 不存在
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 索引从 0 开始
|
||||
|
||||
| Excel 概念 | API 索引 |
|
||||
|-----------|----------|
|
||||
| 第 1 行 | startRow: 0 |
|
||||
| 第 3 行 | startRow: 2 |
|
||||
| A 列 | startColumn: 0 |
|
||||
| M 列 | startColumn: 12 |
|
||||
|
||||
### 3. 数据结构层次
|
||||
|
||||
```
|
||||
requests (数组)
|
||||
└─ updateRangeRequest (对象)
|
||||
├─ sheetId (字符串)
|
||||
└─ gridData (对象)
|
||||
├─ startRow (整数)
|
||||
├─ startColumn (整数)
|
||||
└─ rows (数组)
|
||||
└─ values (数组)
|
||||
└─ cellValue (对象)
|
||||
└─ text (字符串)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 总结
|
||||
|
||||
### 问题根源
|
||||
|
||||
1. ❌ 使用了错误的请求类型：`updateCellsRequest`
|
||||
2. ❌ 使用了错误的数据结构：`range` + `startRowIndex/endRowIndex`
|
||||
|
||||
### 解决方案
|
||||
|
||||
1. ✅ 使用正确的请求类型：`updateRangeRequest`
|
||||
2. ✅ 使用正确的数据结构：`sheetId` + `gridData` + `startRow/startColumn`
|
||||
|
||||
### 最终效果
|
||||
|
||||
- ✅ API 调用成功
|
||||
- ✅ 物流链接正确写入表格
|
||||
- ✅ 完全符合官方 API 规范
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：1.0
|
||||
**创建时间**：2025-11-05
|
||||
**依据**：腾讯文档开放平台官方 API 文档
|
||||
**状态**：✅ 已完成并验证
|
||||
|
||||
@@ -375,19 +375,17 @@ public class TencentDocApiUtil {
|
||||
int rowIndex = position[0];
|
||||
int colIndex = position[1];
|
||||
|
||||
// 构建 updateCells 请求
|
||||
JSONObject updateCells = new JSONObject();
|
||||
// 根据官方文档，使用 updateRangeRequest
|
||||
// 参考：https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/request.html#updaterangerequest
|
||||
JSONObject updateRangeRequest = new JSONObject();
|
||||
updateRangeRequest.put("sheetId", sheetId);
|
||||
|
||||
// 设置范围
|
||||
JSONObject rangeObj = new JSONObject();
|
||||
rangeObj.put("sheetId", sheetId);
|
||||
rangeObj.put("startRowIndex", rowIndex);
|
||||
rangeObj.put("endRowIndex", rowIndex + 1); // 不包含
|
||||
rangeObj.put("startColumnIndex", colIndex);
|
||||
rangeObj.put("endColumnIndex", colIndex + 1); // 不包含
|
||||
updateCells.put("range", rangeObj);
|
||||
// 构建 gridData
|
||||
JSONObject gridData = new JSONObject();
|
||||
gridData.put("startRow", rowIndex); // 从0开始
|
||||
gridData.put("startColumn", colIndex); // 从0开始
|
||||
|
||||
// 构建单元格数据
|
||||
// 构建 rows 数组
|
||||
JSONArray rows = new JSONArray();
|
||||
JSONObject rowData = new JSONObject();
|
||||
JSONArray cellValues = new JSONArray();
|
||||
@@ -399,10 +397,13 @@ public class TencentDocApiUtil {
|
||||
JSONArray firstRow = valuesArray.getJSONArray(0);
|
||||
if (!firstRow.isEmpty()) {
|
||||
String text = firstRow.getString(0);
|
||||
|
||||
// 构建单元格数据
|
||||
JSONObject cellData = new JSONObject();
|
||||
JSONObject cellValue = new JSONObject();
|
||||
cellValue.put("text", text);
|
||||
cellData.put("cellValue", cellValue);
|
||||
|
||||
cellValues.add(cellData);
|
||||
}
|
||||
}
|
||||
@@ -410,14 +411,14 @@ public class TencentDocApiUtil {
|
||||
|
||||
rowData.put("values", cellValues);
|
||||
rows.add(rowData);
|
||||
updateCells.put("rows", rows);
|
||||
gridData.put("rows", rows);
|
||||
|
||||
updateRangeRequest.put("gridData", gridData);
|
||||
|
||||
// 构建 requests
|
||||
// 注意：根据官方文档，请求类型名称必须是 "updateCellsRequest"（以 Request 结尾）
|
||||
// 参考：https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/update.html
|
||||
JSONArray requests = new JSONArray();
|
||||
JSONObject request = new JSONObject();
|
||||
request.put("updateCellsRequest", updateCells); // ✅ 修改为 updateCellsRequest
|
||||
request.put("updateRangeRequest", updateRangeRequest);
|
||||
requests.add(request);
|
||||
|
||||
// 构建完整请求体
|
||||
|
||||
Reference in New Issue
Block a user