SeaTable 中的一个表格叫做 base。一个 base 包括多个子表 (table)。一个 table 包括多个列 (column) 和行 (row)。SeaTable 中一个表格用起来就像是一个 database,这里 base 可以看成是 database 的简写。
SeaTable 服务器包含以下的组件:
dtable 是 SeaTable 项目的早期名称, 另外早期一个 base 也叫做一个 dtable。
SeaTable 中有两类 API
两类 API 由不同的组件提供,需要使用不同的认证 token。如果你只需要操作单个 base, 我们建议只使用第二类 API,这样不需要使用用户名和密码,更加安全。
调用这一类的 API 需要一个合法的 token, 这个 token 要包含在 HTTP 请求的头部:
curl -H 'Authorization: Token 24fd3c026886e3121b2ca630805ed425c272cb96' https://
cloud.seatable.cn/api2/auth/ping/
这个 token 可以通过用户名和密码来获取, 具体见下方章节 全局 API
。
对每个 API, 我们会提供 curl
命令调用的例子。
如果你只需要操作一个 base,你可以在网页 UI 里为这个 base 生成一个 API Token,然后调用 dtable-server 提供的 API。具体见下方章节 读写单个 base 的 API
.
生成 API Token 的菜单位置如下:
具体每个 API 我们都只提供英文版的描述。因为英文版的描述也比较简单易懂,我们就不维护中英文两个版本了 :)
注意: 具体的 API 中我们给的例子都是用 cloud.seatable.io 为域名,你需要改成 cloud.seatable.cn,以便调用我们中国版的服务。
cloud.seatable.io 是国际版本。
全局 API 由 DTable Web 组件提供,先用账号密码来获取 API Token, 然后再调用特定的 API。
用账号和密码获取认证 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 来进行机构成员管理、群组管理等。
读写单个 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 库来方便你调用上述的 API。而且 Python 脚本还可以直接上传到 SeaTable 服务器上运行,不需要你单独的找一台机器来部署。
Last modified by seatable, 2022-04-29