123 lines
3.9 KiB
Markdown
123 lines
3.9 KiB
Markdown
# 腾讯文档 API 404 问题诊断与修复
|
||
|
||
## 问题现象
|
||
调用腾讯文档 API 时返回 404 Not Found 错误：
|
||
```
|
||
Caused by: java.lang.RuntimeException: 请求被代理拦截，返回了HTML页面。请检查系统代理设置或网络配置。响应: <html><head><title>404 Not Found</title></head><body><center><h1>404 Not Found</h1></center><hr><center>nginx</center></body></html>
|
||
```
|
||
|
||
## 可能的原因分析
|
||
|
||
### 1. API 基础 URL 可能不正确
|
||
|
||
我们当前使用的基础 URL 是：`https://docs.qq.com/openapi/v3`
|
||
|
||
但根据腾讯文档API的文档路径结构，可能的正确基础 URL 有以下几种：
|
||
|
||
| 候选URL | 说明 |
|
||
|---------|------|
|
||
| `https://docs.qq.com/open/api/v3` | 推测1：/open/api/v3 |
|
||
| `https://docs.qq.com/openapi/v3` | 推测2：/openapi/v3（当前使用）|
|
||
| `https://docs.qq.com/v3` | 推测3：直接 /v3 |
|
||
| `https://api.docs.qq.com/v3` | 推测4：使用 api 子域名 |
|
||
|
||
### 2. 可能需要使用不同的接口路径
|
||
|
||
腾讯文档 V3 API 可能不支持直接的 REST 风格的 ranges 路径，而是使用：
|
||
- **批量更新接口（batchUpdate）**：用于写入数据
|
||
- **批量查询接口（getGridData 或类似）**：用于读取数据
|
||
|
||
## 诊断步骤
|
||
|
||
### 步骤1：测试不同的基础 URL
|
||
|
||
建议创建一个测试方法，尝试不同的基础URL：
|
||
|
||
```java
|
||
// 测试代码示例
|
||
public void testApiBaseUrls() {
|
||
String[] candidateUrls = {
|
||
"https://docs.qq.com/open/api/v3",
|
||
"https://docs.qq.com/openapi/v3",
|
||
"https://docs.qq.com/v3",
|
||
"https://api.docs.qq.com/v3"
|
||
};
|
||
|
||
for (String baseUrl : candidateUrls) {
|
||
try {
|
||
String testUrl = baseUrl + "/spreadsheets/{fileId}";
|
||
log.info("测试URL: {}", testUrl);
|
||
// 发送GET请求测试
|
||
JSONObject result = callApi(accessToken, testUrl, "GET", null);
|
||
log.info("成功！正确的基础URL是: {}", baseUrl);
|
||
return;
|
||
} catch (Exception e) {
|
||
log.warn("URL {} 失败: {}", baseUrl, e.getMessage());
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 步骤2：检查腾讯文档开放平台的实际API文档
|
||
|
||
访问以下链接查看实际的API调用示例：
|
||
1. 腾讯文档开放平台首页：https://docs.qq.com/open/
|
||
2. 开发文档总览：https://docs.qq.com/open/document/app/
|
||
3. 查找实际的API调用示例（cURL命令或SDK示例）
|
||
|
||
### 步骤3：检查是否需要使用 batchUpdate 接口
|
||
|
||
如果直接的 ranges 路径不可用，可能需要使用批量操作接口：
|
||
|
||
**读取数据**可能需要使用类似的接口：
|
||
- POST `/open/api/v3/spreadsheets/{fileId}:getGridData`
|
||
- 或 POST `/open/api/v3/spreadsheets/{fileId}/values:batchGet`
|
||
|
||
**写入数据**可能需要使用：
|
||
- POST `/open/api/v3/spreadsheets/{fileId}:batchUpdate`
|
||
- 或 POST `/open/api/v3/spreadsheets/{fileId}/values:batchUpdate`
|
||
|
||
## 临时解决方案
|
||
|
||
### 方案1：修改基础URL为 /open/api/v3
|
||
|
||
尝试修改配置：
|
||
|
||
```yaml
|
||
# application-dev.yml 和 application-prod.yml
|
||
tencent:
|
||
doc:
|
||
api-base-url: https://docs.qq.com/open/api/v3
|
||
```
|
||
|
||
```java
|
||
// TencentDocConfig.java
|
||
private String apiBaseUrl = "https://docs.qq.com/open/api/v3";
|
||
```
|
||
|
||
### 方案2：联系腾讯文档技术支持
|
||
|
||
由于官方文档可能没有详细的API调用示例，建议：
|
||
1. 在腾讯文档开放平台提交工单
|
||
2. 咨询实际的API基础URL和调用方式
|
||
3. 获取完整的API调用示例代码
|
||
|
||
## 后续行动
|
||
|
||
1. 首先尝试修改基础URL为 `/open/api/v3`
|
||
2. 如果仍然404，需要查看腾讯文档开放平台控制台的SDK示例或API文档
|
||
3. 考虑使用腾讯文档提供的官方SDK（如果有）
|
||
4. 联系腾讯文档技术支持获取准确的API地址
|
||
|
||
## 参考信息
|
||
|
||
- 文档页面路径：`/open/document/app/openapi/v3/...`（这是文档站点）
|
||
- 可能的API路径：`/open/api/v3/...`（这可能是实际API）
|
||
- 当前使用路径：`/openapi/v3/...`（返回404）
|
||
|
||
---
|
||
|
||
**更新时间**：2025-11-05
|
||
**状态**：待测试验证
|
||
|