vika.py

KO | EN

gitlite — search

#react #llm #golang #android #docker #macos #nodejs #windows #awesome #awesome-list #vue #mcp #openai #open-source

(★ 84)

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

vika.py Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> ⚠️ 请参考[迁移指南](https://github.com/vikadata/vika.py/blob/master/docs/upgrade_to_v1.md) 从 0.1.x 升级至 1.x 版本，旧版本我们将不再维护!

![vika.py](https://socialify.git.ci/vikadata/vika.py/image?description=1&descriptionEditable=Vika%20is%20a%20API-based%20SaaS%20database%20platform%20for%20users%20and%20developers%20here%27s%20Python%20SDK%20for%20integration.&font=Inter&forks=1&issues=1&language=1&logo=https%3A%2F%2Fs1.vika.cn%2Fspace%2F2020%2F09%2F04%2F9fcd0d98c2c74274840fcde3341d5164&owner=1&pattern=Circuit%20Board&pulls=1&stargazers=1&theme=Light)

[Vika](https://vika.cn) Python SDK 是对维格表 Fusion API 的官方封装，提供类似 Django ORM 风格的 API。

用户交流 QQ 群：683795224

## 快速开始

### 环境要求

python3.6 +

### 安装

```shell
pip install --upgrade vika
```

### 获取 API TOKEN

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

### 使用

基础用法

```python
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 状态 |
| -------------- | -------- |
| 登陆后页面崩溃 | 待修复   |

```python
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 的用法

```python
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`

```python
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 请求额度。

_返回指定分页的记录_

```python
dst.records.all(pageNum=3)
```

_搭配视图使用_

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

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

_使用公式筛选数据_

```python
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'。                    |                                       |

参见：[公式使用方式](https://vika.cn/help/tutorial-getting-started-with-formulas/)

### 空间站

### 文件目录

## 开发测试

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

- [正式环境测试模板](https://vika.cn/share/shrTZC8odwrWl95Gil2Dm)
- [内部环境测试模板](https://integration.vika.ltd/share/shr2BYKJ5QysFK9YoAws1)

```shell
cp .env.example .env
```

配置测试所需的环境变量

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

## 更新日志

参见: [releases](https://github.com/vikadata/vika.py/releases)

## 相关项目

- [JavaScript SDK](https://github.com/vikadata/vika.js)
- [Golang SDK](https://github.com/vikadata/vika.go)
- [Java SDK](https://github.com/vikadata/vika.java)

## FAQ

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

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

可以通过 fields/views 接口获取

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

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

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

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

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

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

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

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

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

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

vika.py

vika.py Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

vika.py

vika.py Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README