数据说明 - DingTalk Help Center

数据结构

Base，即一篇AI表格文档
- baseId唯一标识了一篇AI表格文档。baseId可以通过以下方法获取。
  通过URL获取 image.png 通过文档信息面板获取 imageimage 通过其它API获取 - 可通过获取节点列表接口获取。说明创建AI表格时，docType值为BASE。
Sheet（即数据表），一篇AI表格文档中通常有多个数据表，且至少有一个数据表。
- 所有需要访问sheet的接口都可以使用sheetId或sheetName作为入参。
- sheetId可以通过获取所有数据表接口获取。

说明

sheetId仅保证在文档中唯一，不保证全局唯一。

sheetName为前端可见的sheet名称，如下图中的任务管理。
Field（即字段），数据表中的每一列即是一个字段，一个数据表中通常有多个字段。
- 所有需要访问field的接口都可以使用fieldId或fieldName作为入参。
- fieldId可以通过获取所有字段接口获取。

说明

fieldId仅保证在文档中唯一，不保证全局唯一。

fieldName为前端可见的field名称，如下图中的重要程度。
每个sheet的第一列为「主字段」，其仅支持特定几种字段类型，且该列不可删除。具体支持的字段类型使用如下方法查看
- 打开任意AI表格
- 编辑主字段
- 查看可设置的字段类型
Record（即记录），数据表中的每一行即是一个记录，一个数据表中通常有多个记录。
- 所有需要访问record接口需要使用recordId。
- recordId可以通过新增记录或列出多行记录等接口获取。

说明

recordId仅保证在文档中唯一，不保证全局唯一。数据结构

数据结构

字段属性

字段属性区域，如下图所示：

字段属性

不同字段类型所支持的属性请参考下表：

字段名	类型 (type)	属性 (property)
文本	text	无
数字	number	`formatter` 取值：`INT` / `FLOAT_1` / `FLOAT_2` / `FLOAT_3` / `FLOAT_4`（保留 N 位小数）/ `THOUSAND` / `THOUSAND_FLOAT`（千分位）/ `PERCENT` / `PERCENT_FLOAT`（百分比）
货币	currency	`currencyType`：`CNY` / `HKD` / `USD` / `EUR` / `GBP` / `MOP` / `VND` / `JPY` / `KRW` / `AED` / `AUD` / `BRL` / `CAD` / `CHF` / `INR` / `IDR` / `MXN` / `MYR` / `PHP` / `PLN` / `RUB` / `SGD` / `THB` / `TRY` / `TWD`；`formatter` 取值：`INT` / `FLOAT_1` … `FLOAT_4`
单选	singleSelect	`{ choices: [{ name: "optionName1" }, { name: "optionName2" }] }`
多选	multipleSelect	同「单选」
日期	date	`formatter` 取值：`YYYY-MM-DD` / `YYYY-MM-DD HH:mm` / `YYYY/MM/DD` / `YYYY/MM/DD HH:mm`
人员	user	`{ multiple: boolean }`（支持多选，默认为 true）
部门	department	`{ multiple: boolean }`（支持多选，默认为 true）
附件	attachment	无
单向关联	unidirectionalLink	`{ multiple: boolean, linkedSheetId: "xxx" }`（`linkedSheetId` 为关联的数据表 ID）
双向关联	bidirectionalLink	`{ multiple: boolean, linkedSheetId: "xxx", linkedFieldId: "yyy" }`（创建字段时 `linkedFieldId` 不传）
链接	url	无

记录值格式

记录值（又称字段值）展示，如下图所示：记录值格式

记录值格式

不同字段类型所使用的格式请参考下表：

字段名	类型 (type)	设置值（新增/更新记录时使用的格式）	返回值（返回记录值时返回的格式）
文本	text	`"TextString"`（字符串）	`"TextString"`（字符串）
数字	number	`123`（支持整数 / 浮点数 / 字符串）	`"123"`（数字值，以字符串形式返回）
货币	currency	`123`（支持整数 / 浮点数 / 字符串）	`"123"`（数字值，以字符串形式返回）
单选	singleSelect	`"optionName1"`（单选选项名）	`{ "id": "id", "name": "optionName1" }`（id 为选项 ID，name 为选项名）
多选	multipleSelect	`["optionName1", "optionName2"]`（多选选项名）	`[{ "id": "id1", "name": "optionName1" }, { "id": "id2", "name": "optionName2" }]`
日期	date	`1688601600000`（时间戳）或 `"2023-12-20 03:00"`（ISO 8601 字符串）	`1688601600000`（时间戳）
人员	user	`[{ unionId: "xxx" }]`	`[{ unionId: "xxx" }]`
部门	department	`[{ deptId: "xxx" }]`	`[{ deptId: "xxx" }]`
附件	attachment	具体请参考上传附件。	`[{ "filename": "image.xlsx", "size": 92250, "type": "xls", "url": "xxx" }]` 说明 url 是附件访问链接。- 当附件是在线文档时，其是在线文档链接，该链接没有访问时效。- 当附件是其它文件时，是一个有访问时效的下载链接，一段时间后该链接将无法访问。
单向关联	unidirectionalLink	`{ "linkedRecordIds": ["xxx", "yyy"] }`	`{ "linkedRecordIds": ["xxx", "yyy"] }` 说明 field property 中包含关联的 sheetId，配合这里返回的 recordId，可以通过调用获取记录接口去获取关联记录的值。
双向关联	bidirectionalLink	`{ "linkedRecordIds": ["xxx", "yyy"] }`	`{ "linkedRecordIds": ["xxx", "yyy"] }`
链接	url	`{ "text": "Dingtalk", "link": "https://dingtalk.io" }`	`{ "text": "Dingtalk", "link": "https://dingtalk.io" }`