跳到主要内容

使用说明

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 参数

字段类型必填说明
limitString查询返回的文档数量,最大值 1000
skipString查询偏移的文档数量
fieldsStringJSON 对象字符串,例:{ key1: 1, key2: 0 },表示取 key1 字段,丢弃 key2 字段
sortStringJSON 对象字符串,例:{ 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 访问路径,旧的路径将无法继续访问。