SeaTable Web API

基本概念

SeaTable 中的一个表格叫做 base。一个 base 包括多个子表 (table)。一个 table 包括多个列 (column) 和行 (row)。SeaTable 中一个表格用起来就像是一个 database，这里 base 可以看成是 database 的简写。

SeaTable 服务器包含以下的组件:

dtable 是 SeaTable 项目的早期名称, 另外早期一个 base 也叫做一个 dtable。

API 基础

SeaTable 中有两类 API

两类 API 由不同的组件提供，需要使用不同的认证 token。如果你只需要操作单个 base, 我们建议只使用第二类 API，这样不需要使用用户名和密码，更加安全。

一、全局 API (管理账号、管理 base 列表)

调用这一类的 API 需要一个合法的 token, 这个 token 要包含在 HTTP 请求的头部:

curl -H 'Authorization: Token 24fd3c026886e3121b2ca630805ed425c272cb96' https://
cloud.seatable.cn/api2/auth/ping/

这个 token 可以通过用户名和密码来获取, 具体见下方章节 全局 API 。

对每个 API, 我们会提供 curl 命令调用的例子。

二、读写单个 base 的 API

如果你只需要操作一个 base，你可以在网页 UI 里为这个 base 生成一个 API Token，然后调用 dtable-server 提供的 API。具体见下方章节 读写单个 base 的 API .

生成 API Token 的菜单位置如下：

说明

具体每个 API 我们都只提供英文版的描述。因为英文版的描述也比较简单易懂，我们就不维护中英文两个版本了 :)

注意: 具体的 API 中我们给的例子都是用 cloud.seatable.io 为域名，你需要改成 cloud.seatable.cn，以便调用我们中国版的服务。

cloud.seatable.io 是国际版本。

常用状态码

全局 API

全局 API 由 DTable Web 组件提供，先用账号密码来获取 API Token, 然后再调用特定的 API。

获取 API token

用账号和密码获取认证 token

curl -d "username=xxxxxxxxxxxx@auth.local&password=123456" https://cloud.seatable.cn/api2/auth-token/

{"token": "24fd3c026886e3121b2ca630805ed425c272cb96"}

注: username 可以是系统给用户分配的唯一随机 ID，可以在管理后台查到，也可以用绑定的邮箱。

如果你的用户名中包含特殊的字符，你需要用 --data-urlencode 选项.

curl --data-urlencode username=xxxxxxxxxxxx@auth.local -d password=123456 https://cloud.seatable.io/api2/auth-token/

{"token":"265757b0a5aaf5d6b2e266d0c21791121ce6cdec"}

如果你开启了两步验证，那么你需要把两步验证的 token 放在头部中: 

curl -d "sername=xxxxxxxxxxxx@auth.local&password=123456" -H 'X-SEAFILE-OTP: <token>' https://cloud.seatable.cn/api2/auth-token/

普通用户 API

见 DTable Web APIs

系统管理员 API

见 DTable Web Admin APIs

机构管理员 API

如果你当前的账号是一个机构管理员账号，你可以调用机构管理员 API 来进行机构成员管理、群组管理等。

见 DTable Web Org Admin APIs

读写单个 Base 的 API

读写单个 Base 的 API 由 dtable-server 和 dtable-db 组件提供。要调用其中的 API，你需要先获取 base access token。一个 base access token 的有效期是 3 天。

有两个获取 base access token 的方式。一个是使用个人的 API Token 来调用 API api/v2.1/workspace/<workspace_id>/dtable/<name>/access-token/ 来获取。

图示如下:

     调用 api2/auth-token          调用 dtable/<name>/access-token 
账号密码 ------------------> 取得 API Token -----------------> 取得 base access token

另一个是使用 UI 界面来获取一个 base 的 API Token，然后来调用以下 API 来获取 base access token:

curl -H 'Accept: application/json; charset=utf-8; indent=4' -H 'Authorization: Token 8g971000df0d6fbntc59580766329a5b37adfh' "https://cloud.seatable.cn/api/v2.1/dtable/app-access-token/"

图示如下:

                                调用 dtable/app-access-token
界面菜单 -----> 取得 base API Token -------------------> 取得 base access token

两种方式最后都会返回以下的结果:

{    
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NjkyMjYxNzEsImR0YWJsZV91dWlkIjoiYjFjYWViNjFjZThmNDhiOWFlY2ZkNDZkNDI5OGM2MmQiLCJ1c2VybmFtZSI6IjEyM0BxcS5jb20iLCJwZXJtaXNzaW9uIjoiciIsImFwcF9uYW1lIjoicnR5dSJ9.pUn_HtrNwISji0nOe0_-0b5JyXN0yEIwzhdIaju-8VE",    
    "dtable_uuid": "b1caeb61-ce8f-48b9-aecf-d46d4298c62d",
    "dtable_server": 'https://dtable-server.seatable.cn/',
    "dtable-db": 'https://dtable-db.seatable.cn/'
    "dtable_socket: 'https://cloud.seatable.cn/',
    ...
}

用以上的信息，你就能调用 dtable-server 和 dtable-db 提供的 API 了:

注意，云服务的 dtable server 的地址为 https\://dtable-server.seatable.cn

开发者版的 dtable server 地址一般为 https\://你服务器域名/dtable-server/

Python 库

我们已经封装好了 Python 库来方便你调用上述的 API。而且 Python 脚本还可以直接上传到 SeaTable 服务器上运行，不需要你单独的找一台机器来部署。

Last modified by seatable, 2022-04-29

基本概念
API 基础
一、全局 API (管理账号、管理 base 列表)
二、读写单个 base 的 API
说明
常用状态码
全局 API
获取 API token
普通用户 API
系统管理员 API
机构管理员 API
读写单个 Base 的 API
Python 库