273 lines
12 KiB
Markdown
273 lines
12 KiB
Markdown
# datasource — 数据源同步管理
|
||
|
||
将外部数据源（当前仅支持 OA 审批）同步到 AI 表格。完整链路：list-sources → (OA) 选择模板 → get-fields → create → sync-status → sync / update / get-config。
|
||
|
||
## 命令一览
|
||
|
||
| 命令 | 用途 | 读/写 |
|
||
|------|------|-------|
|
||
| `+datasource-list-sources` | 列出可用数据源条目，获取 processCode/name/iconUrl/url | 读 |
|
||
| `+datasource-get-fields` | 获取可同步字段列表，用于决定 field-ids | 读 |
|
||
| `+datasource-create` | 创建数据源表并触发首次全量同步 | 写 |
|
||
| `+datasource-update` | 更新已有数据源表的同步配置 | 写 |
|
||
| `+datasource-sync` | 手动触发一次同步（最多 5 张表） | 写 |
|
||
| `+datasource-sync-status` | 查询同步任务状态（RUNNING/FINISHED/FAILED） | 读 |
|
||
| `+datasource-get-config` | 获取数据源表当前同步配置 | 读 |
|
||
|
||
## 典型工作流
|
||
|
||
```
|
||
Step 0 列出可用来源 +datasource-list-sources --base-id <B> --datasource-type OA
|
||
→ 返回 approvals 数组（通常含多个审批模板）
|
||
|
||
Step 0.5 (OA 审批) 选择模板 list-sources 返回的 approvals 数组通常含多个审批模板，需确定目标：
|
||
- 用户已指定名称（如"采购申请"）→ 按 name 精确/模糊匹配
|
||
· 唯一命中 → 提取该条的 processCode/name/iconUrl/url，继续
|
||
· 多候选 → 列出匹配项让用户消歧
|
||
· 零命中 → 停止，提示用户确认名称或从完整列表选择
|
||
- 用户未指定 → 列出候选模板清单（name + processCode），等用户选择
|
||
- 禁止：未匹配直接选第一项、或凭记忆猜 processCode
|
||
注：此步骤针对 OA 审批数据源（多模板场景）；其他数据源类型的
|
||
list-sources 返回结构可能不同，按实际 result 解析即可，
|
||
不一定需要选择步骤。
|
||
|
||
Step 1 (可选) 获取可同步字段 +datasource-get-fields --base-id <B> --datasource-type OA --source-config '<JSON>'
|
||
→ 决定需要同步哪些字段，得到 field-ids
|
||
|
||
Step 2 创建数据源 +datasource-create --base-id <B> --datasource-type OA --source-config '<JSON>'
|
||
→ sourceConfig 中的 processCode/name/iconUrl/url 来自 Step 0.5 选中的模板
|
||
→ 返回 tableId + taskId
|
||
|
||
Step 3 查询同步结果 +datasource-sync-status --base-id <B> --table-id <T> --task-ids <TASK_ID>
|
||
→ FINISHED=完成，FAILED=看 errorCode 排查，RUNNING=轮询
|
||
|
||
Step 4 (后续) 手动触发同步 +datasource-sync --base-id <B> --table-ids <T1>,<T2>
|
||
→ 返回新 taskId，再用 sync-status 查结果
|
||
|
||
Step 5 (后续) 更新配置 +datasource-update --base-id <B> --table-id <T> --source-config '<JSON>' --auto
|
||
→ 更新后自动触发一次同步
|
||
|
||
查看当前配置 +datasource-get-config --base-id <B> --table-id <T>
|
||
```
|
||
|
||
## sourceConfig 字段协议
|
||
|
||
以下字段协议仅适用于 OA 审批数据源（datasourceType=OA），其他数据源类型待后续开放。
|
||
|
||
### 须从 list-sources 原样透传（必填）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| processCode | String | OA 审批流程编码 |
|
||
| name | String | 展示名称 |
|
||
| iconUrl | String | 图标 URL |
|
||
| url | String | 跳转链接 |
|
||
|
||
### 调用方自行设置
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| dataType | String | 是 | 数据范围类型：`time_range` / `start_time` / `recent_time` |
|
||
| recentDays | String | 条件 | dataType=recent_time 时有效，取值 `7d`/`30d`/`1y`，默认 `30d` |
|
||
| startDate | String | 条件 | dataType=time_range 或 start_time 时有效，`yyyy-MM-dd`，默认 30 天前 |
|
||
| endDate | String | 条件 | dataType=time_range 时有效，`yyyy-MM-dd`，默认当天 |
|
||
| keepRemovedFields | Boolean | 否 | 是否保留已删除字段，默认 false |
|
||
| splitParentTableField | Boolean | 否 | 是否拆分父表字段 |
|
||
|
||
> list-sources 返回的 keepRemovedFields / splitParentTableField / enableDataSyncOaDetailList 不要透传，由调用方按需设置。
|
||
|
||
### 三种 dataType 最小示例
|
||
|
||
```json
|
||
// recent_time — 最近一段时间
|
||
{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}
|
||
|
||
// time_range — 指定起止日期
|
||
{"processCode":"PROC-xxxx","name":"采购申请","dataType":"time_range","startDate":"2025-01-01","endDate":"2025-12-31","iconUrl":"...","url":"..."}
|
||
|
||
// start_time — 从某日期至今
|
||
{"processCode":"PROC-xxxx","name":"采购申请","dataType":"start_time","startDate":"2025-06-01","iconUrl":"...","url":"..."}
|
||
```
|
||
|
||
## autoSyncSetting 频率配置
|
||
|
||
仅在 `--auto=true` 时生效。不传时使用下游默认自动同步策略。
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| syncType | 是 | `hourly`（按小时间隔）/ `scheduled`（定时触发） |
|
||
| hourlyInterval | hourly 时 | 正整数，小时间隔 |
|
||
| scheduleType | scheduled 时 | `daily` / `weekly` / `monthly` |
|
||
| timeValue | scheduled 时 | `HH:mm` 触发时间 |
|
||
| selectedMonthDays | monthly 时必填 | 每月几号触发，1-31 |
|
||
| selectedWeekdays | weekly 时必填 | 每周哪几天触发，1=周一…7=周日 |
|
||
| skipNonWorkingDay | 否 | 是否跳过非工作日，默认 false |
|
||
|
||
示例：`{"syncType":"scheduled","scheduleType":"daily","timeValue":"09:00"}`
|
||
|
||
## 命令详情
|
||
|
||
### +datasource-list-sources — 列出可用数据源条目
|
||
|
||
```bash
|
||
dws aitable +datasource-list-sources --base-id BASE_ID --datasource-type OA --format json
|
||
```
|
||
|
||
| flag | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--base-id` | 是 | 目标 Base ID |
|
||
| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
|
||
|
||
返回每条条目包含 `result`（下游原始 JSON 字符串）和 `sourceType`（OA 审批对应 2）。OA 审批场景下 result 为 approvals 数组：
|
||
|
||
```json
|
||
{
|
||
"approvals": [
|
||
{
|
||
"processCode": "PROC-xxxx",
|
||
"name": "采购申请",
|
||
"iconUrl": "https://...",
|
||
"url": "https://...",
|
||
"keepRemovedFields": false,
|
||
"splitParentTableField": false,
|
||
"enableDataSyncOaDetailList": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
调用方应自行解析 result，提取目标模板字段后构造 sourceConfig。
|
||
|
||
### +datasource-get-fields — 获取可同步字段列表
|
||
|
||
```bash
|
||
dws aitable +datasource-get-fields --base-id BASE_ID --datasource-type OA \
|
||
--source-config '{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
|
||
--format json
|
||
```
|
||
|
||
| flag | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--base-id` | 是 | 目标 Base ID |
|
||
| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
|
||
| `--source-config` | 是 | 源配置 JSON 字符串，结构同 create 的 --source-config |
|
||
|
||
返回字段列表（字段 ID、名称、类型等），用于在 create/update 中指定 `--field-ids`。
|
||
|
||
### +datasource-create — 创建数据源表
|
||
|
||
```bash
|
||
dws aitable +datasource-create --base-id BASE_ID --datasource-type OA \
|
||
--source-config '{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
|
||
--format json
|
||
|
||
# 开启自动同步 + 自定义频率
|
||
dws aitable +datasource-create --base-id BASE_ID --datasource-type OA \
|
||
--source-config '...' --auto \
|
||
--auto-sync-setting '{"syncType":"scheduled","scheduleType":"daily","timeValue":"09:00"}' \
|
||
--format json
|
||
```
|
||
|
||
| flag | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--base-id` | 是 | 目标 Base ID |
|
||
| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
|
||
| `--source-config` | 是 | 源配置 JSON 字符串（见上方字段协议） |
|
||
| `--auto` | 否 | 是否开启自动同步，默认 false；无论是否传入，CLI 都会把该字段下发给下游 |
|
||
| `--auto-sync-setting` | 否 | 自动同步频率配置 JSON 字符串，仅 --auto=true 时生效 |
|
||
| `--field-ids` | 否 | 需要同步的字段 ID 列表，不传时同步全部字段 |
|
||
|
||
返回新建数据源表 tableId 和同步任务 taskId。创建后自动触发一次全量同步，需用 `+datasource-sync-status` 查最终结果。
|
||
|
||
### +datasource-update — 更新数据源配置
|
||
|
||
```bash
|
||
# 仅开启自动同步
|
||
dws aitable +datasource-update --base-id BASE_ID --table-id TABLE_ID --auto --format json
|
||
|
||
# 更新源配置
|
||
dws aitable +datasource-update --base-id BASE_ID --table-id TABLE_ID \
|
||
--source-config '{"processCode":"PROC-yyyy","name":"出差申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
|
||
--format json
|
||
```
|
||
|
||
| flag | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--base-id` | 是 | 目标 Base ID |
|
||
| `--table-id` | 是 | 已有数据源表 ID（sync=true） |
|
||
| `--source-config` | 否 | 新的源配置 JSON 字符串，不传时保持原配置；传入时整体覆盖 |
|
||
| `--auto` | 否 | 是否开启自动同步，不传时保持原设置 |
|
||
| `--auto-sync-setting` | 否 | 自动同步频率配置 JSON 字符串，仅 --auto=true 时生效；不传时保持原频率配置 |
|
||
| `--field-ids` | 否 | 需要同步的字段 ID 列表，不传时保持现有字段配置 |
|
||
|
||
更新后自动触发一次全量同步，返回新 taskId。
|
||
|
||
### +datasource-sync — 手动触发同步
|
||
|
||
```bash
|
||
dws aitable +datasource-sync --base-id BASE_ID --table-ids TBL1,TBL2 --format json
|
||
```
|
||
|
||
| flag | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--base-id` | 是 | 目标 Base ID |
|
||
| `--table-ids` | 是 | 待同步的数据源表 ID 列表（sync=true），1-5 个 |
|
||
|
||
返回结果包含文档链接，可打开查看同步进度。每张表独立提交，部分失败不影响其他表。
|
||
|
||
### +datasource-sync-status — 按任务 ID 查询同步状态
|
||
|
||
```bash
|
||
dws aitable +datasource-sync-status --base-id BASE_ID --table-id TABLE_ID --task-ids TASK1,TASK2 --format json
|
||
```
|
||
|
||
| flag | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--base-id` | 是 | 目标 Base ID |
|
||
| `--table-id` | 是 | 数据源表 ID（sync=true） |
|
||
| `--task-ids` | 是 | 同步任务 ID 列表（由 create/update/sync 返回），1-5 个 |
|
||
|
||
任务状态：`RUNNING`（进行中）、`FINISHED`（完成）、`FAILED`（失败，含 errorCode + errorMessage）。
|
||
|
||
### +datasource-get-config — 获取数据源配置
|
||
|
||
```bash
|
||
dws aitable +datasource-get-config --base-id BASE_ID --table-id TABLE_ID --format json
|
||
```
|
||
|
||
| flag | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--base-id` | 是 | 目标 Base ID |
|
||
| `--table-id` | 是 | 数据源表 ID（sync=true） |
|
||
|
||
返回当前同步配置详情（sourceConfig、是否自动同步、同步状态等）。仅适用于数据源表，普通表会报错。
|
||
|
||
## 错误码与排查
|
||
|
||
| 场景 | 表现 | 排查 |
|
||
|------|------|------|
|
||
| 同步运行中重复触发 | errorCode=4014，status=FAILED | 幂等冲突，稍后重试即可 |
|
||
| 非数据源表触发 sync | 参数错误返回 | 确认 table 的 sync=true，用 `+base-get` / `+table-list` 检查 |
|
||
| sourceConfig 缺必填字段 | 创建/更新失败 | 检查 processCode/name/iconUrl/url 是否从 list-sources 原样透传 |
|
||
| dataType 与时间字段不匹配 | 创建失败 | recent_time 需 recentDays；time_range 需 startDate+endDate；start_time 需 startDate |
|
||
|
||
## 能力边界
|
||
|
||
| 能力 | 状态 |
|
||
|------|------|
|
||
| OA 审批数据源 | 已支持 |
|
||
| 其他数据源类型 | 待后续开放 |
|
||
| 全量同步 | 已支持 |
|
||
| 增量同步 | 待后续开放 |
|
||
| 自动同步 | 已支持（--auto + autoSyncSetting） |
|
||
| 删除数据源表 | 走普通表删除，不走 datasource 命令 |
|
||
|
||
## 注意事项
|
||
|
||
- sourceConfig 是 **JSON 字符串**（不是 JSON 对象），CLI flag 传入时需要用单引号包裹
|
||
- list-sources 返回的 keepRemovedFields / splitParentTableField / enableDataSyncOaDetailList 不要透传，由调用方按需设置
|
||
- create/update 后自动触发一次同步，返回 taskId；用 sync-status 查最终结果
|
||
- sync 单次最多 5 张表，超出拆分多次调用
|
||
- sync-status 单次最多 5 个 taskId，超出拆分多次调用
|
||
- get-config 仅适用于数据源表（sync=true），普通表会报错
|