WPS to MySQL - N8N Plugin

将金山WPS多维表数据增量导入到MySQL数据库的N8N插件。

功能特性

• 🔄 增量导入：基于唯一键自动检测已存在数据，仅导入新数据
• 📊 批量处理：支持大数据量的分批插入，提高效率
• 📅 日期字段处理：自动格式化日期字段为 YYYY-MM-DD 格式
• 🔒 字段过滤：仅导入指定的字段，保证数据安全
• ⚡ 性能优化：批量查询已存在键，减少数据库压力
• 📝 详细日志：记录每个步骤的执行情况

安装

npm install @huisir/n8n-nodes-wps-to-mysql

配置说明

必填参数

1. WPS API URL - WPS多维表API地址

   https://www.kdocs.cn/api/v3/ide/file/xxx/script/xxx/sync_task

2. Target Table - MySQL目标表名（格式：database.table）

   tb_isp_business.agency_merchant_daily

3. Unique Key Fields - 唯一键字段（逗号分隔，用于增量导入）

   日期,商家ID

4. Allowed Fields - 允许导入的字段（逗号分隔）

   日期,商家ID,商家昵称,综合体验分,商品体验分

可选参数

1. Date Fields - 日期字段（需要格式化为 YYYY-MM-DD 的字段）

   日期,首次开播日期,首次开店日期

2. Options

   • Batch Size (默认: 1000) - 每批插入的行数
   • Request Timeout (默认: 30000ms) - WPS API请求超时时间
   • API Parameters (JSON格式) - 传递给WPS API的额外参数

     {"import_date": "2025-12-08"}

   • Enable Debug (默认: false) - 启用调试输出

凭据配置

插件需要两个凭据：

1. MySQL API - MySQL数据库连接信息

   • Host
   • Port
   • User
   • Password
   • Connect Timeout

2. WPS API Token - WPS API认证令牌

   • Token (AirScript-Token)

工作流程

1. 从WPS获取数据 - 调用WPS API获取多维表数据
2. 数据处理 - 解析表头和数据行，过滤允许的字段
3. 日期格式化 - 将日期字段转换为标准格式
4. 查询已存在键 - 从MySQL查询已存在的唯一键
5. 过滤增量数据 - 仅保留不存在于数据库的数据
6. 批量插入 - 分批将增量数据插入MySQL

返回结果

{
  "success": true,
  "wpsTotal": 1000,
  "dbExisting": 800,
  "incrementalCount": 200,
  "importedRows": 200,
  "totalBatches": 1,
  "message": "Successfully imported 200 rows in 1 batches",
  "duration": 5432
}

使用示例

基础用法

WPS API URL: https://www.kdocs.cn/api/v3/ide/file/xxx/script/xxx/sync_task
Target Table: tb_isp_business.agency_merchant_daily
Unique Key Fields: 日期,商家ID
Allowed Fields: 日期,商家ID,商家昵称,综合体验分,商品体验分,物流体验分,咨询体验分
Date Fields: 日期,首次开播日期,首次开店日期

带参数的用法

在Options中设置API Parameters：

{
  "import_date": "2025-12-08"
}

这会将参数传递给WPS API，用于筛选特定日期的数据。

与Python版本的对应关系

本插件基于以下Python脚本的功能开发：

• receive/merchant_daily.py - 商家每日数据增量导入
• receive/merchant_detail.py - 商家基础信息增量导入
• libs/wps_fetcher.py - WPS数据获取器

注意事项

1. 唯一键必须完整 - 确保WPS数据中唯一键字段都有值
2. 字段名大小写敏感 - 字段名必须与WPS表头完全匹配
3. 日期格式 - 支持多种日期格式输入，自动转换为YYYY-MM-DD
4. 批量大小 - 根据数据量和网络情况调整批量大小
5. 超时设置 - WPS API可能需要较长时间处理，适当增加超时时间

错误处理

• WPS API请求失败会抛出详细错误信息
• MySQL连接失败会自动关闭连接
• 批量插入失败会记录失败批次
• 启用 "Continue On Fail" 可以忽略错误继续执行

License

MIT

Author

huisir