241 lines
6.0 KiB
Markdown
241 lines
6.0 KiB
Markdown
# 腾讯文档 API 鉴权修复指南
|
||
|
||
## 关键发现
|
||
|
||
根据腾讯文档官方 API 文档，发现了之前鉴权方式的重大错误：
|
||
|
||
### 正确的鉴权方式
|
||
|
||
腾讯文档 V3 API 需要**三个请求头**进行鉴权：
|
||
|
||
```http
|
||
Access-Token: {访问令牌}
|
||
Client-Id: {应用ID}
|
||
Open-Id: {开放平台用户ID}
|
||
```
|
||
|
||
**而不是**：
|
||
```http
|
||
Authorization: Bearer {访问令牌} ❌ 错误！
|
||
```
|
||
|
||
## 推荐方案：使用应用级账号 Token
|
||
|
||
### 什么是应用级账号 Token？
|
||
|
||
- 不需要用户授权流程
|
||
- 直接使用 `client_id` 和 `client_secret` 获取
|
||
- 响应包含所有需要的信息
|
||
|
||
### API 接口
|
||
|
||
**请求：**
|
||
```http
|
||
GET https://docs.qq.com/oauth/v2/app-account-token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"access_token": "ACCESSTOKENEXAMPLE",
|
||
"token_type": "Bearer",
|
||
"refresh_token": "REFRESHTOKENEXAMPLE",
|
||
"expires_in": 259200,
|
||
"scope": "scope.file.editable,scope.folder.creatable",
|
||
"user_id": "bcb50c8a4b724d86bbcf6fc64c5e2b22"
|
||
}
|
||
```
|
||
|
||
### 字段映射
|
||
|
||
| 响应字段 | 对应请求头 | 说明 |
|
||
|---------|-----------|------|
|
||
| `access_token` | `Access-Token` | 访问令牌 |
|
||
| 请求参数 `client_id` | `Client-Id` | 应用ID |
|
||
| `user_id` | `Open-Id` | 开放平台用户ID（关键！） |
|
||
|
||
## 完整的 API 调用流程
|
||
|
||
### 步骤1：获取应用级账号 Token
|
||
|
||
```java
|
||
JSONObject tokenInfo = TencentDocApiUtil.getAppAccountToken(appId, appSecret);
|
||
|
||
String accessToken = tokenInfo.getString("access_token");
|
||
String openId = tokenInfo.getString("user_id"); // 这就是 Open-Id！
|
||
String clientId = appId; // Client-Id 就是 appId
|
||
```
|
||
|
||
### 步骤2：调用业务 API
|
||
|
||
```java
|
||
// 设置请求头
|
||
conn.setRequestProperty("Access-Token", accessToken);
|
||
conn.setRequestProperty("Client-Id", clientId);
|
||
conn.setRequestProperty("Open-Id", openId);
|
||
conn.setRequestProperty("Content-Type", "application/json");
|
||
```
|
||
|
||
### 步骤3：发送请求
|
||
|
||
```http
|
||
GET https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/A1:Z100
|
||
Access-Token: ACCESSTOKENEXAMPLE
|
||
Client-Id: YOUR_CLIENT_ID
|
||
Open-Id: bcb50c8a4b724d86bbcf6fc64c5e2b22
|
||
Content-Type: application/json
|
||
```
|
||
|
||
## 代码修改方案
|
||
|
||
### 方案 A：简单封装（推荐）
|
||
|
||
在 Service 层创建一个包装类来管理鉴权信息：
|
||
|
||
```java
|
||
public class TencentDocAuth {
|
||
private String accessToken;
|
||
private String clientId;
|
||
private String openId;
|
||
private long expiresAt;
|
||
|
||
// 获取或刷新 Token
|
||
public static TencentDocAuth getAuth(String appId, String appSecret) {
|
||
JSONObject tokenInfo = TencentDocApiUtil.getAppAccountToken(appId, appSecret);
|
||
|
||
TencentDocAuth auth = new TencentDocAuth();
|
||
auth.accessToken = tokenInfo.getString("access_token");
|
||
auth.openId = tokenInfo.getString("user_id");
|
||
auth.clientId = appId;
|
||
auth.expiresAt = System.currentTimeMillis() + tokenInfo.getIntValue("expires_in") * 1000;
|
||
|
||
return auth;
|
||
}
|
||
|
||
// Getters...
|
||
}
|
||
```
|
||
|
||
### 方案 B：修改现有方法签名
|
||
|
||
修改 `callApi` 方法，添加必要的参数：
|
||
|
||
```java
|
||
public static JSONObject callApi(String accessToken, String clientId, String openId,
|
||
String apiUrl, String method, String body) {
|
||
conn.setRequestProperty("Access-Token", accessToken);
|
||
conn.setRequestProperty("Client-Id", clientId);
|
||
conn.setRequestProperty("Open-Id", openId);
|
||
// ...
|
||
}
|
||
```
|
||
|
||
然后更新所有调用此方法的地方。
|
||
|
||
## 实现步骤
|
||
|
||
### 1. 添加获取应用级账号 Token 的方法 ✅
|
||
|
||
已在 `TencentDocApiUtil.java` 中添加：
|
||
```java
|
||
public static JSONObject getAppAccountToken(String appId, String appSecret)
|
||
```
|
||
|
||
### 2. 修改 callApi 方法 ✅
|
||
|
||
已更新为：
|
||
```java
|
||
public static JSONObject callApi(String accessToken, String clientId, String openId,
|
||
String apiUrl, String method, String body)
|
||
```
|
||
|
||
### 3. 更新所有调用点（待完成）
|
||
|
||
需要更新以下方法：
|
||
- `readSheetData()`
|
||
- `writeSheetData()`
|
||
- `appendSheetData()`
|
||
- `getFileInfo()`
|
||
- `getSheetList()`
|
||
|
||
以及所有调用这些方法的 Service 类。
|
||
|
||
## 测试验证
|
||
|
||
### 1. 获取应用级账号 Token
|
||
|
||
```java
|
||
JSONObject tokenInfo = TencentDocApiUtil.getAppAccountToken(
|
||
"YOUR_CLIENT_ID",
|
||
"YOUR_CLIENT_SECRET"
|
||
);
|
||
|
||
System.out.println("Access Token: " + tokenInfo.getString("access_token"));
|
||
System.out.println("Open-Id: " + tokenInfo.getString("user_id"));
|
||
```
|
||
|
||
### 2. 调用表格 API
|
||
|
||
```java
|
||
String accessToken = tokenInfo.getString("access_token");
|
||
String clientId = "YOUR_CLIENT_ID";
|
||
String openId = tokenInfo.getString("user_id");
|
||
|
||
JSONObject result = TencentDocApiUtil.readSheetData(
|
||
accessToken, clientId, openId,
|
||
"YOUR_FILE_ID", "SHEET_ID", "A1:Z10",
|
||
"https://docs.qq.com/openapi/spreadsheet/v3"
|
||
);
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
### 1. Token 有效期
|
||
|
||
应用级账号 Token 默认有效期为 3 天（259200秒），需要定期刷新。
|
||
|
||
### 2. 存储安全
|
||
|
||
- `client_secret` 必须保密
|
||
- Token 应该缓存并在过期前刷新
|
||
- 不要在日志中打印完整的 Token
|
||
|
||
### 3. 权限范围
|
||
|
||
应用级账号的权限取决于申请时的 scope：
|
||
- `scope.sheet` - 读取表格
|
||
- `scope.sheet.editable` - 编辑表格
|
||
- `scope.file.editable` - 编辑文件
|
||
- `scope.folder.creatable` - 创建文件夹
|
||
|
||
## 错误排查
|
||
|
||
### 401 Unauthorized
|
||
|
||
- 检查 Access-Token 是否正确
|
||
- 检查 Token 是否过期
|
||
- 检查是否包含所有三个请求头
|
||
|
||
### 403 Forbidden
|
||
|
||
- 检查应用是否有相应的权限 (scope)
|
||
- 检查 Open-Id 是否正确
|
||
|
||
### 404 Not Found
|
||
|
||
- 检查 URL 路径是否正确
|
||
- 确认基础 URL 为 `https://docs.qq.com/openapi/spreadsheet/v3`
|
||
- 确认路径格式为 `/files/{fileId}/...`
|
||
|
||
## 参考文档
|
||
|
||
- [批量更新接口](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchUpdate.html)
|
||
- [获取应用级账号 Token](https://docs.qq.com/open/document/app/oauth2/app-account-token.html)
|
||
- [请求头部说明](https://docs.qq.com/open/document/app/openapi/v3/)
|
||
|
||
---
|
||
|
||
**更新时间**：2025-11-05
|
||
**状态**：部分完成，需要更新所有调用点
|
||
|