⚠️ 请参考迁移指南 从 0.1.x 升级至 1.x 版本，旧版本我们将不再维护!

Vika Python SDK 是对维格表 Fusion API 的官方封装，提供类似 Django ORM 风格的 API。

用户交流 QQ 群：683795224

快速开始

环境要求

python3.6 +

安装

pip install --upgrade vika

获取 API TOKEN

访问维格表的工作台，点击左下角的个人头像，进入「用户中心 > 开发者配置」。点击生成 Token(首次使用需要绑定邮箱)。

使用

基础用法

from vika import Vika

vika = Vika("your api_token")

dst = vika.datasheet("dstt3KGCKtp11fgK0t")
# 传入表格URL 会自动解析表格 id，忽略视图 id。
# dst = vika.datasheet("https://vika.cn/space/spcxcvEBLXf7X/workbench/dstt3KGCKtp11fgK0t/viwmKtRiYcPfk")

# 创建记录
record = dst.records.create({"title": "new record from Python SDK"})
print(record.title)
# print(record.标题)

# 批量创建记录
records = dst.records.bulk_create([
    {"title": "new record from Python SDK"},
    {"title": "new record from Python SDK2"}
])

# 更新单个字段值
record.title = "new title"
print(record.title)
# "new title"

# 更新多个字段值
record.update({
    "title": "new title",
    "other_field": "new value",
})

# 批量更新多条记录
records = dst.records.bulk_update([
    {"recordId": "recxxxxx1", "fields":{"title": "new record.title from Python SDK"}},
    {"recordId": "recxxxxx2", "fields":{"title": "new record.title from Python SDK2"}},
])

# 附件字段更新
my_file = dst.upload_file( < 本地或网络文件路径 >)
record.files = [my_file]

# 过滤记录
songs = dst_songs.records.filter(artist="faye wong")
for song in songs:
    print(song.title)

# 批量更新一批记录
dst_tasks.records.filter(title=None).update(status="Pending")

# 获取单条记录
book = dst_book.records.get(ISBN="9787506341271")
print(book.title)

# 将 record 对象转化为 json
record.json()

# 删除符合过滤条件的一批记录
dst.records.filter(title=None).delete()

# 获取字段
for field in vika.datasheet("dstId").fields.all():
  print(field.name)

# 获取指定视图的字段，隐藏的字段不会返回
for field in vika.datasheet("dstId").fields.all(viewId="viewId"):
  print(field.name)

# 获取视图
for view in vika.datasheet("dstId").views.all():
  print(view.name)

字段映射

对于中文用户，表格的字段名通常是中文，虽然 Python 支持中文变量名，但是依然会出现中文字段名不符合变量规范的情况。因此你不得不回退到使用 fieldId 作为 key 的情况，致使代码可读性变差。

为了改善这种情况，Python SDK 提供了字段映射的功能。

Bug 标题!	Bug 状态
登陆后页面崩溃	待修复

dst = vika.datasheet("dstt3KGCKtp11fgK0t",field_key_map={
  "title": "Bug 标题!",
  "state": "Bug状态",
})

record = dst.records.get()
print(record.title)
# "登陆后页面崩溃"
print(record.state)
# "待修复"
record.state="已修复"

保留使用 field id 作 key 的用法

bug = vika.datasheet("dstn2lEFltyGHe2j86", field_key="id")
row = bug.records.get(flddpSLHEzDPQ="登陆后页面崩溃")
row.flddpSLHEzDPQ = "登陆后页面崩溃"
row.update({
    "flddpSLHEzDPQ": "登陆后页面崩溃",
    "fldwvNDf9teD2": "已修复"
})

指定 field_key="id" 时，再指定 field_key_map 对应的键值应该是 fieldId

bug = vika.datasheet("dstn2lEFltyGHe2j86", field_key="id", field_key_map={
    "title": "flddpSLHEzDPQ",
    "state": "fldwvNDf9teD2",
})

API

维格表

records 方法

dst.records 管理表格中的记录。

方法	参数	返回类型	说明	例子
create	dict	Record	创建单条记录	dst.records.create({"title":"new title"})
bulk_create	dict[]	Record[]	批量创建多条记录	dst.records.bulk_create([{"title":"new record1"},{"title":"new record2"}])
bulk_update	dict[]	Record[]	批量更新多条记录	dst.records.bulk_update([{"recordId": "recxxxxx1", "fields":{"title": "new record.title from Python SDK"}}])
all	**kwargs	QuerySet	返回记录集合,可传参定制返回内容	dst.records.all()
get	**kwargs	Record	单条记录	dst.records.get(title="new title")
get_or_create	(defaults,**kwargs)	Record,bool	通过 kwargs 查询对应的记录，如果不存在则结合 defaults 创建一条新记录，返回的 bool 表示是否是新建的记录	dst.records.get_or_create(title="new title",defaults={"status":"pending"})
update_or_create	(defaults,**kwargs)	Record,bool	通过 kwargs 查询对应的记录，并以 defaults 更新记录。不存在则创建（与 get_or_create 一致）	dst.records.update_or_create(title="new title",defaults={"status":"done"})
filter	**kwargs	QuerySet	过滤一批记录	dst.records.filter(title="new title")

QuerySet

返回 QuerySet 的方法可以进行链式调用。例如 qs = dst.records.all() 返回了一批查询出来的数据集。

方法	参数	返回类型	说明	例子
filter	**dict	QuerySet	过滤出一批记录	qs.filter(title="new title")
all	/	QuerySet	返回当前记录集合的拷贝	qs.filter(title="new title").all()
get	**dict	Record	单条记录	qs.get(title="new title")
count	/	int	记录总数	qs.filter(title="new title").count()
last	/	Record	最后一条记录	qs.filter(title="new title").last()
first	/	Record	第一条记录	qs.filter(title="new title").first()
update	**dict	Record	更新成功的记录数	qs.filter(title="new title").update(title="new title")
delete	/	bool	是否删除成功	qs.filter(title="new title").delete()

Record

查询出来的 QuerySet 是一个 Record 的集合。单个 Record 可以通过 record.字段名 的方式获取指定字段的值。

请尽量避免字段名和 Record 保留的方法属性同名，表格中的同名字段会被遮蔽。如果确实存在，请使用字段映射配置

方法/属性	参数	返回类型	说明	例子
json	/	dict	返回当前记录的所有字段值	record.json()
_id	/	str	_id 是保留属性，返回当前记录的 recordId	record._id

字段值

维格列字段值与 Python 数据结构的映射关系。 维格表中单元格为空的数据始终是 null，API 返回的记录中，不会包含值为 null 的字段。

维格列类型	数据类型
单行文本	str
多行文本	str
单选	str
多选	str[]
网址	str
电话	str
邮箱	str
数字	number
货币	number
百分比	number
自增数字	number
日期	number
创建时间	number
修改时间	number
附件	attachment object[]
成员	unit object[]
勾选	bool
评分	int
创建人	unit object
修改人	unit object
神奇关联	str[]
神奇引用	any[]
智能公式	str / bool

all 参数

all 方法会自动处理分页加载全部资源

传入分页相关参数（pageNum、pageSize）时，SDK 不会再自动加载全部记录，只返回指定页数据。

尽量避免在不加参数的情况下使用 dst.records.all 方法，获取全部数据。 API 每次请求最多获取 1000 条数据，如果你的数据量过大，接近 50000 的限制。在不加任何参数的情况下，调用 all 会串行请求 50 次 API。 不仅非常慢，而且消耗 API 请求额度。

返回指定分页的记录

dst.records.all(pageNum=3)

搭配视图使用

指定视图 id 返回和视图中相同的数据。

dst.records.all(viewId="viwxxxxxx")

使用公式筛选数据

dst.records.all(filterByFormula='{title}="hello"')

参数	类型	说明	例子
viewId	str	视图 ID。请求会返回视图中经过视图中筛选/排序后的结果
pageNum	int	默认 1
pageSize	int	默认 100 ， 最大 1000
sort	dict[]	指定排序的字段，会覆盖视图排序条件	[{ field: 'field1', order: 'asc' }]
recordIds	str[]	返回指定 recordId 的记录集	['recordId1', 'recordId2']
fields	str[]	只有指定字段会返回
filterByFormula	str	使用公式作为筛选条件，返回匹配的记录
maxRecords	int	限制返回记录数，默认 5000
cellFormat	'json' or 'string'	默认为 'json'，指定为 'string' 时所有值都将被自动转换为 string 格式。
fieldKey	'name' or 'id'	指定 field 查询和返回的 key。默认使用列名 'name'。

参见：公式使用方式

空间站

文件目录

开发测试

复制测试模板到自己的空间站，每次测试时，保证表中只有一条 title = "无人生还" 的记录

• 正式环境测试模板
• 内部环境测试模板

cp .env.example .env

配置测试所需的环境变量

# 安装依赖
pipenv install --pre
pipenv shell
python -m unittest test

更新日志

参见: releases

相关项目

• JavaScript SDK
• Golang SDK
• Java SDK

FAQ

可以拿到表格的字段类型（meta）信息吗？

目前不可以，后续 REST API 升级会暴露表格 meta 信息

可以通过 fields/views 接口获取

可以自动创建单多选选项吗？

record.tags = ["目前 tags 字段中不存在的选项"]

目前不可以，你只能赋值已经存在的选项。后续会支持 :D

现在已经支持，如果写入不存在的单多选字段，自动创建该选项

单个表格最大支持多少条记录？

目前单表最大支持 5w 条记录

每次请求可以处理更多的记录吗？

目前是 10 条。后续我们会根据实际情况，调整该限制的大小。

每次请求可以获取更多的记录吗?

目前最大值是 1000 条。后续我们会根据实际情况，调整该限制的大小。