178 lines
4.6 KiB
Markdown
178 lines
4.6 KiB
Markdown
|
# 飞书数据同步工具
|
|||
|
|
|
|||
|
|
这个工具提供了与飞书多维表格进行数据同步的功能，支持双向同步：从飞书导入数据到数据库，以及从数据库导出数据到飞书。同时支持将达人数据同步到外部知识库。
|
|||
|
|
|
|||
|
|
## 功能特点
|
|||
|
|
|
|||
|
|
- 从飞书多维表格导入数据到数据库
|
|||
|
|
- 从Excel文件更新数据库记录
|
|||
|
|
- 从数据库导出数据到飞书多维表格
|
|||
|
|
- 从特定数据库模型导入数据到飞书
|
|||
|
|
- 从自定义SQL查询导入数据到飞书
|
|||
|
|
- 将达人信息同步到外部知识库
|
|||
|
|
- 支持Gmail和飞书达人信息的统一管理
|
|||
|
|
- 支持自定义字段映射
|
|||
|
|
- 支持记录过滤和数量限制
|
|||
|
|
|
|||
|
|
## 使用方法
|
|||
|
|
|
|||
|
|
### 显示帮助信息
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py help
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 从飞书导入数据到数据库
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py sync_from_feishu
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 从Excel文件更新数据库记录
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py update_from_excel <excel文件路径>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 从数据库导出数据到飞书多维表格
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py export_to_feishu [--handle 关键字] [--limit 数量]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
例如，导出Handle包含"tiktok"的前10条记录：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py export_to_feishu --handle tiktok --limit 10
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 从特定数据库模型导入数据到飞书
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py import_from_db <模型名称> [--filters 字段1=值1,字段2=值2,...] [--limit 数量]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
支持的模型：
|
|||
|
|
- Data：数据模型
|
|||
|
|
- KnowledgeBase：知识库模型
|
|||
|
|
- FeishuCreator：飞书创作者模型
|
|||
|
|
|
|||
|
|
例如，导入技术部的管理员数据：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py import_from_db Data --filters type=admin,department=技术部 --limit 50
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 从自定义SQL查询导入数据到飞书
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py custom_import <sql_file>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
SQL文件格式示例：
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
-- 查询语句
|
|||
|
|
SELECT id, name, type FROM your_table WHERE condition;
|
|||
|
|
|
|||
|
|
-- FIELD_MAPPING:
|
|||
|
|
{
|
|||
|
|
"id": "飞书ID字段",
|
|||
|
|
"name": "飞书名称字段",
|
|||
|
|
"type": "飞书类型字段"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 将达人信息同步到知识库
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py sync_to_kb --id <creator_id> | --handle <handle> | --email <email>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
例如，同步特定达人信息到知识库：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python feishu.py sync_to_kb --handle tiktok_user123
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 示例
|
|||
|
|
|
|||
|
|
在`examples`目录中提供了几个示例文件：
|
|||
|
|
|
|||
|
|
- `custom_query.sql`：自定义SQL查询示例，包含字段映射
|
|||
|
|
- `creator_kb_query.sql`：查询达人信息并检查知识库映射的SQL示例
|
|||
|
|
- `sample_data_template.txt`：Excel导入模板说明
|
|||
|
|
|
|||
|
|
## REST API接口
|
|||
|
|
|
|||
|
|
除了命令行工具外，还提供了以下REST API接口：
|
|||
|
|
|
|||
|
|
### 1. 飞书数据同步API
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/feishu/sync
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
参数：
|
|||
|
|
- `sync_type` (可选)：同步类型，默认为"all"
|
|||
|
|
- `handle` (可选)：指定特定的达人Handle
|
|||
|
|
- `create_kb` (可选)：是否创建知识库，默认为false
|
|||
|
|
|
|||
|
|
### 2. 达人信息同步到知识库API
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/feishu/to_kb
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
参数：
|
|||
|
|
- `creator_id`、`handle`或`email`：至少提供一个参数用于识别达人
|
|||
|
|
|
|||
|
|
### 3. 检查达人知识库API
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/feishu/check_kb
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
参数：
|
|||
|
|
- `creator_id`、`handle`或`email`：至少提供一个参数用于识别达人
|
|||
|
|
|
|||
|
|
## 与Gmail集成
|
|||
|
|
|
|||
|
|
本工具支持与Gmail系统集成，实现达人信息的统一管理：
|
|||
|
|
|
|||
|
|
1. 当通过飞书同步达人信息到知识库时，会检查该达人是否已有Gmail映射
|
|||
|
|
2. 如果该达人邮箱已有Gmail映射，则使用现有知识库
|
|||
|
|
3. 如果没有映射，则创建新的知识库并建立映射关系
|
|||
|
|
4. 知识库文档采用追加模式，保留历史记录
|
|||
|
|
|
|||
|
|
## 配置
|
|||
|
|
|
|||
|
|
飞书API配置位于代码中，包括：
|
|||
|
|
|
|||
|
|
- APP_TOKEN：飞书应用的AppToken
|
|||
|
|
- TABLE_ID：飞书多维表格的TableID
|
|||
|
|
- USER_ACCESS_TOKEN：用户访问令牌
|
|||
|
|
|
|||
|
|
如需修改这些配置，请编辑相应的函数中的变量。
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. 确保已安装所需的依赖：`lark_oapi`, `pandas`, `django`等
|
|||
|
|
2. 在执行数据库操作前，确保数据库连接已正确配置
|
|||
|
|
3. 自定义SQL查询应避免执行修改数据的操作(INSERT, UPDATE, DELETE等)
|
|||
|
|
4. 导入大量数据时，可能需要分批处理，使用`--limit`参数控制数量
|
|||
|
|
5. 创建知识库需要管理员权限，确保有可用的管理员账号
|
|||
|
|
|
|||
|
|
## 常见问题
|
|||
|
|
|
|||
|
|
### Q: 导入数据时出现字段不匹配错误？
|
|||
|
|
|
|||
|
|
A: 确保字段名称与飞书多维表格中的字段名称完全匹配，或使用字段映射功能。
|
|||
|
|
|
|||
|
|
### Q: 如何添加新的数据模型支持？
|
|||
|
|
|
|||
|
|
A: 在`import_from_database_to_feishu`函数中添加新的模型映射，并按照现有模式实现字段映射逻辑。
|
|||
|
|
|
|||
|
|
### Q: 如何处理Gmail和飞书同一个达人的数据合并？
|
|||
|
|
|
|||
|
|
A: 系统会自动检查达人邮箱，如果在Gmail中已有映射，会使用同一个知识库，避免重复创建。
|