2.4 数据访问接口

数据引擎提供RESTful风格的访问接口，用于查询数据、插入/更新数据和删除数据。

2.4.1 查询数据

提供一个接口，实现查询数据，支持分页、过滤、排序、关联查询、子查询等。

2.4.1.1 接口说明

请求URL：域名/微服务名/模块名/dbrest/数据集标识
请求方法：GET
请求头：
- dbrest-resource : class -- 参数中使用的是数据集中定义的标识
- x-output-count : 1 -- 在请求返回中返回记录数
请求参数：
- limit -- 分页数据大小，-1表示取全部数据，例如：limit=-1或limit=20
- offset -- 取第几页数据，页数从0开始，例如：offset=0
- select -- 查询数据列
  - 直接写列名，例如：select=name
  - 多列使用逗号分隔，例如：select=fid,name
  - 列名前面加上数据集标识，例如：select=customer.name
  - 给列定义别名，例如：select=customer.name as "customer_name"
  - 使用统计函数计算统计值，例如：select=count(fid)
    - 提供5个统计函数：计数count(列标识)、计算合计sum(列标识)、计算最大值max(列标识)、计算平均值avg(列标识)、计算最小值min(列标识)
- order -- 排序
  - asc表示升序，desc表示降序。例如：order="orderDate".desc
  - 多列排序，使用逗号分隔。例如：order="orderDate".desc,"orderNo".asc
- 列名 -- 过滤条件
  - 支持等于、字母匹配、包含等各种条件，条件操作符详见下表
  - 一个条件就是一个参数，例如：?orderNo=eq.11
  - 多个条件默认是and关系，例如：?fid=not.is.null&orderNo=eq.11
  - 支持多个条件使用or关系：or.。例如：?fid=not.is.null&or.orderNo=eq.11
  - 支持使用小括号定义优先级：&(和&)。例如：?fid=not.is.null&(&orderNo=eq.11&or.orderDate=not.is.null&)
  - 使用子查询结果，例如：使用subquery0的结果，写为$subquery:subquery0，当子查询返回多值时，使用in操作符，写为?fid=in.$subquery:subquery0
- join -- 关联查询
  - 支持4种关联方式：左连接left、右连接right、内连接inner和全连接full
  - 参数写法：左数据集.关联方式.右数据集[左数据集列.条件操作符.右数据集列]，例如：join=saleOrder.left.customer[customId.eq.id]
  - 关联条件中，用3个大括号引用值，例如：active.eq.{{{1}}}或{{{1}}}.eq.active
  - 多个关联条件，用冒号分隔，例如：join=saleOrder.left.customer[customId.eq.id:active.eq.{{{1}}}]
  - 多个表join，用逗号分隔，例如：join=saleOrder.left.customer[customId.eq.id],customer.left.project[projectId.eq.id]
- distinct -- 设置为true表示去重查询
- $subquery -- 定义子查询，也可以称作嵌套查询，子查询用于为主查询返回其所需数据，对检索数据进行进一步的限制
  - 支持多个子查询
  - 子查询的 SELECT 子句中只能有一个列
  - 返回多行数据的子查询只能同多值操作符一起使用，比如 in 操作符
  - 使用JSON描述子查询，格式为{"子查询名称","子查询的url"}，例如：定义两个子查询subquery0和subquery1，写为$subquery={"subquery0":"/main/dbrest/saleOrderDetail?limit=-1&offset=0&select=saleOrder&product=eq.办公桌","subquery1":"/main/dbrest/customer?limit=-1&offset=0&select=id&customType=eq.vip"}
- $get -- 获取附件流，详见 2.5.9 获取附件流
- $detail -- 输出数据集，详见 2.5.3 —— 2.5.5 三节
响应头：
- Content-Range -- 查询范围/返回记录数例如：每页取20条数据，查询第1页数据，查询结果返回3条数据，Content-Range的值为0-19/3

请求返回

返回JSON数组，如果请求头中设置了x-output-count : 1，JSON数组第一行会返回记录数

[{
    "recordCount": 1
},{
    "fid":"C9CFFE7FD3D000017C3A1FDDA5401C83",
    "orderNo":"SO20220011",
    "totalMoney":"12345.00",
    "files":null,
    "orderDate":"2022-05-06"
}]

2.4.1.2 接口案例

查询全部数据

查询全部数据，limit参数必须设置为-1，url如下：

域名/微服务名/main/dbrest/saleOrder?limit=-1

分页查询数据

一页取20条记录，查询第一页的数据，url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0

指定数据列

查询表中5列数据，其他列不查询，url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&select=fid,orderNo,totalMoney,files,orderDate

过滤数据

查询5月1日到5月31日期间的订单，url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&select=fid,orderNo,totalMoney,files,orderDate&orderDate=gte.2022-5-1&orderDate=lte.2022-5-31

数据排序

查询订单，先按下单日期排降序，再按订单编号排升序，url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&select=fid,orderNo,totalMoney,files,orderDate&order="orderDate".desc,"orderNo".asc

关联查询

通过销售订单的客户id列左关联客户的id列，查询出客户名称列，url如下：

域名/微服务名/main/dbrest/saleOrder?select=fid,orderNo,totalMoney,files,orderDate,customer.name as "customer_name"&join=saleOrder.left.customer[customId.eq.id]

通过销售订单的客户id列左关联客户的id列，再通过客户的项目id列左关联项目的id列,查询出客户名称、项目名称列，url如下：

域名/微服务名/main/dbrest/saleOrder?select=fid,orderNo,totalMoney,files,orderDate,customer.name as "customer_name",project.name as "project_name"&join=saleOrder.left.customer[customId.eq.id:{{{1}}}.eq.active],customer.left.project[id.eq.orderNo]

去重

去重查询销售订单中的客户id，url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&distinct=true&select=customId

统计

统计总记录数、订单金额合计、最大订单金额、订单金额的平均值、最小订单金额，url如下：

域名/微服务名/main/dbrest/saleOrder?select=count(fid),sum(totalMoney),max(totalMoney),avg(totalMoney),min(totalMoney)

子查询

使用一个子查询，查询订单明细中包括办公桌的订单，url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&select=fid,orderNo,totalMoney,orderDate&fid=in.$subquery:subquery0&$subquery={"subquery0":"/main/dbrest/saleOrderDetail?limit=-1&offset=0&select=saleOrder&product=eq.办公桌"}

其中$subquery的值需要使用Base64加密，加密后的url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&select=fid,orderNo,totalMoney,orderDate&fid=in.$subquery:subquery0&$subquery=eyJzdWJxdWVyeTAiOiIvbWFpbi9kYnJlc3Qvc2FsZU9yZGVyRGV0YWlsP2xpbWl0PS0xJm9mZnNldD0wJnNlbGVjdD1zYWxlT3JkZXImcHJvZHVjdD1lcS7lip7lhazmoYwifQ==

使用两个子查询，查询订单明细中包括办公桌的，且客户类型为vip的订单，url如下:

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&select=fid,orderNo,totalMoney,files,orderDate,customId&fid=in.$subquery:subquery0&customId=in.$subquery:subquery1&$subquery={"subquery0":"/main/dbrest/saleOrderDetail?limit=-1&offset=0&select=saleOrder&product=eq.办公桌","subquery1":"/main/dbrest/customer?limit=-1&offset=0&select=id&customType=eq.vip"}

其中$subquery的值需要使用Base64加密，加密后的url如下：

域名/微服务名/main/dbrest/saleOrder?limit=20&offset=0&select=fid,orderNo,totalMoney,files,orderDate,customId&fid=in.$subquery:subquery0&customId=in.$subquery:subquery1&$subquery=eyJzdWJxdWVyeTAiOiIvbWFpbi9kYnJlc3Qvc2FsZU9yZGVyRGV0YWlsP2xpbWl0PS0xJm9mZnNldD0wJnNlbGVjdD1zYWxlT3JkZXImcHJvZHVjdD1lcS7lip7lhazmoYwiLCJzdWJxdWVyeTEiOiIvbWFpbi9kYnJlc3QvY3VzdG9tZXI/bGltaXQ9LTEmb2Zmc2V0PTAmc2VsZWN0PWlkJmN1c3RvbVR5cGU9ZXEudmlwIn0=

上文中提到的条件操作符，见下表

操作符	含义	案例（以过滤订单编号orderNo列为例）
eq	等于	orderNo=eq.11
neq	不等	orderNo=neq.11
gt	大于	orderNo=gt.11
lt	小于	orderNo=lt.11
gte	大于等于	orderNo=gte.11
lte	小于等于	orderNo=lte.11
like	字符匹配，支持通配符*	orderNo=like.2 查找包括2的 orderNo=like.2 查找以2开头的 orderNo=like.2 查找以2结尾的
ilike	字符匹配（不区分大小写）	orderNo=ilike.2
not.like	字符不匹配	orderNo=not.like.2
nilike	字符不匹配（不区分大小写）	orderNo=not.ilike.2
in	包含	orderNo=in.11,22
not.in	不包含	orderNo=not.in.11,22
is.null	为空	orderNo=is.null
not.is.null	非空	orderNo=not.is.null

字符匹配适用于模糊搜索，即通过输入部分内容进行查找
包含是全词匹配，不能用于模糊搜索，适用于同时查找多个值，相当于多个过滤条件，使用or连接

2.4.2 插入一条数据

提供一个接口，实现插入一条数据。

2.4.2.1 接口说明

请求URL：域名/微服务名/模块名/dbrest/数据集标识
请求方法：POST
请求头：
- dbrest-resource : class -- 参数中使用的是数据集中定义的标识
请求体 -- JSON，新增的数据

请求返回 -- JSON

  {
      message: "插入成功",
      result: 1, -- 实际插入记录数
      status: 201
  }

2.4.2.2 接口案例

新增一条数据

请求URL：域名/微服务名/main/dbrest/saleOrder 请求体：

{
    fid: "C9D01FD2A4B00001F552157017849320",
    files: null,
    orderDate: "2022-05-06",
    orderNo: "22",
    totalMoney: "220"
}

2.4.3 插入/更新多条数据

提供一个接口，实现插入或者更新，通过主键的值进行判断，如果数据表中不存在这个主键值，则插入，否则更新。

2.4.3.1 接口说明

请求URL：域名/微服务名/模块名/dbrest/数据集标识?pk=主键列标识
请求方法：PUT
请求头：
- dbrest-resource : class -- 参数中使用的是数据集中定义的标识
请求参数：
- pk -- 主键列标识
请求体 -- JSON数组，新增/修改的数据

请求返回 -- JSON

  {
      message: "插入/更新成功",
      result: 1, -- 实际插入/更新记录数
      status: 201
  }

2.4.3.2 接口案例

新增/修改一条数据

请求URL：域名/微服务名/main/dbrest/saleOrder?pk=fid 请求体：

[{
    fid: "C9D01FD2A4B00001F552157017849320",
    files: null,
    orderDate: "2022-05-06",
    orderNo: "22",
    totalMoney: "220"
}]

2.4.4 删除数据

提供一个接口，实现删除一条或多条数据。支持两种参数，一种是删除条件，另一种是要删除的数据（JSON数组格式）。无参数表示删除全部数据。

2.4.4.1 接口说明

请求URL：域名/微服务名/模块名/dbrest/数据集标识
请求方法：DELETE
请求头：
- dbrest-resource : class -- 参数中使用的是数据集中定义的标识
请求参数：下面的两个参数设置一个即可
- 列名 -- 删除条件
- $body -- 要删除数据的JSON数组，可以只包括主键的值

返回数据 -- JSON

  {
      message: "删除成功",
      result: 1, -- 实际删除记录数
      status: 200
  }

2.4.4.2 接口案例

使用删除条件，删除一条数据

根据主键删除一条数据，URL如下：

域名/微服务名/main/dbrest/saleOrder?fid=eq.C9D01FD2A4B00001F552157017849320

使用删除条件，删除多条数据

根据主键删除两条数据，URL如下：

域名/微服务名/main/dbrest/saleOrder?fid=in.C9D01FD2A4B00001F552157017849320,C9D01FD2A4B00001F552157017849321

删除订单编号小于11的数据，URL如下

域名/微服务名/main/dbrest/saleOrder?orderNo=lt.11

使用JSON数组格式的数据，删除多条数据

根据JSON数组删除两条数据，URL如下：

域名/微服务名/main/dbrest/zidian?$body=[{fid:1},{fid:2}]

url上的参数需要转码，转码后的url如下：

域名/微服务名/main/dbrest/zidian?$body=%5B%7Bfid%3A1%7D%2C%7Bfid%3A2%7D%5D

数据访问接口