Vika.py

⚠️ 请参考迁移指南 从 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[]