百数 (Baishu) API 操作技能

概述

百数是一款低代码平台，提供完整的 OpenAPI 接口。本 Skill 覆盖三大接口体系：

• 应用接口：获取应用列表、表单列表、字段结构
• 表单数据接口：增删改查（单条 & 批量）
• 文件接口：文件上传（通过 URL）

快速开始

1. 获取 API 凭证

• 登录百数 → 点击右上角头像 → 开放平台 → 密钥管理 → 创建 API Key
• 所有请求 Header 必须携带：Authorization: Bearer YOUR_APIKEY
• 频率限制：每秒最多 5 次请求

2. 获取 Base URL

登录应用主页 → 右上角头像 → 开放平台 → API → 任意应用 → 在文档开头找到"统一访问地址"

3. 使用封装脚本

技能内置 Python 封装类，位于 scripts/baishuyun_api.py：

# 命令行快速调用示例
python scripts/baishuyun_api.py --base-url "https://www.baishuyun.com" --api-key "YOUR_KEY" list-apps
python scripts/baishuyun_api.py --base-url "..." --api-key "..." list-forms --app-id APP_ID
python scripts/baishuyun_api.py --base-url "..." --api-key "..." get-data --app-id APP_ID --entry-id ENTRY_ID --data-id DATA_ID
python scripts/baishuyun_api.py --base-url "..." --api-key "..." query-data --app-id APP_ID --entry-id ENTRY_ID --limit 100
python scripts/baishuyun_api.py --base-url "..." --api-key "..." create-data --app-id APP_ID --entry-id ENTRY_ID --data '{"字段名":"值"}'
python scripts/baishuyun_api.py --base-url "..." --api-key "..." update-data --app-id APP_ID --entry-id ENTRY_ID --data-id DATA_ID --data '{"字段名":"新值"}'
python scripts/baishuyun_api.py --base-url "..." --api-key "..." delete-data --app-id APP_ID --entry-id ENTRY_ID --data-id DATA_ID
python scripts/baishuyun_api.py --base-url "..." --api-key "..." upload-file --app-id APP_ID --entry-id ENTRY_ID --file-url "https://..." --file-name "test.jpg"

接口体系详解

一、应用接口

1.1 查询表单字段结构

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/widgets
• 无请求体
• 返回: widgets 数组，含字段 name、type、title、widget（原始别名）

> ⚠️ 不支持分割线和关联查询字段

二、表单数据接口

2.1 新增数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_create

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| data | Object | ✅ | 字段名→值的映射，使用字段别名 |

| is_start_workflow | Boolean | ❌ | 是否触发流程，默认 false |

| is_start_event | Boolean | ❌ | 是否触发事件，默认 false |

| operator | String | ❌ | 操作人ID |

返回: data 对象，含 _id、appId、entryId、createTime 等

2.2 查询单条数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_retrieve

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| data_id | String | ✅ | 数据ID |

2.3 查询多条数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| limit | Number | ❌ | 每次最多 300 条，默认 300 |

| skip | Number | ❌ | 分页偏移量 |

| fields | Array | ❌ | 指定返回字段别名列表 |

| filter | Object | ❌ | 筛选器，含 rel（and/or）和 cond 数组 |

| sort | Object | ❌ | 排序，{"字段别名": "asc"/"desc"} |

| data_id | Array | ❌ | 按ID列表直接查询 |

| isbackup | Number | ❌ | 0=未删除，1=回收站 |

filter 示例:

{
  "filter": {
    "rel": "and",
    "cond": [
      {"field": "字段别名", "method": "eq", "value": "目标值"},
      {"field": "字段别名2", "method": "not_empty"}
    ]
  }
}

可用 method: eq(等于)、ne(不等于)、empty(为空)、not_empty(非空)、gt(大于)、lt(小于)、gte(≥)、lte(≤)、like(包含)

2.4 编辑数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_update

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| data_id | String | ✅ | 数据ID |

| data | Object | ❌ | 要更新的字段数据 |

| is_start_event | Boolean | ❌ | 是否触发事件，默认 false |

| operator | String | ❌ | 操作人ID |

2.5 删除数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_delete

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| data_id | String | ✅ | 数据ID |

2.6 批量新增数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_create_batch
• body: {"data_list": [{...}, {...}], "is_start_event": false}

2.7 查询数据总数

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_count
• body: {"filter": {...}}（可选）

2.8 批量修改数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_update_batch

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| filter | Object | ❌ | 筛选条件 |

| data | Object | ✅ | 批量更新的字段数据 |

| is_start_event | Boolean | ❌ | 是否触发事件 |

2.9 批量删除数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_delete_batch

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| filter | Object | ❌ | 筛选条件（与 data_ids 二选一） |

| data_ids | Array | ❌ | 要删除的 ID 列表 |

2.10 新增唯一数据（去重插入）

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_create_unique
• body: 同新增数据，如已存在则不重复插入

2.11 批量新增唯一数据

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/data_create_unique_batch

三、文件接口

3.1 文件上传（通过 URL）

• URL: POST /openapi/v1/app/{app_id}/entry/{entry_id}/upload_file
• body: JSON 数组格式

[
  {"name": "文件名.jpg", "url": "https://可公开访问的文件地址"}
]

返回:

{
  "data": [
    {"name": "文件名.jpg", "size": 68065, "mime": "image/jpeg", "url": "https://..."}
  ]
}

> 返回的 url 可直接用于创建/修改数据接口中的附件或图片控件字段值

常见字段类型传值格式

| 字段类型 | 传值格式示例 |

|---------|------------|

| 单行/多行文本 | "字段名": "文本内容" |

| 数字 | "字段名": 100 |

| 日期时间 | "字段名": "2024-01-01 12:00:00" |

| 成员单选 | "字段名": "用户ID" |

| 成员多选 | "字段名": ["用户ID1", "用户ID2"] |

| 地址 | "字段名": {"province": "湖南省", "city": "长沙市", "district": "芙蓉区", "detail": "韶山北路"} |

| 附件/图片 | "字段名": [{"name": "文件名", "url": "文件地址"}]（先调用文件上传接口获取） |

| 子表单 | "字段名": [{"子字段1": "值1"}, {"子字段1": "值2"}] |

错误码速查

| 错误码 | 含义 |

|--------|------|

| 4001 | 参数错误 |

| 4003 | 无权限 |

| 4004 | 请求频率超限（每秒限5次） |

| 4005 | 数据不存在 |

| 400 | 其他业务错误 |

工作流程（SOP）

场景 A：数据迁移（外部数据 → 百数）

1. 调用 list-forms 确认目标表单ID
2. 调用 get-widgets 获取字段结构，建立字段别名映射
3. 批量构造数据，调用 create-data（单条）或 create-batch（批量，建议每批 ≤100）
4. 如需上传附件，先调用 upload-file 获取 URL，再填入数据

场景 B：数据同步（百数 → 外部系统）

1. 调用 query-data 分页拉取数据（limit=300，循环 skip）
2. 判断总数可先调用 data-count
3. 处理数据、写入目标系统

场景 C：条件更新/删除

1. 构造 filter 条件
2. 调用 update-batch 或 delete-batch

参考资源

• scripts/baishuyun_api.py：完整 Python 封装类，支持命令行和模块两种用法
• references/api_quick_ref.md：接口速查表
• 官方文档：https://doc.baishuyun.com/md/1288