|
|
维格表 API 参考手册 ( beta )
当前 API 处于 beta 阶段，我们可能会添加新的接口返回值属性，但不会删除已经存在的属性。如果 API 没有返回你需要的数据，欢迎向我们 反馈 。
这份参考手册旨在帮助你全面了解维格云 API。
如果你之前未了解过维格云 API，推荐你从 维格云 API 简介 开始阅读。
通过本页面左边的导航区域，你可以找到每种 API 接口（包括记录、字段、视图、附件、空间站、工作目录）的详细信息。
通过本页面右边的代码区域，你可以找到每种 API 接口的请求示例和响应示例，方便你直接复制需要的代码。
方式一：通过 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方式二：通过 OAuth2（后续支持，敬请期待）
发送 API 请求时，你需要注意以下几种限制：频率限制、接口限制、用量限制。
同一个用户对同一张表的 API 请求频率上限为 ：
青铜级（免费版）：2 QPS，适合 API 学习和体验
白银级：5 QPS，适合个人应用的搭建
黄金级：10 QPS，适合团队应用的开发和运行
企业级：20 QPS，适合企业级內部应用的搭建和高并发场景
请求频率超过限制时，会提示错误“操作太频繁”（错误状态码 429）,详情见：
维格云价目表
获取记录接口：一次最多获取 1000 行记录。
比如想批量获取 10000 行记录，至少需要调用 10 次获取记录接口。
创建记录接口：一次最多创建 10 行记录。
比如想批量创建 1000 行记录，至少需要调用 100 次创建记录接口。
更新记录接口：一次最多更新 10 行记录。
比如想批量更新 1000 行记录，至少需要调用 100 次更新记录接口。
删除记录接口：一次最多删除 10 行记录。
比如想批量删除 1000 行记录，至少需要调用 100 次删除记录接口。
上传附件接口：一次只可上传 1 个附件。
如果需要上传多份文件，需要重复调用此接口。
API 用量
1 万次请求/月
10 万次请求/月
50 万次请求/月
250 万次请求/月
1GB 默认
席位数 * 5GB
席位数 * 7GB
席位数 * 10GB
每次发送 API 请求时，程序都会返回业务状态码和对应消息。
如果请求失败，你可以根据返回的状态码及报错消息进行排查。
HTTP 状态码
业务状态码
SUCCESS
GET
、
PATCH
、
DELETE
请求正常并按预期返回结果
SUCCESS
POST
请求正常并按预期返回结果
找不到指定的维格表
可能的情况：
① 该维格表可能已被删除
② 用户无法在自己的空间站列表中找到该维格表
上传附件失败
可能的情况：
① 附件超出 1 GB 的大小限制
② 空间站的附件容量已达上限
上传附件个数超出限制
上传附件每次调用仅可上传一个，超出会报此错误
无节点权限操作
用户无指定维格表的访问权限（比如可管理、可编辑或只读）
（参考具体的错误消息）
参数异常，数据校验异常
身份认证失败
可能的情况：
① 请求头没有传入 API Token
② API Token 不正确
可能的情况：
① API 调用次数已经超出限制
② 无法获得空间站的 API 用量额度，请稍后再试
接口不存在
请检查请求地址是否正确
操作太频繁
同一用户对同一张表的请求频率有上限，详情见：
维格云价目表
SERVER_ERROR (code)
内部服务发生未处理的异常
您的功能使用量已经超出「公测版」50000行的限制
表的行数已经达到单表行数上限，请尽快更换，以免出现数据丢失的情况
目前维格云开放获取记录、创建记录、更新记录、删除记录的接口。
记录（Record）的数据结构如下：
recordId
string
该记录的 ID，示例值：
"rec1jV9eWxcaB"
createdAt
number
该记录的创建时间，为时间戳格式，示例值：
1624960629000
updatedAt
number
该记录的修改时间，为时间戳格式，示例值：
1624964696000
fields
object
一条记录里对应字段的数据，返回格式为
{"fieldName": fieldValue}
使用
创建记录
或
更新记录
接口对表格字段进行写入操作时，需要了解每种字段值的数据类型和结构。
需注意：动态计算类型的字段（自增数字、公式、神奇引用、修改时间、创建时间、修改人、创建人）不允许主动写入值。
为方便参考，下表列举了不同类型字段的值：
Field Type(字段类型)
SingleText(单行文本)
string
单行文本，适合保存不带换行符的文本，例如文章的标题
例：
{"fieldName": "an example title"}
Text(多行文本)
string
多行文本，可用于存放较长的文本内容，例如一篇学术论文
例：
{"fieldName": "a long text"}
SingleSelect(单选)
string
已选中的选项文本值。当创建/更新记录时，提交的选项值不存在于选项列表，则会返回错误码400，并提示“参数错误”
例：
{"fieldName": "done"}
MultiSelect(多选)
array of strings
已选中的若干选项文本值组成的数组。当创建/更新记录时，提交的选项值不存在于选项列表，则会返回错误码400，并提示“参数错误”
例：
{"fieldName": ["Option1", "Option2"]}
Number(数字)
number
数值，支持负值。通过api读取此字段的值，精度不受列配置影响，只会原样返回
例：
{"fieldName": 1998}
Currency(货币)
number
数值，支持负值。通过api读取此字段的值，精度不受列配置影响，只会原样返回
例：
{"fieldName": 999}
Percent(百分比)
number
数值，支持负值。通过api读取此字段的值，精度不受列配置影响，只会原样返回
例：
{"fieldName": 0.1}
DateTime(日期)
number
日期和时间，以毫秒（ms）为单位返回时间戳
例：
{"fieldName": 1678723200000}
Attachment(附件)
array of attachment objects
由若干“附件对象”组成的数组，每一个附件对象应该包含下列属性：
- mimeType : string，附件的媒体类型
- name: string，附件的名称
- size: number，附件的大小，单位为字节
- width: number， 如果附件是图片格式，表示图片的宽度，单位为px
- height: number，如果附件是图片格式，表示图片的高度，单位为px
- token: string，附件的访问路径
- preview: string，如果附件是PDF格式，将会生成一个预览图，用户可以通过此网址访问
例：
{"fieldName":[{"id":"atcFagvJrELTS","name":"logo.png","size":6396,"mimeType":"image/png","token":"space/2023/03/17/ee1bb79d3fd847e383e21c9b0bd53dfc","width":424,"height":80,"url":"https://s1.vika.com/space/2023/03/17/ee1bb79d3fd847e383e21c9b0bd53dfc"}]}
Member(成员)
array of unit objects
由若干「组织单元（unit）」对象构成的数组，「组织单元」是维格表中描述“空间站”与“成员”之间的关系的一个抽象概念。成员（member）、小组（team）都是一种组织单元。每一个「组织单元」对象应该包含下列属性：
- id: string，组织单元的ID
- type: number，组织单元的类型，1是小组，3是成员
- name: string，小组或成员的名称
- avatar: string，头像URL，只读，不可写入
例：
{"fieldName":[{"id":"1291258301781176321","type":3,"name":"Jane","avatar":"https://s1.vika.com/space/2023/02/09/79e112dd10424ac7842256736e4f5568"}]}
Checkbox(勾选)
boolean
布尔类型的true 或 空。当此字段被勾选时返回“true”。除此以外，记录中不返回此字段
例：
{"fieldName": true}
Rating(评分)
number
评分值是 1-9 之间的一个正整数如果单元格为空或者撤销评分，则记录中不返回此字段
例：
{"fieldName": 5}
URL(网址)
object
返回一个 URL 对象，其中包括 title(网页标题)、text(网页地址)、favicon(网页 ICON)
例：
{"fieldName":{"title":"vika","text":"https://vika.cn", "favicon":"https://s1.vika.cn/space/2022/12/20/73456950217f4f79b20c7ef1a49acf6e"}}
Phone(电话)
string
电话号码（字符串）
例：
{"fieldName": "138xxxx7240"}
Email(邮箱)
string
邮件地址（字符串）
例：
{"fieldName": "[email protected]"}
MagicLink(神奇关联)
array of record IDs
由多条已关联记录的ID组成的数组
例：
{"fieldName": ['recz9eeg61SEa', 'recz97eg81ScD']}
MagicLookUp(神奇引用)
array of any
A表与B表通过神奇关联字段进行表关联后，可使用此字段对B表的任意字段进行引用，视乎引用方式的不同，而返回不同数据类型的运算值。如果引用方式选择了「原样引用」，则运算结果的数据类型保持与B表源字段一致；其他引用方式皆返回数字类型的运算值
例：
{"fieldName": ['Reference data 1', 'Reference data 2']}
Formula(智能公式)
string | number | boolean
经过公式和函数运算后的结果，数据类型可能是数字、字符串、布尔值。此字段是计算字段，创建/更新记录时不支持写入
AutoNumber(自增数字)
number
数值，正整数。创建记录时自动生成，不支持手动写入
例：
{"fieldName": 1}
获取记录
请求地址：
https://api.vika.cn/fusion/v1/datasheets/{datasheetId}/records
请求方法：
GET
请求头必须包含：
Authorization: Bearer {你的 API Token}
右侧区域提供了 cURL、Javascript SDK 的请求示例，供你参考。
如果你需要更详细的操作指导，可阅读「API 指南」的
获取记录
操作指南。
如果你有更复杂的接口请求，可参考下列参数，自行组合。
path
Parameters
|
datasheetId
required
|
string
Example:
dst0Yj5aNeoHldqvf6
维格表 ID |
query
Parameters
| pageSize |
number
Default:
100
Example:
pageSize=100
每页返回多少条记录。默认每页返回 100 条记录。取值范围为 1~1000 的整数。 |
| maxRecords |
number
Example:
maxRecords=1000
总共返回多少条记录。如果 maxRecords 与 pageSize 同时使用，且 maxRecords 的值小于总记录数，则只生效 maxRecords 的设置。 |
| pageNum |
number
Default:
1
Example:
pageNum=1
指定分页的页码，与参数 pageSize 配合使用。例如
|
| sort |
Array of
objects
对返回的记录进行排序。sort 是由多个排序对象 (sort object) 组成的数组。单个排序对象的结构为
|
| recordIds |
Array of
strings
Example:
recordIds=rec4zxfWB5uyM
返回一个指定的记录。获取多条记录示例：
|
| viewId |
string
Example:
viewId=viwG9l1VPD6nH
不显式指定 viewId 时，返回全部记录和全部字段。显式指定 viewId 时，则按照指定视图中的排序来依次返回该视图中的所有记录。注意：视图中隐藏的字段，不会出现在返回结果中。 |
| fields |
Array of
strings
限制在返回的记录结果只包含指定的字段。cURL 查询示例：1.
|
| filterByFormula |
string
使用智能公式来筛选记录。公式使用方式可参考
《一分钟上手公式》
。如果 filterByFormula 与 viewId 同时使用，则会返回指定视图中满足此公式的所有记录。查询示例：
|
| cellFormat |
string
Default:
"json"
Enum
:
"string"
"json"
单元格中值的类型，默认为
|
| fieldKey |
string
Default:
"name"
Enum
:
"name"
"id"
查询字段和返回字段时所用的 key。默认使用
|
Responses
Request samples
-
cURL -
JavaScript SDK
curl -X GET \
"https://api.vika.cn/fusion/v1/datasheets/{替换为你的 datasheetId}/records" \
-H "Authorization: Bearer {替换为你的 API Token}"
Response samples
-
200
Content type
application/json
]
,
"pageSize"
:
100
,
"total"
:
500
}
}
创建记录
该接口用于在指定的维格表中创建新的记录。单次请求最多可以创建 10 条记录。
请求地址：
https://api.vika.cn/fusion/v1/datasheets/{datasheetId}/records
请求方法：
POST
请求头必须包含：
-
Authorization: Bearer {你的 API Token}
-
Content-Type：application/json
右侧区域提供了 cURL、Javascript SDK 的请求示例，供你参考。
POST 的数据包会包含一个
records
数组，其中包含若干条将要创建的记录。
对象
fields
包含一条记录中要新建的字段及对应的值，可以包含任意数量的字段值，没有显式指定的字段将会留空。
如果你需要更详细的操作指导，可阅读「API 指南」的
创建记录
操作指南。
如果你有更复杂的接口请求，可参考下列参数，自行组合。
path
Parameters
|
datasheetId
required
|
string
Example:
dst0Yj5aNeoHldqvf6
维格表 ID |
query
Parameters
| viewId |
string
Example:
viewId=viwG9l1VPD6nH
不显式指定 viewId 时，返回全部不为空的字段；显式指定 viewId 时，返回指定视图中未隐藏且不为空的字段。 |
Request Body schema:
application/json
请求体结构
|
required
|
Array of
objects
(
FieldCreateRo
)
需要创建的记录数据，包括记录的字段和字段值。 |
| fieldKey |
string
Default:
"name"
Enum
:
"name"
"id"
写入字段和返回字段时所用的 key。默认使用
|
Responses
Request samples
-
Payload -
cURL -
JavaScript SDK
Content type
application/json
}
,
}
]
,
"fieldKey"
:
"name"
}
Response samples
-
201
Content type
application/json
]
}
}