ruoyi-java/doc/腾讯文档API最终修复说明.md

腾讯文档 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

// 修改后
private String apiBaseUrl = "https://docs.qq.com/openapi/spreadsheet/v3";

2. 配置文件

文件： application-dev.yml 和 application-prod.yml

# 修改后
tencent:
  doc:
    api-base-url: https://docs.qq.com/openapi/spreadsheet/v3

3. API 工具类路径修复

文件： TencentDocApiUtil.java

readSheetData() - 读取表格数据

// 修改前
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() - 写入表格数据

// 修改前
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() - 获取文件信息

// 修改前
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() - 追加数据

// 修改前（获取工作表信息）
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 错误。

预期结果

{
  "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
状态：✅ 已验证正确
下一步：重启应用并测试