SeaTable Web API - seatable-user-manual

基本概念

如下图所示，SeaTable 中的一个表格被定义为一个 Base 。

一个 Base 中可以包含多个子表（Table），每个子表由多个列（Column）和行（Row）组成。

从使用方式来看，SeaTable 中的 Base 类似于一个数据库（Database），因此，你可以将 Base 简单理解为 Database 的一种更直观的表达方式。

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

dtable-web: 主网站，显示和管理 base 的列表。
dtable-server: 加载一个 base 对应的文件到内存，并提供协同功能。
dtable-db: 提供数据归档功能，并提供 SQL 查询结果来查询全量数据(包括归档和未归档的数据)。
api-gateway: 提供针对 base 数据访问和写入的 API 服务 (包括归档和未归档的数据)。
seaf-server: 保存附件 (文件和图片)。

API 基础

SeaTable 中有两类 API

一类是全局 API, 包括管理账号、管理 base 列表的 API，由 dtable-web 组件提供。
一类是读写特定数据库 (base) 的 API，由 api-gateway 组件提供。

两类 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，包括：

普通用户 API
团队管理员 API
系统管理员 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 由 api-gateway 组件提供。要调用其中的 API，你需要先获取 base 的access-token。一个 base 的 access-token 的有效期是 3 天。以下有两种方式获取 base 的 access -token，两种方式都会返回相同的结果：

通过 API Token 获取 access-token

可以在网页 UI 里为这个 base 生成一个 API Token，该 token 长期有效，然后调用 api-gateway 提供的 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",
                
            
                
                                ...
                
            
                
                        }

用以上的信息你就能调用 api-gateway 提供的 API 了，这一部分的 API 由 api-gateway 提供，地址为 https://cloud.seatable.cn/api-gateway/

API列表

Restful API

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

Python API

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

需要注意的问题

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

dtable-web: API 请求域名 https://cloud.seatable.io ，地址是域名 + “/api/v2.1/....“
api-gateway : API 请求域名 https://cloud.seatable.io /api-gateway ，地址是域名 + “/api/v2.1/....“

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

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

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

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

dtable-web: https://cloud.seatable.cn/ , 请求方式域名 + “/api/v2.1/.....“ 的方式，如以下 API 查看用户管理的 base 的信息：

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

api-gateway: 请求域名是 https://cloud.seatable.cn/api-gateway ，请求方式是域名 + “/api/v2/...”的方式。如下述列出行的 API

            
                
                
                        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'