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 认证 Token以及结构请参照下图， 以下会进行详细说明

全局 API

调用这一类的 API 需要一个合法的 token, 叫做 Account token， 这个 token 要包含在 HTTP 请求的头部， 如：

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

该 token 需要使用用户的登陆用户名以及密码进行获取， 全局 API 由 DTable Web 组件提供， 可以进行 Workspace管理， 用户管理， Base管理( 非Base数据管理 )，群组以及成员管理等。根据用户认证的 角色不同， 提供了不同类型的 API， 包括：

获取 account token

用账号和密码获取认证 token， 该 token 长期有效

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

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

{"token": "24fd3c026886e3121b2ca630805ed425c272cb96"}

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

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

{"token":"265757b0a5aaf5d6b2e266d0c21791121ce6cdec"}

读写单个 base 的 API

读写单个 Base 的 API 由 dtable-server 和 dtable-db 组件提供。要调用其中的 API，你需要先获取 base 的access-token。一个 base 的 access-token 的有效期是 3 天。以下有两种方式获取 base 的 access -token， 两种方式都会返回相同的结果：

通过 API Token 获取 access-token

可以在网页 UI 里为这个 base 生成一个 API Token，该 token 长期有效，然后调用 dtable-server 提供的 API 可以获取操作该 base 的 access-token，使用 access-token 可以对 base 的相关 API 进行访问，生成 API Token 的菜单位置如下：

假设这里生成的一个 API Token 是 “8g971000df0d6fbntc59580766329a5b37adfh“， 调用以下 API 即可

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

通过 Account Token 获取 access-token

假设通过上述全局 API 的 account token 获取方式，获得 的account token为 “jwiefpvwd6fbntc59580766329a5b37adfh“， base的名称叫做“CommonSurvey“， 所在的工作区的 workspace的id 为255， 请求下列 API即可：

curl -H 'Accept: application/json; charset=utf-8; indent=4' -H 'Authorization: Bearer jwiefpvwd6fbntc59580766329a5b37adfh'https://cloud.seatable.cn/api/v2.1/workspace/255/dtable/CommonSurvey/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 了， 这一部分的 API 由 dtable_server / dtable-db 提供， 因此服务器地址可以参照使用上述返回的具体内容

API列表

Restful API

SeaTable Restful API：这是 restful 形式编写的 API 说明，采用英文书写， 不限于编程语言。我们在文档中提供了 一个 API 请求的详细说明， 包括但不限于请求方式， 请求体， 返回的数据结构等。

Python API

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

其他

上述 Restful API 文档是基于 国外的云服务编制而成， 此外还有一些 功能以及 API 是在中国国内使用， 而在国外用不到的， 此处列举出来：

需要注意的问题

上述 API 文档是基于 SeaTable 的 国外服务基础上编制而成， 其请求的域名 与 SeaTable 开发者/私有部署版类似即

开发者版或者私有部署版，以上的 “cloud.seatable.io“ 可以使用 你自己的服务器的域名来代替。

以下是 国内 SeaTable 的国内云服务， 请求的域名与上述稍有不同， 用户在参照 API 文档时测试国内版本的时候需要进行注意

国内云服务 (https://cloud.seatable.cn/ )

SeaTable 国内云服务请求域名如下：

curl --request GET \
     --url https://cloud.seatable.cn/api/v2.1/user-admin-dtables/ \
     --header 'accept: application/json' \
     --header 'authorization: Bearer foue8r4729393766tfhfkjhwseur93uuf23'


curl --request GET \
     --url https://dtable-server-03.seatable.cn/api/v1/dtables/base_uuid/rows/?table_name=Table1 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDU4MjM3NjcsImR0YWJsZV91dWlkIjoiN2Q5ZjJjMWQtZjE3MC00ZDg5LWJlNmQtNjZjMGM2MTM2N2RhIiwidXNlcm5hbWUiOiJhZWE5ZTgwN2JjZmQ0ZjM0ODFkNjAyOTRkZjc0ZjZlZUBhdXRoLmxvY2FsIiwiaWRfaW5fb3JnIjoiIiwidXNlcl9kZXBhcnRtZW50X2lkc19tYXAiOnsiY3VycmVudF91c2VyX2RlcGFydG1lbnRfaWRzIjpbXSwiY3VycmVudF91c2VyX2RlcGFydG1lbnRfYW5kX3N1Yl9pZHMiOltdfSwicGVybWlzc2lvbiI6InJ3In0.31qwCMWOmqdOXnm0MZJ5KK5DIGvBl4U6OaJUdLMA91g'


curl --request POST \
     --url https://dtable-db.seatable.cn/api/v1/query/base_uuid/ \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDU4MjM3NjcsImR0YWJsZV91dWlkIjoiN2Q5ZjJjMWQtZjE3MC00ZDg5LWJlNmQtNjZjMGM2MTM2N2RhIiwidXNlcm5hbWUiOiJhZWE5ZTgwN2JjZmQ0ZjM0ODFkNjAyOTRkZjc0ZjZlZUBhdXRoLmxvY2FsIiwiaWRfaW5fb3JnIjoiIiwidXNlcl9kZXBhcnRtZW50X2lkc19tYXAiOnsiY3VycmVudF91c2VyX2RlcGFydG1lbnRfaWRzIjpbXSwiY3VycmVudF91c2VyX2RlcGFydG1lbnRfYW5kX3N1Yl9pZHMiOltdfSwicGVybWlzc2lvbiI6InJ3In0.31qwCMWOmqdOXnm0MZJ5KK5DIGvBl4U6OaJUdLMA91g' \
     --header 'content-type: application/json' \
     --data '
{
  "convert_keys": true,
  "sql": "select * from Table1"
}
'


curl --request GET \
     --url https://cloud.seatable.cn/api-gateway/api/v2/dtables/:base_uuid/rows/?table_name=Table1 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDU4MjM3NjcsImR0YWJsZV91dWlkIjoiN2Q5ZjJjMWQtZjE3MC00ZDg5LWJlNmQtNjZjMGM2MTM2N2RhIiwidXNlcm5hbWUiOiJhZWE5ZTgwN2JjZmQ0ZjM0ODFkNjAyOTRkZjc0ZjZlZUBhdXRoLmxvY2FsIiwiaWRfaW5fb3JnIjoiIiwidXNlcl9kZXBhcnRtZW50X2lkc19tYXAiOnsiY3VycmVudF91c2VyX2RlcGFydG1lbnRfaWRzIjpbXSwiY3VycmVudF91c2VyX2RlcGFydG1lbnRfYW5kX3N1Yl9pZHMiOltdfSwicGVybWlzc2lvbiI6InJ3In0.31qwCMWOmqdOXnm0MZJ5KK5DIGvBl4U6OaJUdLMA91g'

Last modified by seatable, 2024-07-05

基本概念
API 基础
全局 API
获取 account token
读写单个 base 的 API
通过 API Token 获取 access-token
通过 Account Token 获取 access-token
结果说明
API列表
Restful API
Python API
其他
需要注意的问题