跳到主要内容

云数据库API

清林云 BaaS 云数据库 OneDB 作为底层承载所有环境的应用数据，拥有理论上无限的数据存储能力和极快的数据读写速度，保障整个清林云 BaaS 系统的数据稳定和安全。

本章节详细说明清林云 BaaS 系统的云数据库 OneDB API 格式，类似于应用 API 格式TypeAPI，有部分区别。

云数据库 OneDB API 主要用于集成原有业务和原有数据上云。

基本结构#

API 的基本 HTTP 结构如下：

API 示例#

以浏览器的 fetch 请求为例：

fetch("https://环境地域.baasapi.com/cdb", {  "headers": {    "content-type": "application/json",    "envid": "你的环境ID",    "keyid": "你的环境密匙ID",    "Authorization": "（必选）由环境密匙密码构建的访问token"  },  "method": "POST",  "body": JSON.stringify({    appId: "user", // 必填    tableId: "User", // 必填    action: "get", // 必填    ids: {},    columns: {},    getColumns: [],    engineIndex: '',    orderType: 'desc',    endIds: {},    rowsLimit: 100,    filter: {},    condition: {},    updateType: '',    skip: 0,    getTotalCount: false,    querys: [],    sorters: [],    nextToken: '',  })}).then(res=>res.json()).then(data=>console.log(data)).catch(e=>console.log(e))

在下文中我们详细解释每一个字段的作用和场景。

请求地址 url#

https://[环境地域].baasapi.com/cdb

其中[环境地域] 为你使用环境的地域代码，例如：https://cn-east-1.baasapi.com/cdb。

地域代码可在控制台概览页面的环境上方看到。

以下为所有地域代码：

  • 中国东部：cn-east-1
  • 中国北部：cn-north-1
  • 中国南部：cn-south-1
  • 中国西部：cn-west-1
  • 中国香港：cn-hk-1
  • 美国西部：us-west-1
  • 美国东部：us-east-1
  • 英国：uk-1
  • 新加坡：sg-1
  • 澳大利亚：au-1
  • 印度：in-1

另外专有云和私有云地域代码根据客户定制。

请求方法 method#

统一为POST。

请求头 headers#

{  "headers": {    "Content-Type": "application/json",    "envid": "你的环境ID",    "keyid": "你的环境密匙Id",    "Authorization": "Bearer 云数据库jwtToken"  }}

请求内容类型统一为 application/json。

携带你的环境 ID 和密匙 ID。

注意此处Authorization，需要使用上面环境密匙的密码去签名一个 jwtToken，设置签名的对象为：{identity:"cdb"}，即身份为 cdb。最好加上一个过期时间，以防 token 不慎泄露造成影响。

JavaScript 示例：

const token =  'Bearer ' +  jwt.sign(    {      identity: 'cdb',    },    '环境密匙密码',    { expiresIn: '1h' },  );

另外，需要前往应用市场 AppHub，安装云数据库应用(应用 ID：cdb)，然后进入该环境的密匙管理界面，设置该密匙-分应用权限-选择云数据库应用，开通该密匙的应用权限后才可以访问云数据库 API。

示例："Authorization": "Bearer eyJhbGVCJ9.eyJMzEwMjF9.mXM2b6yg"（此处为删减 token，实际 token 要更长一些）

之所以流程稍微复杂，是因为访问云数据库的 token 权限比较高，必须保障一定的安全性。

基础安全：云数据库 API 地址必须为 HTTPS

第一重安全：确保访问云数据库 API 的 token 不暴露在公网，不放到前端代码中

第二重安全：能够访问云数据库 API 的环境密匙需单独开通该应用的权限

第三重安全：确保访问云数据库 API 的 token 有过期时间

第四重安全：如不慎泄露，请尽快取消该密匙的云数据库应用权限或删除该密匙

第五重安全：如不慎泄露并造成数据恶意删除，请联系客服进行数据恢复，该方法需要一定人力和时间，所以尽量在源头做好安全管控

请求内容 body#

{  "appId": "user", // 必填  "tableId": "User", // 必填  "action": "get", // 必填  "ids": {},  "columns": {},  "getColumns": [],  "engineIndex": "",  "orderType": "desc",  "endIds": {},  "rowsLimit": 100,  "filter": {},  "condition": {},  "updateType": "",  "skip": 0,  "getTotalCount": false,  "querys": [],  "sorters": [],  "nextToken": ""}

appId是需要操作数据库表的应用 ID；

tableId是需要操作数据库表的 ID；

action是需要操作数据库表的动作，有以下几种：

get#

查询单个数据。

必填项：ids 即该条数据的所有 id，示例：

{  "ids": {    "userId": "test",    "postId": "one"  }}

可选项：getColumns 查询该条数据的部分列，如果不填则默认返回该条数据的全部列，示例：

{  "getColumns": ["name", "title"]}

如果没有该条数据，则会返回null。

getMany#

查询多条数据。

必填项：ids 即查询范围的起始 id。

示例：

{  "ids": {    "userId": "test",    "postId": "CDB:tableMaxId" // 特殊值，代表最大  }}

必填项：endIds 即查询范围的终止 id。

示例：

{  "endIds": {    "userId": "test",    "postId": "CDB:tableMinId" // 特殊值，代表最小  }}

可选项：orderType 查询的排序方向，asc为正序，即从小到大，desc为倒序从大到小，默认为倒序，示例：

{  "orderType": "asc"}

可选项：rowsLimit 需要返回数据的数量，默认为 100，最大为 5000，示例：

{  "rowsLimit": 100}

可选项：filter 可以在返回的数据中进行一次过滤，减少不符合条件数据的网络传输，示例：

{  "filter": {    "conditionList": [      {        "column": "name",        "symbol": "=",        "value": "清林云"      },      {        "column": "title",        "symbol": "=",        "value": "BaaS"      }    ],    "conditionLogical": "and"  }}

conditionList是过滤条件列表，可以有一个或多个过滤条件。过滤条件有三个值：

column 是需要过滤的字段名；

symbol 是字段的值和给定的值之间的比较运算符号，符号有：= != > >= < <=，意思是等于 不等于 大于 大于等于 小于 小于等于；

value 是需要比较的给定的值；

conditionLogical是多个过滤条件的组合逻辑：

and是默认值，即代表过滤后的数据要满足所有过滤条件；

not代表过滤后的数据不会符合过滤条件，conditionList只能有一个过滤条件；

or代表过滤后的数据只符合过滤条件其中之一即可；

可选项：getColumns 查询所有数据的部分列，如果不填则默认返回数据的全部列，示例：

{  "getColumns": ["name", "title"]}

create#

新增一条数据。

必填项：ids 即新增数据的所有 id。

示例：

{  "ids": {    "userId": "test",    "postId": "CDB:nanoId" // 特殊值，代表21位随机值，类似uuid  }}

另外还有几个特殊值：

CDB:timeId：即 13 位时间戳加 10 位随机值，适用于极其严格要求数据不重复的场景；

CDB:microsecondId：当数据表的类型为 A 系列并且该字段类型为microsecondId时使用，格式为时间戳+3 位唯一事务数字；

必填项：columns 即新增数据的所有列字段。

示例：

{  "columns": {    "string1": "qqq",    "int2": 2,    "boolean3": true,    "float4": 2.3  }}

可选项：condition 可以在新建数据时提前进行一次判断，示例：

{  "condition": {    "type": "ignore"  }}

类型有如下几种：

ignore: 忽略判断，直接新建数据，如果原先有该 ID 的数据，则会覆盖；

exist: 期待已存在该 ID 的数据，如果原先有该 ID 的数据，则会覆盖；

notExist: 期待不存在该 ID 的数据，如果原先有该 ID 的数据，则会报错；

默认是ignore。

update#

更新一条数据。

必填项：ids 即更新数据的所有 id。

示例：

{  "ids": {    "userId": "test",    "postId": "postone"  }}

必填项：columns 即需要更新数据的字段。

示例：

{  "columns": {    "string1": "qqq",    "int2": 2,    "boolean3": true,    "float4": 2.3  }}

可选项：condition 可以在新建数据时提前进行一次判断，示例：

{  "condition": {    "type": "ignore",    "conditionList": [      {        "column": "name",        "symbol": "=",        "value": "清林云"      },      {        "column": "title",        "symbol": "=",        "value": "BaaS"      }    ],    "conditionLogical": "and"  }}

类型有如下几种：

ignore: 忽略判断，直接更新数据，如果原先没有该 ID 的数据，则会新建；

exist: 期待已存在该 ID 的数据，如果原先没有该 ID 的数据，则会报错；

notExist: 期待不存在该 ID 的数据，如果原先有该 ID 的数据，则会报错；

默认是ignore。

更新数据的条件判断多了个列判断，和filter一样，具体可见getMany。

delete#

删除一条数据。

必填项：ids 即删除数据的所有 id。

示例：

{  "ids": {    "userId": "test",    "postId": "posttwo"  }}

可选项：condition 可以在删除数据时提前进行一次判断，示例：

{  "condition": {    "type": "ignore"  }}

类型有如下几种：

ignore: 忽略判断，直接删除数据，如果原先有该 ID 的数据，则会删除，没有也正常执行；

exist: 期待已存在该 ID 的数据，如果原先没有该 ID 的数据，则会报错；

notExist: 期待不存在该 ID 的数据，如果原先有该 ID 的数据，则会报错；

默认是ignore。

search#

可选项：querys 查询条件列表。查询条件由多个条件组合而成，满足条件的数据会返回，看如下示例：

{  "querys": [    {      "queryType": "equal", // 精确查询      "column": "title",      "value": "a" // 只有该列的值完全等于value时才可查到    },    {      "queryType": "equalMany", // 多词精确查询      "column": "title",      "value": ["b", "c"] // 列值满足一个即可    },    {      "queryType": "match", // 匹配查询，用于text类型字段      "column": "title", // 要查询的列名      "value": "this is 米饭" // 该分词可查到包含 this 米 米饭 的数据    },    {      "queryType": "matchPhrase", // 短语查询，用于text类型字段      "column": "title",      "value": "爱吃米饭" // 可以查到 我爱吃米饭，查不到 爱吃楼下的米饭    },    {      "queryType": "range", // 范围查询，用于int字段      "column": "title",      "rangeFrom": 100,      "rangeTo": 2000    },    {      "queryType": "prefix", // 前缀查询      "column": "title",      "value": "上海" // 可查到值为 上海市浦东新区 的数据    },    {      "queryType": "constScore", // 相关性查询      "column": "title",      "value": "查询值"    },    {      "queryType": "functionScore", // 因子相关性查询      "column": "title",      "factor": "因子",      "value": "查询值"    },    {      "queryType": "nested", // 嵌套查询，用于nested类型数据      "column": "title",      "searchKey": "customKey",      "searchValue": "someValue"    },    {      "queryType": "wildcard", // 通配符查询      "column": "title",      "value": "上海市??区*街道" // （*）代表任意字符序列，问号（?）代表任意单个字符    },    {      "queryType": "matchAll" // 所有行数查询或随机返回数据    },    {      "queryType": "distance", // 距离查询      "column": "location",      "centerPoint": "30.00,-90.22", // 中心点坐标，纬度在前，经度在后      "distance": 1200.5 // 和中心点的距离，单位：米    },    {      "queryType": "distanceBounding", // 地理矩形范围查询      "column": "location",      "topLeft": "30.20,-90.22", // 左上角坐标      "bottomRight": "30.00,-90.20" // 右下角坐标    },    {      "queryType": "distancePolygon", // 地理多边形查询      "column": "location",      "points": ["30.20,-90.22", "30.20,-90.22"] // 多边形端点坐标    },    {      "queryType": "exist", // 列存在查询      "column": "title" // 该列的值不为空即可返回    }  ]}

可选项：sorters 查询排序方式。先看示例：

{  "sorters": [    {      "sorterType": "ids",      "orderType": "asc"    },    {      "sorterType": "column",      "orderType": "desc",      "columnName": "title"    },    {      "sorterType": "union",      "orderType": "desc"    },    {      "sorterType": "distance",      "orderType": "desc",      "columnName": "location",      "points": ["0,0"]    }  ]}

排序方式可以有多个，会根据顺序依次排序。排序方式的字段解释如下：

  • sorterType 排序类型:
    • 值为column代表是以某个列排序，由columnName决定；
    • 值为ids代表主键数据排序；
    • 值为union代表相关性排序，使用了 BM25 算法计算相关性；
    • 值为distance代表距离排序，计算列由columnName决定，距离点由points决定；
  • columnName 排序列名
  • orderType 值为asc正序或desc倒序,四种类型都需要该值，默认为倒序从大到小
  • points 为排序距离点，格式为["0,0"]

如果设置只查询部分列，需要排序的列一定要包含在getColumns内。

可选项：rowsLimit 需要返回的数据量，默认为 20，最大为 100，示例：

{  "rowsLimit": 100}

可选项：getTotalCount 是否返回符合查询条件的数据总数，默认为false，示例：

{  "getTotalCount": true}

可选项：skip 查询时从第几条数据开始，默认为 0，最大 5000，常用于查询多条数据时进行翻页的功能。

示例：

{  "skip": 0}

可选项：nextToken 查询翻页的信息。

当查询数据时，如果符合条件的数据有 200 条，一次最多只能查询 100 条，那么返回的数据中就会携带前 100 条数据和nextToken信息，前端收到后如果需要翻页，查询第 100-200 条数据，那么加入nextToken即可查询到后面的数据。

skip和nextToken都可以进行查询翻页，但 skip 有最大值，超过最大值时的翻页就需要nextToken来处理。

示例：

{  "nextToken": "xxx"}

可选项：getColumns 查询所有数据的部分列，如果不填则默认返回数据的全部列，示例：

{  "getColumns": ["name", "title"]}

返回内容#

返回内容都是 JSON 格式，分别有成功和失败两种状态：

成功#

成功会返回数据：

// action: "get"{  "ids": "idsValue",  "columns": "columnsValue"}
// action: "getMany"{  "data": [    {      "ids": "idsValue",      "columns": "columnsValue"    }  ],  "nextId": { "ids": "idsValue" }}
// action: "create"{  "ids": "idsValue"}
// action: "update"{  "ids": "idsValue"}
// action: "update"// updateType: "increment"{  "columns": "columnsValue"}
// action: "delete"{  "success": true}
// action: "search"{  "data": [    {      "ids": "idsValue",      "columns": "columnsValue"    }  ],  "nextToken": "xxx",  "totalCounts": 100}

失败#

失败返回遵循最新的通用 HTTP 异常返回标准草案，但是更改了状态码 400 为 200，加入了errCode项进行判断，因为在某些请求客户端下，400 状态会导致一些程序异常。

{  "errCode": "错误码", // 通常为 1，第三方服务则是第三方错误码，验证请求是否出错一般判断是否有errCode即可，如 if(res.errCode){错误处理} else {正常处理}  "type": "错误的API",  "title": "错误原因",  "detail": "详细数据",  "instance": "请求ID和客户端数据"}

其中，detail是如下字段的 Json 字符串：

{  "envId": "环境ID",  "keyId": "环境Key",  "appId": "应用ID",  "tableId": "表ID",  "action": "执行动作"}

instance是如下字段的 Json 字符串：

{  "requestId": "请求ID", // 如果出现莫名错误，向客服提交该项用于追踪bug  "clientIP": "请求端IP地址", // 请求端IP地址  "referer": "请求来源", // 请求来源  "userAgent": "请求客户端", // 请求客户端  "date": "时间戳" // 时间戳}