bluerangala/vika.py

维格表(vika.cn)官方JavaScript SDK, 让你轻松集成维格表的 可视化API数据库能力。Vika is a API-based SaaS database platform for users and developers，here is it's Python SDK for integration.

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

快速开始

环境要求

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",
})

# 附件字段更新
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)

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

字段映射

对于中文用户，表格的字段名通常是中文，虽然 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.update(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 方法

方法	参数	返回类型	说明	例子
create	dict	Record	创建单条记录	dst.records.create({"title":"new title"})
bulk_create	dict[]	Record[]	批量创建多条记录	dst.records.bulk_create([{"title":"new record1"},{"title":"new record2"}])
all	**dict	QuerySet	返回记录集合,可传参定制返回内容	dst.records.all()
count	/	int	记录总数	dst.records.count()
get	**dict	Record	单条记录	dst.records.get(title="new title")
filter	**dict	QuerySet	过滤一批记录	dst.records.filter(title="new title")

QuerySet

返回 QuerySet 的方法可以进行链式调用

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

all 参数

当首次调用 all 不传入任何参数时，默认加载第一个视图的记录，后续的 filter、get 均在本地缓存数据中进行，all 方法仅在首次调用时，从服务端获取数据。

当调用 all 时，显式地传入参数，则利用服务端计算返回部分数据集。

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

参见：公式使用方式

开发测试

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

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

cp .env.example .env

配置测试所需的环境变量

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

更新日志

参见: releases

相关项目

• JavaScript SDK
• Golang SDK
• PHP SDK

FAQ

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

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

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

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

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

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

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

TODO

• 优化数据集较大时的网络请求
• 网络请求封装 & 错误处理
• filter 操作符