使用说明

CloudBase CMS 2.3.0 版本起，提供了通过 RESTful API 访问内容集合数据的能力。

自 2.12.0 版本起，新增 API 访问鉴权。

启用 RESTful API

默认情况下，API 访问为关闭状态，此时无法使用 RESTful API 功能。你需要在系统设置中启用 API 访问功能，并设置访问路径后，才可以通过完整的访问路径访问 RESTful API

访问权限

CMS RESTful 的访问权限控制主要由两部分组成：

1. API 鉴权：默认不开启，开启后需要 API Token 才能访问内容
2. 内容访问权限：默认通过 RESTful API 不能访问任何内容，仅已设置权限的内容才可以访问

开启 API 鉴权后，任需要设置内容访问权限，才能通过 RESTful API 访问内容。

内容访问权限

默认情况下，RESTful API 无法访问任何数据，你需要在项目设置中的 API 访问 Tab 设置允许通过 RESTful API 访问/修改的内容：

• 允许访问：能通过 RESTful API 读取内容

• 允许修改：能通过 RESTful API 创建、更新内容

• 允许删除：能通过 RESTful API 删除内容

API 访问鉴权

自 2.12.0 版本起，你可以为 RESTful API 开启访问鉴权，只有通过鉴权的请求才能访问 CMS 的内容。

1. 开启访问鉴权

2. 创建 API Token，勾选 API Token 的权限

   • 允许访问：能通过 RESTful API 读取内容
   • 允许修改：能通过 RESTful API 创建、更新内容
   • 允许删除：能通过 RESTful API 删除内容

API 请求

请求路径

CloudBase CMS 的 RESTful API 请求路径由三部分组成：部署路径 + API 版本路径 + 服务路径。如

CMS 服务部署路径（下方的域名为示例，真实域名请查看您的 HTTP 访问服务默认域名）

https://xxxx.tcloudbase.com/api/

API 版本路径

/v1.0

服务路径，collectionName 为数据库集合名

/{collectionName}

则获取数据库名为 goods 的文档列表的请求路径为

GET https://xxx.tcloudbase.com/api/v1.0/goods

注意事项

1. 所有 POST 请求的 body 均应为 application/json 类型，请勿使用其他的类型

2. 查询数据时，默认最多一次返回 100 条数据

3. 请求时传入的参数会覆盖默认的行为表现，如指定了返回结果要携带某个字段，但是在模型定义中此字段在 API 返回值中为隐藏的，遵循以上原则，则返回数据时，此字段会存在

4. CMS 中默认会将上传的图片、文件存储在云存储中，并在数据库中存储 cloudId 形式的访问链接，使用 RESTful API 获取数据时，返回结果中的 cloudId 会被转换成 HTTP 链接。自动转换仅针对直接记录的 cloudId，关联文档中的 cloudId 不会处理。

5. 使用 RESTful API 获取数据时，返回结果中的关联字段会被转换为完整的关联文档的值，如当一个商品内容模型中关联了标签内容模型（tag），数据库底层存储如下：

{
  "_createTime": 1603183501849,
  "_id": "112557505f8ea38e001e1fc210bd51ed",
  "_updateTime": 1604541130908,
  "name": "苹果",
  "price": 6299,
  "stock": 100000,
  "tags": [
    "b8df3bd65f681d43002b894d0bdce7ac"
  ]
}

则返回的结果为：

{
  "_createTime": 1603183501849,
  "_id": "112557505f8ea38e001e1fc210bd51ed",
  "_updateTime": 1604541130908,
  "name": "苹果",
  "price": 6299,
  "stock": 100000,
  "tags": [
    {
      "_id": "b8df3bd65f681d43002b894d0bdce7ac",
      "_createTime": 1603183501849,
      "_updateTime": 1604541130908,
      "name": "水果",
      "count": 10
    }
  ]
}

公共参数

查询操作时，可以在 URL 中添加以下的 Query 参数

字段	类型	必填	说明
limit	String	否	查询返回的文档数量，最大值 1000
skip	String	否	查询偏移的文档数量
fields	String	否	JSON 对象字符串，例：{ key1: 1, key2: 0 }，表示取 key1 字段，丢弃 key2 字段
sort	String	否	JSON 对象字符串，例：{ key1: 1, key2: -1 }，表示按 key1 升序，key2 降序 排序

如：

GET /{collectionName}/?limit=10&skip=0&fields={"name":1}&sort={"name":1}

请求鉴权

当使用 API Token 调用 RESTful API 时，需要在 HTTP 请求 Header 中添加下面的配置

Authorization: Bearer API_TOKEN

API_Token 为在系统设置中生成的 Token，Bearer 为固有字段，两者通过空格连接。

设置迁移

自 2.12.0 版本起，项目中的 API 访问设置已迁移到系统设置中统一管理，你可以请前往系统设置进行 API 访问配置，并关闭项目中的 API 访问开关。

警告

在关闭项目中的 API 访问开关前，请确保已经更换了你的应用中的请求接口到新的接口，关闭 API 访问后，会删除绑定的 API 访问路径，旧的路径将无法继续访问。