应用表格接口调用规则

1. 适用范围

本文档适用于 SDK OpenAPI 数据表接口：

{sdkPathPrefix}/sdk/v2/api/table-api/openapi/v1/tables

2. 通用规则

2.1 请求 Header

所有接口必须携带：

提交 JSON 请求体时必须携带：

错误信息国际化可选携带：

2.2 鉴权规则

操作类型	权限要求
查询表、字段、行	文件读权限
创建表、创建字段、更新字段、删除字段、创建行、更新行、删除行	文件写权限

文件开启高级权限时，接口直接返回 403。

2.3 通用成功响应

{
  "code": 0,
  "msg": "success",
  "data": {}
}

2.4 通用错误响应

{
  "code": 70000,
  "message": "请求参数错误"
}

说明：code 为数字业务错误码；鉴权签名或 Token 无效时可能直接返回 401 {"error":"Unauthorized"}，不包含业务错误码。

3. 基础接口

3.1 获取数据表列表

兼容参数：

规则：

项	说明
必填参数	baseGuid 或 base_guid
权限	读权限
高级权限	开启时返回 403

3.2 创建数据表

请求体：

{
  "baseGuid": "base_xxx",
  "name": "客户表",
  "withoutInitRows": false,
  "cols": [
    {
      "name": "客户名称",
      "type": "SingleLineText",
      "props": {}
    }
  ]
}

规则：

项	说明
必填字段	baseGuid、name
权限	写权限
高级权限	开启时返回 403
表名长度	1-31 个字符
初始字段	cols 至少包含一列，第一列为主键列
主键列类型	SingleLineText、LongText、SingleChoice、Number、Percent、AutoNumber、Date
特殊 props	CheckBox 和 Rate 字段必须符合 3.4 中的 props 规则

3.3 获取字段列表

规则：

项	说明
路径参数	guid 为数据表 guid
权限	读权限

3.4 新增字段

请求体：

{
  "name": "金额",
  "type": "Number",
  "props": {
    "precision": 2
  },
  "viewGuid": "view_xxx",
  "targetGuid": "col_xxx"
}

支持字段类型： SingleLineText
Number

LongText

Date

SingleChoice

MultipleChoice

Percent

Link

CheckBox

Rate

Cascade

规则：

项	说明
必填字段	name、type、viewGuid
权限	写权限
字段名长度	1-100 个字符
字段名唯一性	同一数据表内不可重复
类型限制	只能使用上述支持字段类型
targetGuid	在指定字段后创建；空字符串表示创建为第一列并切换为主键列
第一列类型	仅允许当前新增字段接口支持的主键类型：SingleLineText、LongText、SingleChoice、Number、Percent、Date

CheckBox props：

{
  "type": "check"
}

type 仅允许：check、star、close。
Rate props：

{
  "count": 5,
  "icon": "star"
}

count 必须为 1-10；icon 仅允许：star、flame、heart、honor、stone。

3.5 更新字段

请求体：

{
  "name": "成交金额",
  "type": "Number",
  "props": {
    "precision": 2
  }
}

规则：

项	说明
路径参数	guid 为数据表 guid，colGuid 为字段 guid
权限	写权限
可更新字段	name、type、props
字段名长度	1-100 个字符
字段名唯一性	同一数据表内不可重复
类型限制	只能使用新增字段接口列出的支持字段类型
特殊 props	更新为 CheckBox/Rate 或更新这两类字段的 props 时，必须符合 3.4 的规则
主键列类型	主键列修改类型时，仅允许当前更新字段接口支持的主键类型：SingleLineText、LongText、SingleChoice、Number、Percent、Date
历史值转换	不自动转换历史行值

3.6 删除字段

规则：

项	说明
路径参数	guid 为数据表 guid，colGuid 为字段 guid
权限	写权限
字段不存在	返回 400

3.7 获取行列表

规则：

参数	必填	说明
guid	是	数据表 guid
pageSize	否	默认 10，最大 100
offset	否	起始 row guid
viewGuid	否	不传时使用默认视图

3.8 获取单行

规则：

项	说明
路径参数	guid 为数据表 guid，rowGuid 为行 guid
权限	读权限
行不存在	返回 404

3.9 新增行

请求体：

{
  "rows": [
    {
      "客户名称": "石墨",
      "金额": 123.45,
      "状态": "待跟进"
    }
  ]
}

规则：

项	说明
必填字段	rows
权限	写权限
单次行数	1-2000
valueMap key	使用字段名称
单选字段值	使用选项名称
多选字段值	使用选项名称数组

注：不支持附件列单元格值的更新，涉及需要先上传附件，功能不在本次接口范围内，下面的更新行也是一样

3.10 更新单行

请求体：

{
  "valueMap": {
    "客户名称": "石墨文档",
    "金额": 200,
    "状态": "待跟进"
  }
}

规则：

项	说明
必填字段	valueMap
权限	写权限
valueMap key	使用字段名称
未传字段	不更新
单选字段值	使用选项名称
多选字段值	使用选项名称数组

3.11 删除行

规则：

项	说明
路径参数	guid 为数据表 guid，rowGuid 为行 guid
权限	写权限
行不存在	返回 404

4. 复合操作调用规则

4.1 字段类型转换

适用场景：

字段 type 发生变化，且历史行值需要同步转换

调用顺序：

GET /tables/{guid}/columns

GET /tables/{guid}/rows

调用方计算转换后的行值

PUT /tables/{guid}/columns/{colGuid}

PATCH /tables/{guid}/rows/{rowGuid}

规则：

项	说明
字段定义变更	通过 PUT columns/{colGuid} 完成
历史值变更	通过 PATCH rows/{rowGuid} 完成
转换逻辑	调用方负责计算
事务性	多次 HTTP 调用不保证原子性
失败处理	PATCH row 失败时调用方记录失败行并重试

示例：

将“金额”字段从 SingleLineText 转为 Number

先更新字段：

{
  "type": "Number",
  "props": {
    "precision": 2
  }
}

再更新历史行：

{
  "valueMap": {
    "金额": 123.45
  }
}

4.2 字段属性变更导致历史值失效

适用场景：

字段 props 变化后，部分历史值不再合法

典型场景：

场景	处理方式
删除单选选项	清空或替换引用该选项的历史值
删除多选选项	从历史多选值中移除该选项
多选转单选	将数组值转换为单个值
数字精度或范围变化	调整不符合新规则的历史值

调用顺序：

GET /tables/{guid}/rows

调用方计算需要修正的行值

PUT /tables/{guid}/columns/{colGuid}

PATCH /tables/{guid}/rows/{rowGuid}

规则：

项	说明
字段属性变更	通过 PUT columns/{colGuid} 完成
历史值修正	通过 PATCH rows/{rowGuid} 完成
修正范围	只更新受影响行

4.3 删除字段

调用接口：

规则：

项	说明
删除字段	只调用删除字段接口
额外行更新	不需要调用
日期提醒	当前无公开 OpenAPI 处理

4.4 删除行

调用接口：

规则：

项	说明
删除单行	只调用删除行接口
删除多行	逐行调用删除行接口
删除父子记录	调用方先展开子记录，再逐行删除
日期提醒	当前无公开 OpenAPI 处理

推荐顺序：

DELETE child row

DELETE parent row

4.5 更新单元格

调用接口：

规则：

项	说明
单元格更新	通过 valueMap 更新
清空单元格	字段值传 null
日期提醒	当前无公开 OpenAPI 处理

5. 复合操作对照表

业务操作	必须调用接口	需要调用方补充调用	说明
字段类型转换	PUT columns/{colGuid}	PATCH rows/{rowGuid}	历史值转换由调用方负责
字段属性变更	PUT columns/{colGuid}	PATCH rows/{rowGuid}	仅修正受影响行
删除字段	DELETE columns/{colGuid}	无	日期提醒暂无公开接口
删除行	DELETE rows/{rowGuid}	无	多行删除需逐行调用
删除父子记录	DELETE rows/{rowGuid}	调用方展开子记录	先删子记录，再删父记录
更新单元格	PATCH rows/{rowGuid}	无	清空值传 null
新增字段	POST columns	无	不自动补历史行值
新增行	POST rows	无	初始值在请求体中传入

6. 调用方必须保证的事项

字段类型转换前，调用方必须先读取旧字段定义和历史行值。

字段类型转换后，如历史值需要变化，调用方必须逐行调用更新行接口。

字段属性变更后，如历史值不再合法，调用方必须逐行修正。

多次接口调用不具备事务性，调用方必须处理部分成功和重试。

批量行处理必须分页读取，单次新增行不得超过 2000。

删除多行或父子记录时，调用方必须自行拆分为多次删除行调用。

当前公开 OpenAPI 不提供日期提醒更新接口，调用方不得假设日期提醒会被同步处理。

7. 错误码与触发原因

7.1 通用错误码

除特别说明外，下表适用于全部 OpenAPI 接口。

HTTP 状态	业务错误码	含义	常见触发原因
400	70000	请求参数错误	JSON 格式错误、必填字段缺失、字段格式或业务校验不通过
400	70004	字段不存在	更新或删除的 colGuid 在数据表中不存在
400	70012	请求体过大	Compose 数据超过服务允许的消息大小
401	20000	认证信息无效	X-Shimo-User-ID 无法解析等身份信息错误
401	无业务码	签名或 Token 无效	X-Shimo-Signature、X-Shimo-Token 缺失、过期或校验失败；响应可能为 {"error":"Unauthorized"}
403	20000	无访问权限	没有文件读权限、写权限，或上游文件服务拒绝访问
403	20000	高级权限不支持	文件已开启高级权限，OpenAPI 拒绝访问
404	70001	文件不存在	baseGuid 对应的文件不存在
404	70002	数据表不存在	路径中的数据表 guid 不存在
404	70003	视图不存在	viewGuid 不存在，或数据表没有可用默认视图
404	70005	行不存在	rowGuid 对应的行不存在
408	70006	请求超时或取消	调用下游服务或同步 Compose 超时，请求上下文被取消
500	10000	服务内部错误	下游 RPC、存储、Compose 或其他未映射为明确业务错误码的异常；message 中包含 traceId

7.2 各接口错误原因

GET /tables

HTTP 状态	业务错误码	触发原因
400	70000	未传 baseGuid/base_guid，或值为空
403	20000	没有文件读权限，或文件已开启高级权限
404	70001	baseGuid 对应文件不存在
408	70006	请求超时或被取消
500	10000	查询文件、权限、高级权限状态或数据表列表失败

POST /tables

HTTP 状态	业务错误码	触发原因
400	70000	JSON 无法解析，baseGuid/name 缺失，cols 为空或包含 nil 字段
400	70000	第一列不是允许的主键列类型
400	70000	CheckBox 的 type 非 check/star/close，或 Rate 的 count/icon 不合法
400	70000	数据表名称长度不在 1-31 个字符范围内
400	70012	建表 Compose 消息过大
403	20000	没有文件写权限，或文件已开启高级权限
404	70001	baseGuid 对应文件不存在
408	70006	同步创建超时或请求被取消
500	10000	权限检查、名称调整、Compose、创建后查询等下游操作失败

GET /tables/{guid}/columns

HTTP 状态	业务错误码	触发原因
403	20000	没有文件读权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
408	70006	请求超时或被取消
500	10000	字段查询或下游服务失败

POST /tables/{guid}/columns

HTTP 状态	业务错误码	触发原因
400	70000	JSON 无法解析，或必填 viewGuid 缺失
400	70000	字段类型不在支持范围内
400	70000	targetGuid 为空时，字段类型不符合主键列类型限制
400	70000	字段 props 无效；CheckBox/Rate 不符合特殊 props 规则
400	70000	字段名为空、超过 100 个字符，或与已有字段重名
400	70012	创建字段 Compose 消息过大
403	20000	没有文件写权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
408	70006	同步创建超时或请求被取消
500	10000	字段查询、Compose 或下游存储操作失败

PUT /tables/{guid}/columns/{colGuid}

HTTP 状态	业务错误码	触发原因
400	70000	JSON 无法解析，或 name/type/props 均未提供有效更新
400	70000	字段类型不受支持，字段名为空或超过 100 个字符
400	70000	主键列被修改为不允许的类型
400	70000	字段 props 无效；CheckBox/Rate 不符合特殊 props 规则
400	70000	字段名称与已有字段重名
400	70004	colGuid 对应字段不存在
400	70012	更新字段 Compose 消息过大
403	20000	没有文件写权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
408	70006	同步更新超时或请求被取消
500	10000	字段查询、Compose、更新后查询或下游操作失败

DELETE /tables/{guid}/columns/{colGuid}

HTTP 状态	业务错误码	触发原因
400	70004	colGuid 对应字段不存在
400	70012	删除字段 Compose 消息过大
403	20000	没有文件写权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
408	70006	同步删除超时或请求被取消
500	10000	字段查询、Compose 或下游删除操作失败

GET /tables/{guid}/rows

HTTP 状态	业务错误码	触发原因
403	20000	没有文件读权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
404	70003	viewGuid 不存在，或未传 viewGuid 且数据表没有默认视图
408	70006	查询超时或请求被取消
500	10000	视图、行、字段或用户信息查询失败

GET /tables/{guid}/rows/{rowGuid}

HTTP 状态	业务错误码	触发原因
403	20000	没有文件读权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
404	70005	rowGuid 对应行不存在
408	70006	查询超时或请求被取消
500	10000	行、字段或用户信息查询失败

PATCH /tables/{guid}/rows/{rowGuid}

HTTP 状态	业务错误码	触发原因
400	70000	JSON 无法解析，valueMap 缺失，或转换后的更新数据校验失败
400	70012	更新行 Compose 消息过大
403	20000	没有文件写权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
408	70006	同步更新超时或请求被取消
500	10000	字段查询、Compose、更新后查询或下游操作失败

DELETE /tables/{guid}/rows/{rowGuid}

HTTP 状态	业务错误码	触发原因
400	70012	删除行 Compose 消息过大
403	20000	没有文件写权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
404	70005	rowGuid 对应行不存在
408	70006	同步删除超时或请求被取消
500	10000	行查询、Compose 或下游删除操作失败

POST /tables/{guid}/rows

HTTP 状态	业务错误码	触发原因
400	70000	JSON 无法解析，rows 缺失或为空
400	70000	单次 rows 数量超过 2000
400	70012	创建行 Compose 消息过大
403	20000	没有文件写权限，或文件已开启高级权限
404	70001	数据表所属文件不存在
404	70002	数据表不存在
408	70006	同步创建超时或请求被取消
500	10000	字段查询、值转换、Compose、创建后查询或下游操作失败

1. 适用范围#

2. 通用规则#

2.1 请求 Header#

2.2 鉴权规则#

2.3 通用成功响应#

2.4 通用错误响应#

3. 基础接口#

3.1 获取数据表列表#

3.2 创建数据表#

3.3 获取字段列表#

3.4 新增字段#

3.5 更新字段#

3.6 删除字段#

3.7 获取行列表#

3.8 获取单行#

3.9 新增行#

3.10 更新单行#

3.11 删除行#

4. 复合操作调用规则#

4.1 字段类型转换#

4.2 字段属性变更导致历史值失效#

4.3 删除字段#

4.4 删除行#

4.5 更新单元格#

5. 复合操作对照表#

6. 调用方必须保证的事项#

7. 错误码与触发原因#

7.1 通用错误码#

7.2 各接口错误原因#

GET /tables#

POST /tables#

GET /tables/{guid}/columns#

POST /tables/{guid}/columns#

PUT /tables/{guid}/columns/{colGuid}#

DELETE /tables/{guid}/columns/{colGuid}#

GET /tables/{guid}/rows#

GET /tables/{guid}/rows/{rowGuid}#

PATCH /tables/{guid}/rows/{rowGuid}#

DELETE /tables/{guid}/rows/{rowGuid}#

POST /tables/{guid}/rows#

1. 适用范围

2. 通用规则

2.1 请求 Header

2.2 鉴权规则

2.3 通用成功响应

2.4 通用错误响应

3. 基础接口

3.1 获取数据表列表

3.2 创建数据表

3.3 获取字段列表

3.4 新增字段

3.5 更新字段

3.6 删除字段

3.7 获取行列表

3.8 获取单行

3.9 新增行

3.10 更新单行

3.11 删除行

4. 复合操作调用规则

4.1 字段类型转换

4.2 字段属性变更导致历史值失效

4.3 删除字段

4.4 删除行

4.5 更新单元格

5. 复合操作对照表

6. 调用方必须保证的事项

7. 错误码与触发原因

7.1 通用错误码

7.2 各接口错误原因

GET /tables

POST /tables

GET /tables/{guid}/columns

POST /tables/{guid}/columns

PUT /tables/{guid}/columns/{colGuid}

DELETE /tables/{guid}/columns/{colGuid}

GET /tables/{guid}/rows

GET /tables/{guid}/rows/{rowGuid}

PATCH /tables/{guid}/rows/{rowGuid}

DELETE /tables/{guid}/rows/{rowGuid}

POST /tables/{guid}/rows