Appearance
工作表 API 文档
本文档基于明道云(HAP)应用开放接口文档 (v3-beta),提供了完整的工作表 API 使用说明。
概述
应用开放接口文档提供了一个简单的方法来实现应用数据和任何外部数据的集成。API 严格遵循 REST 语义,使用 JSON 编码对象,并依赖标准 HTTP 代码来指示操作结果。
请求格式
- 对于 GET 请求,所有参数通过拼接在 URL 之后传递
- 对于 POST / PUT / PATCH / DELETE 请求,请求的主体必须是 JSON 格式,而且 HTTP header 的 Content-Type 需要设置为
application/json
响应格式
- 所有响应的 HTTP 状态码都是 200
- 响应的 Content-Type 为
application/json - 响应的 body 是 JSON 格式
字段类型对照表
| Type | Code | 描述 | 允许API创建 | 允许API查询 |
|---|---|---|---|---|
| Text | 2 | 文本 | ✓ | ✓ |
| PhoneNumber | 3 | 手机 | - | ✓ |
| LandlinePhone | 4 | 座机 | - | ✓ |
| 5 | 邮箱 | - | ✓ | |
| Number | 6 | 数值 | ✓ | ✓ |
| Certificate | 7 | 证件 | - | ✓ |
| Currency | 8 | 金额 | - | ✓ |
| SingleSelect | 9 | 单选 | ✓ | ✓ |
| MultipleSelect | 10 | 多选 | ✓ | ✓ |
| Dropdown | 11 | 下拉 | - | ✓ |
| Attachment | 14 | 附件 | ✓ | ✓ |
| Date | 15 | 日期 | ✓ | ✓ |
| DateTime | 16 | 时间 | ✓ | ✓ |
| Region | 19/23/24 | 地区 | - | ✓ |
| DynamicLink | 21 | 自由链接 | - | ✓ |
| Divider | 22 | 分段 | - | - |
| AmountInWords | 25 | 大写金额 | - | ✓ |
| Collaborator | 26 | 成员 | ✓ | ✓ |
| Department | 27 | 部门 | - | ✓ |
| Rating | 28 | 等级 | - | ✓ |
| Relation | 29 | 关联记录 | ✓ | ✓ |
| Lookup | 30 | 他表字段 | - | ✓ |
| Formula | 31 | 公式 | - | ✓ |
| Concatenate | 32 | 文本拼接 | - | ✓ |
| AutoNumber | 33 | 自动编号 | - | ✓ |
| SubTable | 34 | 子表 | - | ✓ |
| CascadingSelect | 35 | 级联选择 | - | ✓ |
| Checkbox | 36 | 检查框 | - | ✓ |
| Rollup | 37 | 汇总 | - | ✓ |
| DateFormula | 38 | 公式(日期) | - | ✓ |
| CodeScan | 39 | 扫码 | - | ✓ |
| Location | 40 | 定位 | - | ✓ |
| RichText | 41 | 富文本 | - | ✓ |
| Signature | 42 | 签名 | - | ✓ |
| OCR | 43 | 文字识别 | - | ✓ |
| Role | 44 | 角色 | - | ✓ |
| Embed | 45 | 嵌入 | - | - |
| Time | 46 | 时间 | ✓ | ✓ |
| Barcode | 47 | 条码 | - | ✓ |
| OrgRole | 48 | 组织角色 | - | ✓ |
| Button | 49 | API查询(按钮) | - | - |
| APIQuery | 50 | API查询(下拉) | - | - |
| QueryRecord | 51 | 查询记录 | - | - |
| Section | 52 | 标签页 | - | - |
| FunctionFormula | 53 | 函数公式 | - | ✓ |
筛选器使用指南
筛选器结构
基本语法:
json
Filter = {
type: 'group' | 'condition';
// 当 type 为 'group' 时的字段
logic?: 'AND' | 'OR';
children?: Filter[]; // 只能全是group或全是condition,不能混合使用。最多只能使用两层children
// 当 type 为 'condition' 时的字段
field?: string; // 字段ID或别名
operator?: FilterOperator; // 运算符
value?: any; // 值(字符串、数值、数组)
}支持的运算符
比较运算符
| 运算符 | 描述 | 示例值 |
|---|---|---|
| eq | 等于 | "Beijing" 或 ["<targetid>"] |
| ne | 不等于 | "London" 或 ["<targetid>"] |
| gt | 大于 | 20 或 "2025-02-06 00:00:00" |
| ge | 大于等于 | 10 |
| lt | 小于 | 20 |
| le | 小于等于 | 100 |
| in | 是其中一个 | ["value1", "value2"] |
| notin | 不是任意一个 | ["value1", "value2"] |
| contains | 包含 | "Ch" 或 ["销售部", "市场部"] |
| notcontains | 不包含 | "Ch" 或 ["销售部", "市场部"] |
| concurrent | 同时包含 | ["<id1>", "<id2>"] |
| belongsto | 属于 | ["<departmentid>"] |
| notbelongsto | 不属于 | ["<departmentid>"] |
| startswith | 开头是 | "张" |
| notstartswith | 开头不是 | "李" |
| endswith | 结尾是 | "公司" |
| notendswith | 结尾不是 | "有限公司" |
| between | 在范围内 | ["2025-01-01", "2025-01-31"] |
| notbetween | 不在范围内 | ["10", "20"] |
为空运算符
| 运算符 | 描述 | 备注 |
|---|---|---|
| isempty | 为空 | 不需要 value 字段 |
| isnotempty | 不为空 | 不需要 value 字段 |
使用示例
示例 1: 筛选条件
查询所有1月份入职的姓"张"的职员:
json
{
"type": "group",
"logic": "AND",
"children": [
{
"type": "condition",
"field": "name",
"operator": "startswith",
"value": "张"
},
{
"type": "condition",
"field": "onboard_date",
"operator": "between",
"value": ["2025-01-01", "2025-01-31"]
}
]
}注意事项
- 嵌套限制: 最多支持两层嵌套(group -> group -> condition)
- children 类型一致性: 一个group的children只能全是group或全是condition,不能混合
- logic 必需: 当type为group时,logic字段必须指定为AND或OR
- 为空运算符: 使用isempty和isnotempty时不需要提供value字段
- 数组值: 某些运算符需要数组形式的值(如between、in、contains、concurrent、belongsto等)
- 选项型字段: 所有的选项型字段(单选、多选)需要把对应option的key值放到数组中作为value,使用数组值运算符
- 关联记录: 关联的记录的筛选需要先查询到对应的record_id,再以数组值规则进行筛选
错误码说明
| 错误码 | 说明 |
|---|---|
| 0 | 失败 |
| 1 | 成功 |
| 51 | 请求限流 |
| 10000 | 拒绝访问ip 受限 |
| 10001 | 参数错误 |
| 10002 | 参数值错误 |
| 10005 | 数据操作无权限 |
| 10006 | 数据已存在 |
| 10007 | 数据不存在或已经删除 |
| 10101 | 令牌不存在 |
| 10102 | 签名不合法 |
| 10105 | 用户访问令牌失效 |
| 10106 | 用户访问组织令牌受限 |
| 100005 | 字段值重复 |
| 100006 | 选项数量已达上限 |
| 100007 | 附件数量已达上限 |
| 430013 | 应用未找到工作表 |
| 430014 | 工作表字段权限不足 |
| 430017 | 应用附件上传量不足 |
| 430018 | 草稿箱记录数量已达上限 |
| 430019 | 必填字段值为空 |
| 430020 | 子表数据错误 |
| 430021 | 数据不满足业务规则 |
| 430022 | 工作表不存在 |
| 90000 | 请求次数超出限制 |
| 99999 | 数据操作异常 |
应用接口
获取应用信息
获取应用信息,包含应用下分组、工作表、自定义页面信息
请求
http
GET /v3/app请求头
text
Appkey: {appkey}
Sign: {签名}响应示例
json
{
"success": true,
"error_code": 0,
"error_msg": "",
"data": {
"organizationId": "28447959-cf7f-4ae9-XXXXXXXXXXXXXXX",
"appId": "b55d6ceb-b69a-44f0-a011-XXXXXXXXXXXXXXX",
"name": "客户关系管理",
"iconUrl": "https://fp1.example.cn/customIcon/sys_13_1_shop.svg",
"color": "#3054EB",
"desc": "",
"sections": [
{
"id": "676910ae3e6f2583f5d3edd5",
"name": "驾驶舱",
"items": [],
"childSections": []
}
]
}
}工作表接口
获取工作表列表
获取应用下的所有工作表或者指定的工作表列表
请求
http
POST /v3/app/worksheets/list请求头
text
HAP-Appkey: {HAP应用密钥}
HAP-Sign: {HAP签名}请求体
json
{
"responseFormat": "json",
"worksheets": ["string"]
}响应示例
json
{
"success": true,
"error_code": 0,
"error_msg": "string",
"data": [
{
"id": "string",
"name": "string",
"remark": "string"
}
]
}新建工作表
创建工作表,目前支持字段类型有Text|Number|SingleSelect|MultipleSelect|Date|DateTime|Collaborator|Relation|Attachment
请求
http
POST /v3/app/worksheets请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"name": "测试新建工作表",
"sectionId": "",
"fields": [
{
"name": "文本",
"alias": "",
"type": "2",
"required": true,
"isTitle": true
},
{
"name": "数值",
"alias": "",
"type": "6",
"precision": 2,
"required": true
},
{
"name": "单选",
"alias": "",
"type": "11",
"options": [
{
"value": "选项名称1",
"index": 1
},
{
"value": "选项名称2",
"index": 2
}
],
"required": true
}
]
}响应示例
json
{
"data": {
"worksheetId": "worksheet123"
},
"success": true
}获取工作表结构信息
获取工作表配置及其字段信息
请求
http
GET /v3/app/worksheets/{worksheet_id}?responseFormat=json请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"worksheetId": "65dda1a5a608a40050774c72",
"name": "会员信息",
"alias": "",
"desc": "",
"remark": "",
"fields": [
{
"id": "632444f6182c34e9180b0676",
"name": "名称",
"alias": "",
"desc": "",
"type": "2",
"required": false,
"isHidden": false,
"isReadOnly": false,
"isHiddenOnCreate": false,
"isUnique": false,
"isTitle": true,
"remark": ""
}
],
"views": [
{
"id": "65dda1a5a608a40050774c8f",
"name": "全部",
"type": "0"
}
]
},
"success": true
}编辑工作表
编辑工作表结构,包括新增、编辑、删除字段
请求
http
POST /v3/app/worksheets/{worksheet_id}请求头
text
HAP-Appkey: {HAP应用密钥}
HAP-Sign: {HAP签名}请求体
json
{
"name": "string",
"alias": "string",
"remark": "string",
"sectionId": "string",
"addFields": [
{
"name": "string",
"type": 0,
"alias": "string",
"remark": "string",
"desc": "string",
"required": false,
"isTitle": false,
"isHidden": false,
"isReadOnly": false,
"isHiddenOnCreate": false,
"isUnique": false,
"precision": 14,
"subType": "string",
"options": [
{
"value": "string",
"index": 0
}
],
"relation": {
"showFields": ["string"],
"bidirectional": true
},
"max": 10,
"dataSource": "string",
"sourceField": "string"
}
],
"editFields": [
{
"id": "string",
"name": "string",
"type": 0,
"alias": "string",
"remark": "string",
"desc": "string",
"required": false,
"isTitle": false,
"isHidden": false,
"isReadOnly": false,
"isHiddenOnCreate": false,
"isUnique": false,
"precision": 14,
"subType": "string",
"options": [
{
"value": "string",
"index": 0
}
],
"relation": {
"showFields": ["string"]
},
"max": 10,
"dataSource": "string",
"sourceField": "string"
}
],
"removeFields": ["string"]
}删除工作表
删除工作表
请求
http
DELETE /v3/app/worksheets/{worksheet_id}请求头
text
HAP-Appkey: {HAP应用密钥}
HAP-Sign: {HAP签名}工作表行记录接口
新建行记录
新建行记录
请求
http
POST /v3/app/worksheets/{worksheet_id}/rows请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"triggerWorkflow": true,
"fields": [
{
"id": "6847f2a1e66b4b2aa67b1467",
"value": "HHHH"
}
]
}响应示例
json
{
"data": {
"id": "67890abcdef"
},
"success": true
}获取行记录列表
获取工作表记录列表,包含记录创建者、拥有者信息,各字段对应的值
请求
http
POST /v3/app/worksheets/{worksheet_id}/rows/list请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"pageSize": 20,
"pageIndex": 1,
"viewId": "view_123",
"fields": ["field1", "field2"],
"filter": {
"type": "group",
"logic": "OR",
"children": [
{
"type": "group",
"logic": "AND",
"children": [
{
"type": "condition",
"field": "name",
"operator": "startswith",
"value": "张"
}
]
}
]
},
"sorts": [
{
"field": "createdAt",
"direction": "desc"
}
]
}响应示例
json
{
"data": {
"rows": [
{
"id": "row123",
"_createdBy": {
"accountId": "user123",
"fullname": "张三"
},
"_owner": {
"accountId": "user123",
"fullname": "张三"
},
"_createdAt": "2024-03-25 15:52:58",
"_updatedAt": "2024-03-25 15:52:58",
"_updatedBy": {
"accountId": "user123",
"fullname": "张三"
}
}
],
"total": 100,
"pageIndex": 1,
"pageSize": 20
},
"success": true
}批量新增行记录
批量新建行记录
请求
http
POST /v3/app/worksheets/{worksheet_id}/rows/batch请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"rows": [
{
"fields": [
{
"id": "field1",
"value": "值1"
},
{
"id": "field2",
"value": "值2"
}
]
},
{
"fields": [
{
"id": "field1",
"value": "值3"
},
{
"id": "field2",
"value": "值4"
}
]
}
],
"triggerWorkflow": true
}响应示例
json
{
"data": {
"rowIds": ["row1", "row2"]
},
"success": true
}批量更新行记录详情
批量更新行记录
请求
http
PATCH /v3/app/worksheets/{worksheet_id}/rows/batch请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"rowIds": ["row1", "row2"],
"fields": [
{
"id": "field1",
"value": "新值1"
},
{
"id": "field2",
"value": "新值2"
}
],
"triggerWorkflow": true
}响应示例
json
{
"data": {
"failedRowIds": [],
"successfulRowIds": ["row1", "row2"]
},
"success": true
}批量删除行记录
批量删除行记录
请求
http
DELETE /v3/app/worksheets/{worksheet_id}/rows/batch请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"rowIds": ["row1", "row2", "row3"],
"triggerWorkflow": true,
"permanent": false
}获取行记录详情
获取记录详情信息,包括创建者、拥有者、字段信息、根据字段数据类型生成示例值
请求
http
GET /v3/app/worksheets/{worksheet_id}/rows/{row_id}?includeSystemFields=false请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"id": "67890abcdef12345",
"6847f2a1e66b4b2aa67b1467": "示例值",
"_createdAt": "2024-03-25 15:52:58",
"_createdBy": {
"accountId": "user123",
"fullname": "张三",
"avatar": "https://example.com/avatar.jpg",
"status": "1"
},
"_updatedAt": "2024-03-25 15:52:58",
"_updatedBy": {
"accountId": "user123",
"fullname": "张三",
"avatar": "https://example.com/avatar.jpg",
"status": "1"
},
"_owner": {
"accountId": "user123",
"fullname": "张三",
"avatar": "https://example.com/avatar.jpg",
"status": "1"
}
},
"success": true
}更新行记录
更新行记录
请求
http
PATCH /v3/app/worksheets/{worksheet_id}/rows/{row_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"fields": [
{
"id": "6847f2a1e66b4b2aa67b1467",
"value": "更新后的值"
}
],
"triggerWorkflow": true
}响应示例
json
{
"success": true,
"data": {
"id": "89d4fd5b-91d8-4b0d-babc-263cefed16c7"
}
}删除行记录
删除行记录
请求
http
DELETE /v3/app/worksheets/{worksheet_id}/rows/{row_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"triggerWorkflow": false,
"permanent": true
}工作流接口
获取流程列表
获取应用下工作流列表
请求
http
GET /v3/app/workflow/processes请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"processes": [
{
"id": "681b8934ec9191462c08417a",
"name": "新增线索",
"alias": "",
"type": 10,
"description": "新增线索流程",
"status": 0,
"_createdAt": "2025-02-17 17:53:44",
"_updatedAt": "2025-06-17 17:53:44",
"_owner": {
"accountId": "e2453de8-1a6a-4d4f-ba36-87fdff880a20",
"fullname": "卜佳菲",
"avatar": "https://p1.example.cn/UserAvatar/fe9c4374-68f1-4f64-88ea-47050dff28bd.jpg?imageView2/1/w/100/h/100/q/90",
"status": "1"
}
}
]
},
"success": true
}获取流程详情
获取流程详情,包含流程请求参数,响应参数
请求
http
GET /v3/app/workflow/processes/{process_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"id": "681b8934ec9191462c08417a",
"name": "新增线索",
"description": "新增线索的描述",
"inputParameters": [
{
"field": "681b8190ec9191462c08283b",
"fieldname": "名称",
"alias": "",
"description": "",
"type": 2,
"required": false
},
{
"field": "681b8190ec9191462c08111",
"fieldname": "渠道",
"description": "",
"alias": "",
"type": 9,
"options": [
{
"key": "option1",
"value": "选项1"
}
],
"required": false
}
],
"outputParameters": [
{
"field": "681b8190ec9191462c082222",
"fieldname": "id",
"alias": "",
"description": "",
"type": 2
}
]
},
"success": true
}触发流程
触发流程
请求
http
POST /v3/app/workflow/hooks/{process_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"text_field": "日报",
"number_field": 100,
"checkbox_field": 1,
"datetime_field": "2025-07-16 15:20",
"radio_field": "选项B",
"array_field": ["item1", "item2"],
"object_array_field": [
{
"key": "A",
"value": 1
},
{
"key": "B",
"value": 2
}
],
"user_field": ["user_001"],
"department_field": ["dept_001"],
"role_field": ["role_leader"],
"file_field": ["https://example.com/input/file1.pdf"]
}响应示例
json
{
"data": {},
"success": true
}选项集接口
获取选项集列表
获取应用下选项集列表
请求
http
GET /v3/app/optionsets请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"optionsets": [
{
"id": "optionset123",
"name": "状态选项集",
"accountId": "account123",
"worksheetIds": ["worksheet123", "worksheet456"],
"options": [
{
"key": "key1",
"value": "进行中",
"index": 1,
"isDeleted": false,
"color": "#2196F3",
"score": 50
},
{
"key": "key2",
"value": "已完成",
"index": 2,
"isDeleted": false,
"color": "#4CAF50",
"score": 100
}
],
"enableColor": true,
"enableScore": true
}
]
},
"success": true
}创建选项集
创建选项集信息 数据包括:选项集名称、选项集信息(选项值、排序、颜色、分值)
请求
http
POST /v3/app/optionsets请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"name": "状态选项集",
"options": [
{
"value": "进行中",
"index": 1,
"color": "#2196F3",
"score": 50
},
{
"value": "已完成",
"index": 2,
"color": "#4CAF50",
"score": 100
}
],
"enableColor": true,
"enableScore": true
}响应示例
json
{
"data": {
"optionsetId": "option_set_123"
},
"success": true
}编辑选项集
编辑选项集
请求
http
POST /v3/app/optionsets/{optionset_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"name": "更新后的选项集",
"options": [
{
"key": "key1",
"value": "更新选项1",
"index": 1,
"isDeleted": false,
"color": "#FF5722",
"score": 60
}
],
"enableColor": true,
"enableScore": true
}删除选项集
删除选项集
请求
http
DELETE /v3/app/optionsets/{optionset_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}角色接口
获取角色列表
获取应用下角色列表
请求
http
GET /v3/app/roles请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}创建角色
创建角色 信息包含:角色名称、描述、权限信息
请求
http
POST /v3/app/roles请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}请求体
json
{
"name": "新角色",
"description": "角色描述",
"permissionScope": 100,
"type": 0,
"hideAppForMembers": true,
"globalPermissions": {
"addRecord": true,
"share": true,
"import": true,
"export": true,
"discuss": true,
"systemPrint": true,
"attachmentDownload": true,
"log": true
}
}获取角色详情
获取角色详情
请求
http
GET /v3/app/roles/{role_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}删除角色
删除角色
请求
http
DELETE /v3/app/roles/{role_id}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}公共查询接口
查找成员
根据输入的人员名称匹配用户,返回用户 ID、姓名、已脱敏的手机号和邮箱。
请求
http
GET /v3/users/lookup?name={人员名称}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"users": [
{
"accountId": "user_001",
"name": "Alice",
"mobile": "138****5678",
"email": "ali****@mail.com",
"departments": [
{
"id": "dept_001",
"name": "销售部",
"path": "公司/销售部",
"pathNodes": []
}
]
}
]
},
"success": true
}查找部门
根据输入的部门名称匹配部门,返回部门 ID 和名称。
请求
http
GET /v3/departments/lookup?name={部门名称}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"departments": [
{
"id": "7fb381a3-d559-4b0c-a8fd-e1e8a6272442",
"name": "销售一部",
"path": "华东大区/上海分公司/销售部",
"pathNodes": []
}
]
},
"success": true
}获取地区信息
获取地区信息,支持按ID查询或模糊搜索
请求
http
GET /v3/regions?id={地区ID}&search={搜索内容}请求头
text
HAP-Appkey: {appkey}
HAP-Sign: {签名}响应示例
json
{
"data": {
"regions": [
{
"id": "110000",
"name": "北京市",
"path": "北京市",
"last": false
},
{
"id": "120000",
"name": "天津市",
"path": "天津市",
"last": false
}
]
},
"success": true
}注意事项
- 认证方式: 所有请求都需要在请求头中包含
Appkey和Sign进行签名认证 - 字段值格式:
- 附件类型字段:
[{"name":"文件名称,带后缀","url":"url/base64"}] - 关联记录类型:多条记录rowId用逗号(,)分割
- 日期类型:格式为
2018-8-8或2018-8-8 12:00:00
- 附件类型字段:
- 工作流触发: 默认情况下,创建、更新、删除记录会触发工作流,可通过
triggerWorkflow参数控制 - 分页查询: 列表查询接口支持分页,
pageSize最大为 1000,pageIndex从 1 开始 - 筛选器: 筛选器最多支持两层嵌套,children 类型必须一致
维护负责人:技术部
最后更新:2025-01-19
文档来源:明道云(HAP)应用开放接口文档 v3-beta