跳到主要内容

维格表 API 参考手册 (beta)

提醒:

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

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

建议:

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

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

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

介绍

维格云 API 请求的基本 URL 是 https://vika.cn

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

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

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

JSON 中的参数名称使用驼峰命名法(如 viewId),对大小写敏感。

认证

方式一:通过 API token

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

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

以下面这段 cURL 请求为例:

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

其请求头包括:

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

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

方式二:通过 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 状态码 返回消息 业务状态码 说明
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 同一用户对同一张表的请求频率有上限,详情见:维格云价目表
500 SERVER_ERROR (code) 500 内部服务发生未处理的异常
200 您的功能使用量已经超出「公测版」50000行的限制 304 表的行数已经达到单表行数上限,请尽快更换,以免出现数据丢失的情况

记录

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

记录(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://s4.vika.cn/space/2022/12/20/73456950217f4f79b20c7ef1a49acf6e"}}
Phone(电话) string
电话号码(字符串)
例:{"fieldName": "138xxxx7240"}
Email(邮箱) string
邮件地址(字符串)
例:{"fieldName": "support@vikadata.com"}
WorkDoc(轻文档) array of workdoc objects
由若干“轻文档对象”组成的数组,每一个轻文档对象包含下列属性:
- documentId : string,文档ID
- title: string,文档标题
例:{"fieldName":[{"documentId":"docCqiLTtyx4l","title":"I am title"}]}
OneWayLink(单向关联) array of record IDs
由多条已关联记录的ID组成的数组
例:{"fieldName": ['recz9eeg61SEa', 'recz97eg81ScD']}
TwoWayLink(双向关联) 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}

获取记录

该接口用于获取指定维格表的记录。该接口支持搭载全新数据引擎的 Fusion API v3,能够提供提供更出色的性能以及更高效的 API 体验,详情请查看 Fusion API v3

右侧区域提供了 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

对返回的记录进行排序。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,reclNflLgtzjY。返回结果按照传入 recordId 的顺序排序。无分页,每次最多返回 1000 条记录。

viewId
string
Example: viewId=viwG9l1VPD6nH

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

fields
Array of strings

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

filterByFormula
string

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

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

单元格中值的类型,默认为 json 类型。指定为 string 时,所有值都会自动转换为字符串格式。 当指定为 string,并且返回的记录中包含日期类型的值时,日期值将按照如下顺序(优先级从高到低)确定使用哪一个时区:

  1. 如果日期字段设置了时区,使用日期字段设置的时区。
  2. 如果用户帐户设置了时区,使用帐户时区。
  3. 使用默认时区(UTC+8,中国标准时区)。
fieldKey
string
Default: "name"
Enum: "name" "id"

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

Responses

Request samples

curl -X GET \
"https://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)

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

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 of arrays

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

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
string
Example: recordIds=recwZ6yV3Srv3,recwXXyV12454

需要删除的记录 ID,多条记录用逗号分隔,一次请求最多可删除 10 条。

Responses

Request samples

curl -X DELETE \
"https://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
字段名称
例: "Order number"
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 邮箱
WorkDoc 轻文档
OneWayLink 单向关联
TwoWayLink 双向关联
MagicLookUp 神奇引用
Formula 智能公式
AutoNumber 自增数字
CreatedTime 创建时间
LastModifiedTime 修改时间
CreatedBy 创建人
LastModifiedBy 更新人
Button 按钮

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

当调用「获取字段」接口时,各字段类型返回结果如下所示:

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 object arrays 所有可选项列表

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": {
    "dateFormat": "YYYY/MM/DD hh:mm",
    "includeTime": true,
    "timeFormat": "hh:mm",
    "autoFill": true,
    "timeZone": "Asia/Shanghai",
    "includeTimeZone": true
  }
}
字段属性 数据类型 说明
dateFormat string(enum)* YYYY/MM/DD,YYYY-MM-DD,DD/MM/YYYY,YYYY-MM,MM-DD,YYYY,MM,DD
includeTime boolean 是否显示时间
timeFormat string(enum) HH:mm,hh:mm
autoFill boolean 新建记录时,是否自动填充时间
timeZone string 时区
includeTimeZone boolean 是否显示时区

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

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

timeZone 属性可用的时区名称请参考 List of Time Zones 网站,例:Asia/Shanghai

Attachment(附件)

暂无参数。

Member(成员)

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

{
  "type": "Member",
  "property": {
    "isMulti": true,
    "shouldSendMsg": true
  }
}
字段属性 数据类型 说明
isMulti boolean 是否可以选择多个成员
shouldSendMsg boolean 成员列中提及某成员时,是否向其发送站内消息通知

Checkbox(勾选)

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

{
  "type": "Checkbox",
  "property": {
    "icon": "white_check_mark"
  }
}
字段属性 数据类型 说明
icon string(enum) 请参考 emoji 枚举

Rating(评分)

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

{
  "type": "Rating",
  "property": {
    "icon": "⭐",
    "max": 5
  }
}
字段属性 数据类型 说明
icon string 评分值的图标表示,一般为 emoji 字符,比如 ⭐ 或 🎉
max number 评分最大值,取值为 1-10

URL(网址)

暂无参数。

Phone(电话)

暂无参数。

Email(邮箱)

暂无参数。

Workdoc(轻文档)

暂无参数。

OneWayLink(单向关联)

表 A 通过单向关联字段与 B 连接

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

{
  "type": "OneWayLink",
  "property": {
    "foreignDatasheetId": "dstgr2YN264s7CXKVs",
    "limitToViewId": "viwY4B8pmiMoi",
    "limitSingleRecord": true
  }
}
字段属性 数据类型 说明
foreignDatasheetId string 关联表 ID
limitToViewId string 指定关联表的一个视图,限制只能选取该视图下的记录
limitSingleRecord boolean 是否只能选取单条记录

TwoWayLink(双向关联)

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

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

{
  "type": "TwoWayLink",
  "property": {
    "foreignDatasheetId": "dstgr2YN264s7CXKVs",
    "brotherFieldId": "fldxxxxxxxx",
    "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
      }
    },
    "enableFilterSort": true,
    "sortInfo": {
      "rules": [
        {
          "fieldId": "fld7aautAK1h",
          "desc": false
        }
      ]
    },
    "filterInfo": {
      "conjunction": "and",
      "conditions": [
        {
          "fieldId": "fldL74kjFHak",
          "fieldType": "Number",
          "operator": "isGreater",
          "value": [13]
        }
      ]
    },
    "lookUpLimit": "ALL"
  }
}
字段属性 数据类型 说明
relatedLinkFieldId string 引用的当前表的关联字段 ID
targetFieldId string 关联表中查询的字段 ID
hasError boolean 当神奇引用的依赖的关联字段被删除或者转化类型时,可能无法正常获取引用值
entityField object 最终引用到的实体字段,不包含神奇引用类型的字段。存在错误时,实体字段可能不存在。
rollupFunction string 汇总函数
valueType string 返回值类型,取值包括 StringBooleanNumberDateTimeArray
format object 当返回值类型为 NumberDateTime 时,返回对数字或者日期格式化操作的结果
enableFilterSort boolean 是否开启筛选和排序
sortInfo object 排序设置
filterInfo object 筛选设置
lookUpLimit string 限制展示的记录数量
  • 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 是否显示时间
    timeZone string 时区
    includeTimeZone boolean 是否显示时区

    格式化为数字或百分比:

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

    格式化为货币:

    参数 数据类型 说明
    precision number 精度
    symbol string 货币符号
  • sortInfo 下包含的参数说明:

    参数 数据类型 说明
    rules array 排序规则的数组。目前只能指定一个排序规则(数组只能有一个元素)。

    rules 数组元素下包含的参数说明:

    参数 数据类型 说明
    fieldId string 用于排序的字段ID
    desc boolean 是否按降序排序
  • filterInfo 下包含的参数说明:

    参数 数据类型 说明
    conjunction string 筛选条件的组合方式:and 需要满足所有筛选条件;or 满足任意一个筛选条件即可。
    conditions array 筛选条件的数组

    conditions 下包含的参数说明:

    参数 数据类型 说明
    fieldId string 筛选字段的字段ID
    fieldType string 筛选字段的字段类型
    operator string 筛选条件的运算符,可选的取值见下表
    value array 筛选条件的基准值,例如筛选条件是「大于3」,则基准值为 3,value 的取值是 [3]

    operator 的取值说明:

    取值 说明
    is 筛选字段的字段值等于基准值
    isNot 筛选字段的字段值不等于基准值
    contains 筛选字段的字段值包含基准值
    doesNotContain 筛选字段的字段值不包含基准值
    isEmpty 筛选字段的字段值为空
    isNotEmpty 筛选字段的字段值不为空
    isGreater 筛选字段的字段值大于基准值
    isGreaterEqual 筛选字段的字段值大于或等于基准值
    isLess 筛选字段的字段值小于基准值
    isLessEqual 筛选字段的字段值小于或等于基准值
    isRepeat 筛选字段的字段值存在重复项
  • lookUpLimit 的取值说明:

    取值 说明
    ALL 显示所有引用的记录值
    FIRST 只显示引用的第一条记录值

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://s4.vika.cn/default/avatar004.jpg"
      }
    ]
  }
}
字段属性 数据类型 说明
options array 当前成员字段已经选过的成员的数组

options 数组中每个对象包含的参数:

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

LastModifiedBy(更新人)

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

{
  "type": "LastModifiedBy",
  "property": {
    "options": [
      {
        "id": "e9cbc839fd1b49be85b1f7b0977047e2",
        "name": "Coco",
        "avatar": "https://s4.vika.cn/default/avatar004.jpg"
      }
    ]
  }
}
字段属性 数据类型 说明
options array 当前字段存储过的用户的数组

options 数组中每个对象包含的参数:

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

Button(按钮)

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

{
  "id": "fldb6L4FznMbZ",
  "name": "Button",
  "type": "Button",
  "property": {
    "text": "Click to start",
    "style": {
      "type": "Background",
      "color": {
        "name": "deepPurple_5",
        "value": "#B0A4F5"
      }
    },
    "action": {
      "type": "openLink",
      "openLink": {
        "type": "Url",
        "expression": "https://vika.cn"
      }
    }
  },
  "editable": false
}
Field Properties Data Type Description
text String 按钮文案
style Object 按钮样式
action Object 按钮操作
  • style对象包含的参数:
Parameters Data Type Description
type String 按钮样式类型:带背景颜色按钮, 纯文字按钮。默认为:Background
color Object 按钮颜色
  • color对象包含的参数:
Parameters Data Type Description
name String 颜色名称,详细查看色板
value String 颜色名称对应的值,仅供查看,不支持使用此参数修改颜色。详细查看色板
  • action对象包含的参数:
Parameters Data Type Description
type String 按钮操作类型:跳转链接(OpenLink),触发自动化流程(TriggerAutomation),目前API仅支持写入OpenLink按钮列
openLink Object 点击跳转链接
  • openLink对象包含的参数:
Parameters Data Type Description
type String 跳转链接URL,支持: url(Url)、公式(Expression)
expression String 跳转链接

获取字段

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

一张维格表最多可以创建 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://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://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": { }
}

视图

视图的数据结构如下:

属性 说明
id string*
视图 ID
例: viwpdA8TUBp5r
name string*
视图名称
例:全部订单
type string(enum)*
视图类型:Grid(维格视图)、Gallery(相册视图)、Kanban(看板视图)、Gantt(甘特视图)、Calendar(日历视图)、Architecture(架构视图)
例: Grid

获取视图

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

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

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

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

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

path Parameters
datasheetId
required
string
Example: dst0Yj5aNeoHldqvf6

维格表 ID

Responses

Request samples

curl -X GET \
"https://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)

字段列表,为空则新增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://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
e.g. spcX9P2xUcKst
name string*
空间站名称
e.g. test
isAdmin boolean
当前发起API请求的用户是否此空间站的主管理员
e.g. true

获取空间站列表

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

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

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

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

Responses

Request samples

curl -X GET \
"https://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(维格表)、Mirror(镜像)、Folder(文件夹)、Form(收集表)、Dashboard(仪表盘)、Automation(自动化)
例:Folder
isFav boolean
星标状态。该参数指示当前节点是否固定在左侧边栏的“星标”部分中
例:true
permission number
API令牌是基于个人帐号生成的。用户可以基于API令牌检索符合其拥有指定权限的文件节点列表。
0: 对应操作界面的“可管理”权限。在“可编辑”的基础上,还可以增删文件和字段,拥有文件的所有操作权限。
1: 对应操作界面的“可以编辑”权限,在“只可更新”的基础上,还可以增删视图和记录,但不可增删字段。
2: 对应操作界面的“只可更新”,在“只可查看”的基础上,还可以新增和编辑记录,但不可删除记录。
3: 对应操作界面的“只可阅读”,只可查看文件的内容。
有关文件节点权限的更多详细信息,请参考:权限设置
例:0
children array of nodes
**仅调用获取文件节点详情接口,并且目标文件的类型为 Folder 时,才会返回 children 信息。children 下为文件夹下一层的文件列表
例:[{"id":"fodwrbgo8lDpbUjZzm","name":"采购管理","type":"Folder","icon":"🤠","isFav":true},{"id":"fodwrbgo8lDpbUjZzm","name":"采购管理","type":"Folder","icon":"🤠","isFav":true}]
parentId string
只有请求「获取文件节点列表」「搜索文件节点列表」时才返回。父节点 ID。此属性指定当前节点的父节点 ID。如果该节点没有父节点,则不返回此属性
例:fodwrbgo8lDpbUjZzm

获取文件节点列表

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

「获取文件节点列表」接口只支持返回工作目录下最外层的文件列表,如果你想返回工作目录下所有的文件节点列表,可以同时调用「获取文件节点详情」接口以达到目的;

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

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

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

path Parameters
spaceId
required
string
Example: spczdmQDfBAn5

空间站 ID

Responses

Request samples

curl -X GET \
"https://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 的请求示例,供你参考。

如果你需要更详细的操作指导,可阅读「API 指南」的搜索文件节点操作指南。

query Parameters
type
required
string
Enum: "Folder" "Datasheet" "Form" "Dashboard" "Mirror"
Example: type=Datasheet

节点类型,取值为 "Folder", "Datasheet", "Form", "Dashboard"或"Mirror"。枚举值区分大小写。

permissions
Array of numbers
Default: [0,1,2,3]
Items Enum: 0 1 2 3

API令牌是基于个人帐号生成的。用户可以基于API令牌检索符合其拥有指定权限的文件节点列表。
0: 对应操作界面的“可管理”权限。在“可编辑”的基础上,还可以增删文件和字段,拥有文件的所有操作权限。
1: 对应操作界面的“可以编辑”权限,在“只可更新”的基础上,还可以增删视图和记录,但不可增删字段。
2: 对应操作界面的“只可更新”,在“只可查看”的基础上,还可以新增和编辑记录,但不可删除记录。
3: 对应操作界面的“只可阅读”,只可查看文件的内容。
有关文件节点权限的更多详细信息,请参考:权限设置
例:0

query
string

当你想要从搜索结果中检索具有特定关键词的文件节点时,可以使用此参数。API会搜索所有文件节点名称以进行部分匹配,并返回与指定条件匹配的文件节点列表。

Responses

Request samples

curl -X GET \
"https://vika.cn/fusion/v2/spaces/{替换为你的 spaceId}/nodes?type=Datasheet" \
-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://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": {
    }
}

AI

目前维格表仅开放会话补全的接口,并且仅白名单用户可用,点此申请

会话补全

该接口用于与指定的 AI 机器人进行一次会话

如果你需要更详细的操作指导,可阅读「API 指南」的会话补全操作指南。

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

path Parameters
aiId
required
string
Example: ai_zxLeHGV3ac32YYC

AI ID

Request Body schema: application/json

请求体结构

model
required
string

使用模型的 ID,如 "gpt-3.5-turbo",查看目前可用的模型列表

required
Array of objects

包含迄今为止对话的消息列表。

Array of AiFunction (object)

一个函数列表,模型可以为这些函数自动生成 JSON 格式的输入数据

function_call
object

控制模型如何响应函数调用。"none"意味着模型不调用函数,而是直接对终端用户作出响应。"auto"意味着模型可以在响应终端用户和调用函数之间进行选择。通过{"name":"my_function"}指定一个特定的函数会强制模型调用那个函数。如果没有函数存在,默认是"none"。如果有函数存在,默认是 "auto"。

temperature
number [ 0 .. 2 ]

使用什么样的采样温度,在0到2之间。更高的值像0.8会使输出更随机,而更低的值像0.2会使输出更集中和确定。

top_p
number

一种替代基于温度采样的方法,称为核采样,模型只考虑概率质量排在前 top_p 的标记结果。所以0.1表示只考虑组成前10%概率质量的标记。

stream
boolean

如果设置了该选项,将像 ChatGPT 一样发送部分消息增量。标记将以纯数据的服务端发送事件的形式实时发送,并在数据流结束时发送 data:[DONE] 消息进行标记。

stop
string/array/null

最多 4 个序列,当生成到这些序列之一时,API将停止生成更多 token。

max_tokens
number

在会话补全时,可以生成的最大标记(词元)数量。

presence_penalty
number [ -2 .. 2 ]

一个在 -2.0 和 2.0 之间的数字。正值会根据新标记是否出现在目前为止的文本中对其进行惩罚,增加模型谈论新话题的可能性。

frequency_penalty
number [ -2 .. 2 ]

一个在 -2.0 和 2.0 之间的数字。正值会根据标记在目前为止文本中的现有频率对其进行惩罚,降低模型逐字重复同一句子的可能性。

user
string

代表您的最终用户的唯一标识符,可以帮助我们监控和检测滥用行为。

Responses

Request samples

Content type
application/json
{
  • "model": "gpt-3.5-turbo",
  • "messages": [
    ],
  • "functions": [
    ],
  • "function_call": {
    },
  • "temperature": 1,
  • "top_p": 1,
  • "stream": false,
  • "stop": null,
  • "max_tokens": 5,
  • "presence_penalty": 0,
  • "frequency_penalty": 0,
  • "user": "user123456"
}

Response samples

Content type
application/json
{
  • "id": "aitable_ai_CkZH2zQokhry31j_1693452659",
  • "conversation_id": "CS-0253eb8d-d6c6-4543-88d4-fcb555f52982",
  • "actions": null,
  • "object": "chat.completion",
  • "created": 1693452659,
  • "model": "gpt-3.5-turbo",
  • "choices": [
    ],
  • "usage": {
    }
}

成员

成员(Member)的数据结构如下:

属性 类型 说明 示例值
unitId string 成员的唯一 ID "T7fL3jV4KvX1cY2dGmS9sPqZzN6rWnB"
name string 成员的昵称 "张三"
avatar string 成员的头像资源地址 "https://s4.vika.cn/public/2023/05/16/d2d74a23dabb4700a91594fbc975fd06"
email string 成员的邮箱号 "test@vikadata.com"
mobile object 成员的手机号 {"number": "12345678901","areaCode": "+86"}
status integer 成员的状态,0 为未加入空间站,1 为已加入空间站 1
type string 成员的类型,包含 PrimaryAdmin(主管理员),SubAdmin(子管理员),Member(成员) "Member"
teams array of object 成员所属的小组列表 [{"unitId": "VS1SejiywaMWbiGMEHAohh62T9EPmmlh","name": "test","sequence": 1,"parentUnitId":"YN3YT97EPGL9ZA0loc9V2kNQnWb9ivKW"},...]
roles array of object 成员所关联的角色列表 [{"unitId": "sZ6gJ9L2HxP5XW1fRtNwE4zKqVcY7yM","name": "role A","sequence": 1},...]

获取成员

该接口用于获取指定成员。

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

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: kD8tPcZ3fYxSjV9qWvL5X2TmQbN1nR6

成员的 unitId

query Parameters
sensitiveData
string
Example: sensitiveData=true

是否获取成员的敏感数据(手机号、邮箱),如需获取则填入 "true"

Responses

Request samples

curl -X GET \
'https://vika.cn/fusion/v1/spaces/{spaceId}/members/{unitId}?sensitiveData=true' \
-H 'Authorization: Bearer {替换为你的 API Token}'

Response samples

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

更新成员

该接口用于更新空间站指定成员的信息。

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

请求体中包含成员要更新的属性及对应的值,只有显式指定的属性会更新数据,没有被指定的属性会保留旧值。

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: kD8tPcZ3fYxSjV9qWvL5X2TmQbN1nR6

成员的 unitId

query Parameters
sensitiveData
string
Example: sensitiveData=true

是否获取成员的敏感数据(手机号、邮箱),如需获取则填入 "true"

Request Body schema: application/json

请求体结构

name
string

成员昵称

teams
Array of strings

成员所属的小组列表

roles
Array of strings

成员关联的角色列表

Responses

Request samples

Content type
application/json
{
  • "name": "张三",
  • "teams": [
    ],
  • "roles": [
    ]
}

Response samples

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

删除成员

该接口用于删除空间站中指定的成员。

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: kD8tPcZ3fYxSjV9qWvL5X2TmQbN1nR6

需要删除的成员的 unitId

Responses

Request samples

curl -X DELETE \
'https://vika.cn/fusion/v1/spaces/{spaceId}/members/{unitId}' \
-H 'Authorization: Bearer {替换为你的 API Token}'

Response samples

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

小组

小组(Team)的数据结构如下:

属性 类型 说明 示例值
unitId string 小组的唯一 ID "C7dVpM3tBxL4jT6hRyK5WwQsZgX8fNv"
name string 小组的名称 "产品组"
sequence integer 小组在当前层级的排序,通讯录中按照此序号升序排序,同层级的小组序号可重复,若重复则根据小组的创建时间升序排序 1
parentUnitId string 小组所属父级小组的 unitId "nL2vU7tZwKfR4aGxQyJjXq6YbP5mS9c"
roles array of object 小组关联的角色列表 [{"unitId": "gP5zF7xW1mC2nQ4sXrKjV8bT6tL9yH","name": "role A","sequence": 1},..}]

获取小组的成员

该接口用于获取指定小组的成员。

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

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: X9vJ6R2qFzL8sK1mVxZcPwNtY3gT5yD

指定小组的 unitId

query Parameters
pageSize
number
Example: pageSize=100

每页返回多少条记录。默认每页返回 100 条记录。取值范围为 1~1000 的整数。

pageNum
number
Example: pageNum=1

指定分页的页码,与参数 pageSize 配合使用。例如 pageSize=1000&pageNum=2,返回 1001~2000 之间的记录。

sensitiveData
string
Example: sensitiveData=true

是否获取成员的敏感数据(手机号、邮箱),如需获取则填入 "true"

Responses

Request samples

curl -X GET \
"https://vika.cn/fusion/v1/spaces/{spaceId}/teams/{unitId}/members?sensitiveData=true" \
-H "Authorization: Bearer {替换为你的 API Token}"

Response samples

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

获取小组列表

该接口用于获取指定小组的下级小组列表。

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

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: X9vJ6R2qFzL8sK1mVxZcPwNtY3gT5yD

指定小组的 unitId

query Parameters
pageSize
number
Example: pageSize=100

每页返回多少条记录。默认每页返回 100 条记录。取值范围为 1~1000 的整数。

pageNum
number
Example: pageNum=1

指定分页的页码,与参数 pageSize 配合使用。例如 pageSize=1000&pageNum=2,返回 1001~2000 之间的记录。

Responses

Request samples

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

Response samples

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

创建小组

该接口用于在空间站里创建一个小组。

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

如果你需要更详细的操作指导,可阅读「API 指南」的创建小组操作指南。

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

Request Body schema: application/json

请求体结构

name
required
string

小组的名称

sequence
number

小组在当前层级的排序,通讯录中按照此序号升序排序,同层级的小组序号可重复,若重复则根据小组的创建时间升序排序

parentUnitId
string

小组所属父级小组的 unitId

roles
Array of strings

小组关联的角色列表

Responses

Request samples

Content type
application/json
{
  • "name": "Team A",
  • "sequence": 1,
  • "parentUnitId": "bD3fT4cL9wZ5mN8xSsK7qVvRjXhGpY",
  • "roles": [
    ]
}

Response samples

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

更新小组

该接口用于更新空间站指定小组的相关信息。

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

请求体中包含小组中要更新的属性及对应的值,只有显式指定的属性会更新数据,没有被指定的属性会保留旧值。

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: X9vJ6R2qFzL8sK1mVxZcPwNtY3gT5yD

指定小组的 unitId

Request Body schema: application/json

请求体结构

name
string

小组的名称

sequence
number

小组在当前层级的排序,通讯录中按照此序号升序排序,同层级的小组序号可重复,若重复则根据小组的创建时间升序排序

parentUnitId
string

小组所属父级小组的 unitId

roles
Array of strings

小组关联的角色列表

Responses

Request samples

Content type
application/json
{
  • "name": "Team A",
  • "sequence": 1,
  • "parentUnitId": "bD3fT4cL9wZ5mN8xSsK7qVvRjXhGpY",
  • "roles": [
    ]
}

Response samples

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

删除小组

该接口用于删除空间站中指定的小组。

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

query Parameters
unitId
required
string
Example: unitId=zJ6TuQvH2RtNfSx9eY7XKgD1oWcE5pV

需要删除的小组 unitId

Responses

Request samples

curl -X DELETE \
'https://vika.cn/fusion/v1/spaces/{spaceId}/teams/{unitId}' \
-H 'Authorization: Bearer {替换为你的 API Token}'

Response samples

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

角色

角色(Role)的数据结构如下:

属性 类型 说明 示例值
unitId string 角色的唯一 ID "sZ6gJ9L2HxP5XW1fRtNwE4zKqVcY7yM"
name string 角色的名称 "财务"
sequence integer 角色的排序,值从 2000 开始递增,如 “2001,2002,2003”。角色的排序序号可重复,若重复则根据角色的创建时间升序排序 2001

获取角色的成员和小组

该接口用于获取指定角色下的成员和小组。

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

如果你需要更详细的操作指导,可阅读「API 指南」的获取角色的成员和小组操作指南。

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: gP5zF7xW1mC2nQ4sXrKjV8bT6tL9yH

需要获取的角色的 unitId

query Parameters
sensitiveData
string
Example: sensitiveData=true

是否获取成员的敏感数据(手机号、邮箱),如需获取则填入 "true"

Responses

Request samples

curl -X GET \
"https://vika.cn/fusion/v1/spaces/{spaceId}/roles/{unitId}/units?sensitiveData=true" \
-H "Authorization: Bearer {替换为你的 API Token}"

Response samples

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

获取角色

该接口用于获取指定空间站中的所有角色。

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

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

query Parameters
pageSize
number
Example: pageSize=100

每页返回多少条记录。默认每页返回 100 条记录。取值范围为 1~1000 的整数。

pageNum
number
Example: pageNum=1

指定分页的页码,与参数 pageSize 配合使用。例如 pageSize=1000&pageNum=2,返回 1001~2000 之间的记录。

Responses

Request samples

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

Response samples

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

创建角色

该接口用于在空间站里创建一个角色。

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

如果你需要更详细的操作指导,可阅读「API 指南」的创建角色操作指南。

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

Request Body schema: application/json

请求体结构

name
required
string

角色的名称

sequence
number

角色的排序,值从 2000 开始递增,如 “2001,2002,2003”。角色的排序序号可重复,若重复则根据角色的创建时间升序排序

Responses

Request samples

Content type
application/json
{
  • "name": "财务",
  • "sequence": 2001
}

Response samples

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

更新角色

该接口用于更新空间站指定角色的信息。

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

请求体中包含角色中要更新的属性及对应的值,只有显式指定的属性会更新数据,没有被指定的属性会保留旧值。

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: gP5zF7xW1mC2nQ4sXrKjV8bT6tL9yH

需要更新的角色的 unitId

Request Body schema: application/json

请求体结构

name
string

角色的名称

sequence
number

角色的排序,值从 2000 开始递增,如 “2001,2002,2003”。角色的排序序号可重复,若重复则根据角色的创建时间升序排序

Responses

Request samples

Content type
application/json
{
  • "name": "财务",
  • "sequence": 2001
}

Response samples

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

删除角色

该接口用于删除空间站中指定的角色。

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

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

path Parameters
spaceId
required
string
Example: spcjXzqVrjaP3

空间站的 space Id

unitId
required
string
Example: gP5zF7xW1mC2nQ4sXrKjV8bT6tL9yH

需要删除的角色的 unitId

Responses

Request samples

curl -X DELETE \
'https://vika.cn/fusion/v1/spaces/{spaceId}/roles/{unitId}' \
-H 'Authorization: Bearer {替换为你的 API Token}'

Response samples

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