维格表 API 请求的基本 URL 是 https://api.vika.cn/fusion/v1/。

注意：必须使用 https 请求，不能使用 http 请求。

维格表 API 尽可能遵循 RESTful 惯例，即通过对空间站和维格表资源的 GET、POST、PATCH 和 DELETE 请求进行数据的增删改查。

请求和响应体均被编码为 JSON 格式。

JSON 中的参数名称使用驼峰命名法（如 viewId），对大小写敏感。

方式一：通过 API token

API Token 即用户认证令牌。向维格表服务器发送 API 请求时，必须在请求头里带上 Authorization: Bearer {你的 API Token}，方便服务器认证用户身份。

认证成功后，这份 API 请求会拥有该用户在维格表界面操作时相同的权限，即用户能够在界面上操作什么数据，这份请求也能操作什么数据。

以下面这段 cURL 请求为例：

curl "https://api.vika.cn/fusion/v1/datasheets/{datasheetId}/records" \
  -H "Authorization: Bearer {你的 API Token}" \

其请求头包括：

名称	数据类型	必填	值的格式	示例值
Authorization	字符串 (string)	是	Bearer {你的 API Token}	Bearer uskYtInkHozfsMikhh0yfoS

具体的认证操作可参考「API 指南」中的快速上手。

方式二：通过 OAuth2（后续支持，敬请期待）

发送 API 请求时，你需要注意以下几种限制：频率限制、接口限制、用量限制。

频率限制

同一个用户对同一张表的 API 请求频率上限为 5 次/秒。

请求频率超过限制时，会提示错误“操作太频繁”（错误状态码 429）。

接口限制

• 获取记录接口：一次最多获取 1000 行记录。

  比如想批量获取 10000 行记录，至少需要调用 10 次获取记录接口。

• 创建记录接口：一次最多创建 10 行记录。

  比如想批量创建 1000 行记录，至少需要调用 100 次创建记录接口。

• 更新记录接口：一次最多更新 10 行记录。

  比如想批量更新 1000 行记录，至少需要调用 100 次更新记录接口。

• 删除记录接口：一次最多删除 10 行记录。

  比如想批量删除 1000 行记录，至少需要调用 100 次删除记录接口。

• 上传附件接口：一次只可上传 1 个附件。

  如果需要上传多份文件，需要重复调用此接口。

用量限制

用量限制包含两种：一是 API 用量的限制；二是空间站资源用量的限制。

青铜级和白银级空间站每月可免费调用 10000 次 API，累计用量每月账单日清零。

公测阶段，你可以创建最多 1000 张维格表。单个维格表最多支持创建 50000 行记录、200 个字段、30 个视图。

单个空间站上传附件的容量上限为 1 GB。

每次发送 API 请求时，程序都会返回业务状态码和对应消息。

如果请求失败，你可以根据返回的状态码及报错消息进行排查。

HTTP 状态码	返回消息	业务状态码	说明
200	SUCCESS	200	GET、PATCH、DELETE 请求正常并按预期返回结果
201	SUCCESS	200	POST 请求正常并按预期返回结果
200	找不到指定的维格表	301	可能的情况： ① 该维格表可能已被删除 ② 用户无法在自己的空间站列表中找到该维格表
200	上传附件失败	426	可能的情况： ① 附件超出 1 GB 的大小限制 ② 空间站的附件容量已达上限
200	上传附件个数超出限制	428	上传附件每次调用仅可上传一个，超出会报此错误
200	无节点权限操作	602	用户无指定维格表的访问权限（比如可管理、可编辑或只读）
200	（参考具体的错误消息）	400	参数异常，数据校验异常
401	身份认证失败	401	可能的情况： ① 请求头没有传入 API Token ② API Token 不正确
403	禁止访问	403	可能的情况： ① API 调用次数已经超出限制 ② 无法获得空间站的 API 用量额度，请稍后再试
404	接口不存在	404	请检查请求地址是否正确
429	操作太频繁	429	同一用户对同一张表的请求频率上限为 5 次/秒
500	SERVER_ERROR (code)	500	内部服务发生未处理的异常
200	您的功能使用量已经超出「公测版」50000行的限制	304	表的行数已经达到单表行数上限，请尽快更换数表，以免出现数据丢失的情况

目前维格表开放获取记录、创建记录、更新记录、删除记录的接口。

记录的数据结构如下：

属性	类型	说明	示例值
recordId	string*	记录 ID	rec1jV9eWxcaB
createdAt	number*	该记录的创建时间，为时间戳格式	1624960629000
updatedAt	number*	该记录的修改时间，为时间戳格式	1624964696000
fields	object*	一条记录里对应字段的数据，返回格式为 {"field": "value"}	{"状态":"进行中"} 或者 {"created": 1624960629065, "updated": 1624964696235, "分类": ["修复中","P0"], "问题描述": "一个小 bug",}

目前维格表仅开放获取字段的接口。

字段的数据结构如下：

属性	类型	说明	示例值
id	string*	字段 ID	fldsRHWJZwFcM
name	string*	字段名称	单号
type	string*	字段类型，可能的值见字段类型及属性一节中列举的字段	SingleText
editable	boolean*	字段权限，即列权限，true 为可编辑，false 为只读	true
property	object	字段属性。不同的字段有不同的属性，详见字段类型及属性一节各种字段的属性说明	{"defaultValue":"待补充"}
isPrimary	boolean	是否为主数据列	true
desc	string	字段描述，即列描述	这一列是自动生成的单号，不要手动修改

字段类型及属性

维格表目前有如下字段类型：

接口返回的字段类型	对应的维格列类型
SingleText	单行文本
Text	多行文本
SingleSelect	单选
MultiSelect	多选
Number	数字
Currency	货币
Percent	百分比
DateTime	日期
Attachment	附件
Member	成员
Checkbox	勾选
Rating	评分
URL	网址
Phone	电话
Email	邮箱
MagicLink	神奇关联
MagicLookUp	神奇引用
Formula	智能公式
AutoNumber	自增数字
CreatedTime	创建时间
LastModifiedTime	修改时间
CreatedBy	创建人
LastModifiedBy	更新人

下面将详细说明各字段类型的属性。

SingleText（单行文本）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "SingleText",
    "property": {
        "defaultValue": ""
    }
}

字段属性	数据类型	说明
defaultValue	字符串 (string)	新建记录时，此字段对应单元格的默认值，默认为空

Text（多行文本）

暂无字段属性。

SingleSelect（单选）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "SingleSelect",
    "property": {
        "options": [
            {
                "id": "optpTVSGk0R2M",
                "name": "Elevit",
                "color": {
                    "name": "indigo_4",
                    "value": "#5586FF"
                }
            },
            {
                "id": "optqX2Bw479FG",
                "name": "OAD",
                "color": {
                    "name": "blue_4",
                    "value": "#55CDFF"
                }
            }
        ]
    },
}

字段属性	数据类型	说明
options	对象数组	所有可选项列表

options 下包含的参数说明：

参数	数据类型	说明
id	字符串 (string)	选项 ID
name	字符串 (string)	选项名称
color	对象 (object)	选项颜色，包含颜色的名称和色值

MultiSelect（多选）

字段属性与单选相同。

Number（数字）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "Number",
    "property": {
        "defaultValue":"2",
        "precision": 0,
        "commaStyle": ",",
        "symbol": "平方米",
    }
}

字段属性	数据类型	说明
defaultValue	字符串 (string)	新建记录时，此字段对应单元格的默认值，默认为空
precision	数值 (number)	表示小数点的位数，即数字精度。取值有 0（代表整数）、1（精确到小数点后一位）、2（精确到小数点后两位）、3（精确到小数点后三位）、4（精确到小数点后四位）
commaStyle	字符串 (string)	千分位分隔符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000。默认为空（可选）
symbol	字符串 (string)	数字单位，显示在数字的右边，默认为空（可选）

Currency（货币）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "Currency",
    "property": {
        "defaultValue": "1000.00",
        "precision": 2,
        "symbol": "¥",
        "symbolAlign": "Default",
    }
}

字段属性	数据类型	说明
defaultValue	字符串 (string)	新建记录时，此字段对应单元格的默认值，默认为空
precision	数值 (number)	表示小数点的位数，即数字精度。取值有 0（代表整数）、1（精确到小数点后一位）、2（精确到小数点后两位）、3（精确到小数点后三位）、4（精确到小数点后四位）
symbol	字符串 (string)	货币符号，可以是自定义的任意字符
symbolAlign	字符串 (string)	货币符号的对齐方式（可选）。默认值为 Default（货币单位紧挨在数值的左边），其他取值有 Left（货币单位固定到左边）、Right（货币单位固定到右边）。

Percent（百分比）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "Percent",
    "property": {
        "defaultValue":"0.85",
        "precision": 1
    }
}

字段属性	数据类型	说明
defaultValue	字符串 (string)	新建记录时，此字段对应单元格的默认值，默认为空
precision	数值 (number)	表示将字段值转换为百分比后小数点的位数，即百分比精度。取值有 0（代表整数）、1（精确到小数点后一位）、2（精确到小数点后两位）、3（精确到小数点后三位）、4（精确到小数点后四位）。例如：字段值为 0.22 时，如果百分比精度为 0，则展示为 22%；如果百分比精度为 1，则展示为 22.0%

DateTime（日期）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "DateTime",
    "property": {
        "format": "YYYY/MM/DD hh:mm",
        "includeTime": true,
        "autoFill": true
    }
}

字段属性	数据类型	说明
format	字符串 (string)	日期格式
autoFill	布尔型 (boolean)	新建记录时，是否自动填充时间
includeTime	布尔型 (boolean)	是否显示时间

日期字段的值会返回时间戳，不限制格式。字段属性中 format 信息可用于格式化，含义参见 dayjs format。

如果你不想处理日期格式化，希望返回结果和视图展示内容保持一致，可以在接口请求参数中赋值 cellFormat 为 string，则返回的内容全部为字符串。

Attachment（附件）

暂无字段属性。

Member（成员）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "Member",
    "property": {
        "options": [
            {
                "id": "1385370606558318594",
                "name": "Coco",
                "type": "Member",
                "avatar": "https://s1.vika.cn/default/avatar004.jpg"
            }
        ],
        "isMulti": true,
        "shouldSendMsg": true
    }
}

字段属性	数据类型	说明
options	对象数组	当前成员字段已经选过的成员
isMulti	布尔型 (boolean)	是否可以选择多个成员
shouldSendMsg	布尔型 (boolean)	成员列中提及某成员时，是否向其发送站内消息通知

options 下包含的参数说明：

参数	数据类型	说明
id	字符串 (string)	用户在当前空间站的组织单元 id（和实际的用户 id 不同），以下简称成员 id。比如张三在 A 空间站中的成员 id 与他在 B 空间站中的成员 id 是不一样的
name	字符串 (string)	成员名称
type	字符串 (string)	成员类型，取值包括 Member（指有实体账号的用户）和 Team（指空间站内的组织单元，比如部门、小组等）
avatar	字符串 (string)	成员头像的网址 URL

Checkbox（勾选）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "Checkbox",
    "property": {
        "icon": "✅"
    }
}

字段属性	数据类型	说明
icon	字符串 (string)	勾选值的图标表示，一般为 emoji 字符

Rating（评分）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "Rating",
    "property": {
        "icon": "⭐",
        "max": 5
    }
}

字段属性	数据类型	说明
icon	字符串 (string)	评分值的图标表示，一般为 emoji 字符，比如 ⭐ 或 🎉
max	数值 (number)	评分最大值，取值为 1-10

URL（网址）

暂无字段属性。

Phone（电话）

暂无字段属性。

Email（邮箱）

暂无字段属性。

MagicLink（神奇关联）

两张表 A 与 B 通过神奇关联字段连接，在 A 中会有关联到 B 的关联字段，在 B 中也会有关联到 A 的关联字段。这一对关联字段被称为 兄弟字段。

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "MagicLink",
    "property": {
        "foreignDatasheetId": "dstgr2YN264s7CXKVs",
        "brotherFieldId": "fldyv9fOeCx8B",
        "limitToViewId": "viwY4B8pmiMoi",
        "limitSingleRecord": true
    }
}

字段属性	数据类型	说明
foreignDatasheetId	字符串 (string)	关联表 ID
brotherFieldId	字符串 (string)	关联表中兄弟字段 ID
limitToViewId	字符串 (string)	指定关联表的一个视图，限制只能选取该视图下的记录
limitSingleRecord	布尔型 (boolean)	是否只能选取单条记录

MagicLookUp（神奇引用）

神奇引用是依附于神奇关联存在的一种字段，它是一个动态的计算字段，单元格本身不存储任何值。

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "MagicLookUp",
    "property": {
        "relatedLinkFieldId": "fldhBGpM3ylTq",
        "targetFieldId": "fldS2mgS18LE1",
        "rollupFunction": "VALUES",
        "valueType": "Array",
        "entityField": {
            "datasheetId": "dstgr2YN264s7CXKVs",
            "field": {
                "id": "fldS2mgS18LE1",
                "name": "title",
                "type": "SingleText",
                "property": {
                    "defaultValue": ""
                },
                "editable": true
            }
        }
    }
}

字段属性	数据类型	说明
relatedLinkFieldId	字符串 (string)	引用的当前表的关联字段 ID
targetFieldId	字符串 (string)	关联表中查询的字段 ID
hasError	布尔型 (boolean)	当神奇引用的依赖的关联字段被删除或者转化类型时，可能无法正常获取引用值
entityField	对象 (object)	最终引用到的实体字段，不包含神奇引用类型的字段。存在错误时，实体字段可能不存在。
rollupFunction	字符串 (string)	汇总函数
valueType	字符串 (string)	返回值类型，取值包括 String、Boolean、Number、DateTime、Array
format	对象 (object)	当返回值类型为 Number 或 DateTime 时，返回对数字或者日期格式化操作的结果

• rollupFunction 的取值说明（参数含义参考 神奇引用产品手册）：

  函数名	返回值类型	说明
  VALUES	array	原样引用
  AVERAGE	number	平均数
  COUNT	number	非空数值计数
  COUNTA	number	非空值计数
  COUNTALL	number	全计数
  SUM	number	总和
  MIN	number/datetime	最小值
  MAX	number/datetime	最大值
  AND	boolean	和运算
  OR	boolean	或运算
  XOR	boolean	异或运算
  CONCATENATE	string	连接成文本
  ARRAYJOIN	string	逗号连接
  ARRAYUNIQUE	array	去重
  ARRAYCOMPACT	array	过滤所有空值

• entityField 下包含的参数说明：

  参数	数据类型	说明
  datasheetId	字符串 (string)	实体字段的表 ID
  field	对象 (object)	除了 LookUp 外的 Field 对象，神奇引用可以引用其他表的神奇引用类型的字段，但最终会存在一个实体字段。

  注意：如果你的应用中使用了此字段的特性，在检测到字段存在引用错误时，需要处理好异常情况。

• format 下包含的参数说明：

  参数	数据类型	说明
  type	字符串 (string)	格式化类型 DateTime、Number、Percent、Currency
  format	对象 (object)	不同格式化类型的具体格式

  格式化为日期：

  参数	数据类型	说明
  dateFormat	字符串 (string)	日期格式，比如 YYYY/MM/DD
  timeFormat	字符串 (string)	时间格式，比如 hh:mm、HH:mm
  includeTime	布尔型 (boolean)	是否显示时间

  格式化为数字或百分比：

  参数	数据类型	说明
  precision	数值 (number)	数字精度或百分比精度

  格式化为货币：

  参数	数据类型	说明
  precision	数值 (number)	精度
  symbol	字符串 (string)	货币符号

Formula（智能公式）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "Formula",
    "property": {
        "expression": "",
        "valueType": "String",
        "hasError": false
    }
}

字段属性	数据类型	说明
expression	string*	公式表达式
valueType	string(enum)*	返回值类型，取值包括 String、Boolean、Number、DateTime、Array
hasError	boolean	当公式依赖的相关字段被删除或者转化类型时，可能无法正常获取计算值
format	object	当返回值类型为 Number 或 DateTime 时候，返回对数字或者日期格式化操作，与 lookup 返回的 format 格式相同

和神奇引用相同，遇到错误时，需要处理异常情况。

AutoNumber（自增数字）

暂无字段属性。

CreatedTime（创建时间）

与 DateTime 相同。

LastModifiedTime（修改时间）

与 DateTime 相同。

CreatedBy（创建人）

成员 id 是空间站级别的，创建人 id 是账号级别的。

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "CreatedBy",
    "property": {
        "options": [
            {
                "id": "e9cbc839fd1b49be85b1f7b0977047e2",
                "name": "Coco",
                "avatar": "https://s1.vika.cn/default/avatar004.jpg"
            }
        ]
    }
}

字段属性	数据类型	说明
options	option[]	当前成员字段已经选过的成员

options 下包含的参数说明：

参数	数据类型	说明
id	string*	用户 id
name	string*	用户昵称
avatar	string*	用户头像的网址 URL

LastModifiedBy（更新人）

返回结果示例片段（仅包含字段类型及属性）：

{
    "type": "LastModifiedBy",
    "property": {
        "options": [
            {
                "id": "e9cbc839fd1b49be85b1f7b0977047e2",
                "name": "Coco",
                "avatar": "https://s1.vika.cn/default/avatar004.jpg"
            }
        ]
    }
}

字段属性	数据类型	说明
options	option[]	当前字段存储过的用户

options 下包含的参数说明：

参数	数据类型	说明
id	string*	用户 id
name	string*	用户昵称
avatar	string*	用户头像的网址 URL

目前维格表仅开放获取视图的接口。

视图是数据的不同展示形式，分为维格视图、看板视图、相册视图、甘特视图等不同类型。视图中可单独设置筛选、分组、排序等。

一张维格表可以建立最多 30 个视图。

视图的数据结构如下：

属性	类型	说明	示例值
id	string*	视图 ID	viwpdA8TUBp5r
name	string*	视图名称	全部订单
type	string (enum)*	视图类型，可能的值有 Grid（维格视图）、Gallery（相册视图）、Kanban（看板视图）、Gantt（甘特视图）	Grid

目前维格表仅开放创建表格的接口。

目前维格表仅开放上传附件的接口。

目前维格表仅开放获取空间站列表的接口。

空间站的数据结构如下：

属性	类型	说明	示例值
id	string*	空间站 ID	spcX9P2xUcKst
name	string*	空间站名称	测试空间站
isAdmin	boolean	当前请求用户是否是此空间站的主管理员	true

目前维格表开放获取文件列表、获取文件详情的接口。

文件的数据结构如下：

属性	类型	说明	示例值
id	string*	文件 ID	fodvfSPGFPmFH
name	string*	文件名称	研发部
icon	string	文件图标	🤠
type	string (enum)*	文件类型，可能的值有 Datasheet（维格表）、Folder（文件夹）、Form（收集表）、Dashboard（仪表盘）	Folder
isFolder	boolean	是否是文件夹	true
isFav	boolean	是否已标记此文件为星标	true
children	array of nodes	仅当文件类型为 Folder 时，会返回 children 信息。children 下为文件夹下一层的文件列表	true

请求「获取文件列表」时，如果返回结果包含文件夹，不会返回 children 信息，只有请求「获取文件详情」时才返回。