Skip to main content

维格表 API 参考手册 (beta)

提醒:

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

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

建议:

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

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

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

介绍

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

注意:必须使用 https 请求,不能使用 http 请求。

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

请求和响应体均被编码为 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 GETPATCHDELETE 请求正常并按预期返回结果
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",}

获取记录

该接口用于获取指定维格表的记录。

右侧区域提供了 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 配合使用。例如 pageSize=1000&pageNum=2,返回 1001~2000 之间的记录。

sort
Array of objects[ items ]

对返回的记录进行排序。sort 是由多个排序对象 (sort object) 组成的数组。单个排序对象的结构为 {"order":"asc 或 desc", "field":"字段名称或字段 ID"}。查询示例:sort[][field]=客户名称&sort[][order]=asc,即按照「客户名称」列的字母升序来排列返回的记录。如果 sort 与 viewId 同时使用,则 sort 指定的排序条件将会覆盖视图里的排序条件。

recordIds
Array of strings
Example: recordIds=rec4zxfWB5uyM

返回一个指定的记录。获取多条记录示例:&recordIds=rec4zxfWB5uyM&recordIds=reclNflLgtzjY。如果查询中包含多个 recordIds={recordId},返回结果按照传入 recordId 的顺序排序。无分页,每次最多返回 1000 条记录。

viewId
string
Example: viewId=viwG9l1VPD6nH

不显式指定 viewId 时,返回全部记录和全部字段。显式指定 viewId 时,则按照指定视图中的排序来依次返回该视图中的所有记录。注意:视图中隐藏的字段,不会出现在返回结果中。

fields
Array of strings

限制在返回的记录结果只包含指定的字段。cURL 查询示例:1. &fields[]=姓名&fields[]=年龄(当 &fieldKey=name) 2. &fields[]=fldWooy3c3Puz&fields[]=fldEAr5y7Go5S(当 &fieldKey=id)。以上两种写法均会指定返回的记录只包含「姓名」「年龄」两列。

filterByFormula
string

使用智能公式来筛选记录。公式使用方式可参考《一分钟上手公式》。如果 filterByFormula 与 viewId 同时使用,则会返回指定视图中满足此公式的所有记录。查询示例:&filterByFormula={标题}="标题1"(需要用 encodeURIComponent() 函数对 {标题}="标题1" 进行转义编码),可以精确匹配「标题」这列中值为「标题1」的记录。

cellFormat
string
Default: "json"
Enum: "string" "json"

单元格中值的类型,默认为 json 类型。指定为 string 时,所有值都会自动转换为字符串格式。

fieldKey
string
Default: "name"
Enum: "name" "id"

查询字段和返回字段时所用的 key。默认使用 name(字段名称)。指定为 id 时将以 fieldId 作为查询和返回方式(使用 id 可以避免因修改字段名称而导致的代码失效问题)。

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

创建记录

该接口用于在指定的维格表中创建新的记录。单次请求最多可以创建 10 条记录。

右侧区域提供了 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) [ items ]

需要创建的记录数据,包括记录的字段和字段值。

fieldKey
string
Default: "name"
Enum: "name" "id"

写入字段和返回字段时所用的 key。默认使用 name(字段名称)。如果想以 fieldId 作为写入和返回方式,需要显式指定为 id(使用 id 可以避免因修改字段名称而导致的代码失效问题)。

Responses

Request samples

Content type
application/json
{
  • "records": [
    ],
  • "fieldKey": "name"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

更新记录

该接口用于更新指定维格表的记录。单次请求最多可以更新 10 条记录。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

对象 fields 包含一条记录中要更新的字段及对应的值,只有显式指定的字段会更新数据,没有被指定的字段会保留旧值。

如果需要清空某字段的值,可设置为 null。例如 "状态": null 将清除该记录对应的「状态」列的值。

如果你需要更详细的操作指导,可阅读「API 指南」的更新记录操作指南。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
datasheetId
required
string
Example: dst0Yj5aNeoHldqvf6

维格表 ID

query Parameters
viewId
string
Example: viewId=viwG9l1VPD6nH

不显式指定 viewId 时,返回全部不为空的字段;显式指定 viewId 时,返回指定视图中未隐藏且不为空的字段。

Request Body schema: application/json

请求体结构

records
required
array

需要更新的记录数据,包括记录的字段和字段值。

fieldKey
string
Default: "name"
Enum: "name" "id"

写入字段和返回字段时所用的 key。默认使用 name(字段名称)。如果想以 fieldId 作为写入和返回方式,需要显式指定为 id(使用 id 可以避免因修改字段名称而导致的代码失效问题)。

Responses

Request samples

Content type
application/json
{
  • "records": [
    ],
  • "fieldKey": "name"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

删除记录

该接口用于删除某个维格表的记录。单次请求最多可删除 10 条记录。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的删除记录操作指南。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
datasheetId
required
string
Example: dst0Yj5aNeoHldqvf6

维格表 ID

query Parameters
recordIds
required
Array of strings
Example: recordIds=recwZ6yV3Srv3

需要删除的记录的 ID。

Responses

Request samples

curl -X DELETE \
"https://api.vika.cn/fusion/v1/datasheets/{替换为你的 datasheetId}/records?recordIds={替换为想要删除的 recordId}" \
-H  "Authorization: Bearer {替换为你的 API Token}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": true
}

字段

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

字段的数据结构如下:

属性 类型 说明 示例值
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

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

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) 返回值类型,取值包括 StringBooleanNumberDateTimeArray
format 对象 (object) 当返回值类型为 NumberDateTime 时,返回对数字或者日期格式化操作的结果
  • 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) 格式化类型 DateTimeNumberPercentCurrency
    format 对象 (object) 不同格式化类型的具体格式

    格式化为日期:

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

    格式化为数字或百分比:

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

    格式化为货币:

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

Formula(智能公式)

返回结果示例片段(仅包含字段类型及属性):

{
    "type": "Formula",
    "property": {
        "expression": "",
        "valueType": "String",
        "hasError": false
    }
}
字段属性 数据类型 说明
expression string* 公式表达式
valueType string(enum)* 返回值类型,取值包括 StringBooleanNumberDateTimeArray
hasError boolean 当公式依赖的相关字段被删除或者转化类型时,可能无法正常获取计算值
format object 当返回值类型为 NumberDateTime 时候,返回对数字或者日期格式化操作,与 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

获取字段

该接口用于获取指定维格表中有权限查看的所有字段信息。

一张维格表最多可以创建 200 个字段。请求获取字段时一次性返回结果,不分页。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的获取字段操作指南。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
datasheetId
required
string
Example: dst0Yj5aNeoHldqvf6

维格表 ID

query Parameters
viewId
string
Example: viewId=viwG9l1VPD6nH

视图 ID,指定视图则返回的 fields 顺序和视图保持一致,隐藏的字段不会返回。

Responses

Request samples

curl -X GET \
"https://api.vika.cn/fusion/v1/datasheets/{替换为你的 datasheetId}/fields" \
-H "Authorization: Bearer {替换为你的 API Token}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

创建字段

该接口用于在指定的维格表中创建新的字段。单张维格表最多创建 200 个字段。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站 ID

datasheetId
required
string
Example: dstNiC6R9MryevVaCQ

数表 ID

Request Body schema: application/json

请求体结构

type
required
string

字段类型

name
required
string

字段名称, 不能多于100个字符

required
object

单行文本属性

Responses

Request samples

Content type
application/json
Example
{
  • "type": "SingleText",
  • "name": "标题",
  • "property": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

删除字段

该接口用于在指定的维格表中删除字段。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站 ID

datasheetId
required
string
Example: dstNiC6R9MryevVaCQ

数表 ID

fieldId
required
string
Example: fld7r18G7eSOu

字段 ID, 可以通过获取字段接口获取到字段ID

Responses

Request samples

curl -X DELETE \
"https://api.vika.cn/fusion/v1/spaces/spcjXzqVrjaP3/datasheets/dstNiC6R9MryevVaCQ/fields/fldxxxxxx" \
-H "Authorization: Bearer {你的 API Token}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": { }
}

视图

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

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

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

视图的数据结构如下:

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

获取视图

该接口用于获取指定维格表的所有视图。

请求获取视图时一次性返回结果,不分页。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的获取视图操作指南。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
datasheetId
required
string
Example: dst0Yj5aNeoHldqvf6

维格表 ID

Responses

Request samples

curl -X GET \
"https://api.vika.cn/fusion/v1/datasheets/{替换为你的 datasheetId}/views" \
-H "Authorization: Bearer {替换为你的 API Token}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

表格

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

创建表格

该接口用于在指定的空间站中创建含指定字段的维格表。单次请求最多可以在新建的维格表中创建 200 个字段。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站 ID

Request Body schema: application/json

请求体结构

name
required
string

表格名称,不能多于100个字符

description
string

表格描述,不能多于500个字符

folderId
string

所属文件夹ID,为空则默认为工作目录

preNodeId
string

前一个节点ID,为空则移到首位

Array of objects (FieldItemRo) [ items ]

字段列表,为空则新增3列默认字段

Responses

Request samples

Content type
application/json
{
  • "name": "我的表格",
  • "description": "这是一段描述",
  • "folderId": "fodn173Q0e8nC",
  • "preNodeId": "dstQJl6BGku1WfLPTD",
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

附件

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

上传附件

该接口用于上传一个附件,并将该附件绑定到一张维格表。

上传完附件后,附件数据并不会直接插入到表中,需要再调用「创建记录」或「更新记录」接口将附件数据插入到某个类型为「附件」的字段中。

每次请求只可上传一个附件。如果需要上传多份文件,需要重复调用此接口。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的上传附件操作指南。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
datasheetId
required
string
Example: dst0Yj5aNeoHldqvf6

维格表 ID

Request Body schema: multipart/form-data

请求体结构

file
required
string <binary>

需要上传的附件的本地绝对路径。

Responses

Request samples

curl -X POST \
"https://api.vika.cn/fusion/v1/datasheets/{替换为你的 datasheetId}/attachments" \
-H  "Authorization: Bearer {替换为你的 API Token}" \
-H  "Content-Type: multipart/form-data" \
-F "file=@{替换为你的本地文件路径}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

空间站

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

空间站的数据结构如下:

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

获取空间站列表

该接口用于获取当前请求用户创建或受邀进入的所有空间站。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的获取空间站列表操作指南。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

Responses

Request samples

curl -X GET \
"https://api.vika.cn/fusion/v1/spaces" \
-H "Authorization: Bearer {替换为你的 API Token}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

工作目录

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

文件的数据结构如下:

属性 类型 说明 示例值
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 信息,只有请求「获取文件详情」时才返回。

获取文件列表

该接口用于获取指定空间站的工作目录下最外层的文件列表。

可能获取的文件类型包括维格表、文件夹、收集表、仪表盘等。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的获取文件列表操作指南。

path Parameters
spaceId
required
string
Example: spczdmQDfBAn5

空间站 ID

Responses

Request samples

curl -X GET \
"https://api.vika.cn/fusion/v1/spaces/{替换为你的 spaceId}/nodes" \
-H  "Authorization: Bearer {替换为你的 API Token}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}

获取文件详情

该接口用于获取指定空间站的工作目录下指定文件的详细信息。

可能获取的文件类型包括维格表、文件夹、收集表、仪表盘等。

如果指定的文件类型是文件夹,会获取该文件夹下最外层的文件列表及详细信息;如果指定的文件是其他类型,会获取该文件的详细信息。

右侧区域提供了 cURL、Javascript SDK 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的获取文件详情操作指南。

如果你有更复杂的接口请求,可参考下列参数,自行组合。

path Parameters
spaceId
required
string
Example: spczdmQDfBAn5

空间站 ID

nodeId
required
string
Example: fodTXAYEmQ5rd

文件节点 ID,比如维格表 ID、文件夹 ID、收集表 ID 或者仪表盘 ID

Responses

Request samples

curl -X GET \
"https://api.vika.cn/fusion/v1/spaces/{替换为你的 spaceId}/nodes/{替换为你的 nodeId}" \
-H  "Authorization: Bearer {替换为你的 API Token}"

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "SUCCESS",
  • "data": {
    }
}