维格表 API 参考手册 (beta)

提醒：
当前 API 处于 beta 阶段，我们可能会添加新的接口返回值属性，但不会删除已经存在的属性。如果 API 没有返回你需要的数据，欢迎向我们反馈。

这份参考手册旨在帮助你全面了解维格表 API。

建议：
如果你之前未了解过维格表 API，推荐你从维格表 API 简介开始阅读。

通过本页面左边的导航区域，你可以找到每种 API 接口（包括记录、字段、视图、附件、空间站、工作目录）的详细信息。

通过本页面右边的代码区域，你可以找到每种 API 接口的请求示例和响应示例，方便你直接复制需要的代码。

介绍

维格表 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 请求为例：

其请求头包括：

名称	数据类型	必填	值的格式	示例值
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	表的行数已经达到单表行数上限，请尽快更换数表，以免出现数据丢失的情况

维格表 API 参考手册 (beta)

介绍#

认证#

方式一：通过 API token#

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

限制#

频率限制#

接口限制#

用量限制#

状态码#

介绍

认证

方式一：通过 API token

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

限制

频率限制

接口限制

用量限制

状态码