数据访问接口

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

特别说明

数据访问接口是 http 请求，前后端皆可调用

在前端访问数据，优先使用数据组件，其次使用 JS SDK，最后使用数据访问接口

在后端访问数据，优先使用 MyBatis，其次使用 Java SDK，最后使用数据访问接口

查询数据

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

接口说明

请求 URL：
- http(s)://域名/微服务名/模块名/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 -- 获取附件流，详见《获取附件流》
- $detail -- 输出数据集，详见《关联查询》《嵌套数据查询》《跨数据库查询》三节
响应头：
- 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"
}]

请求案例

http://entrydevguide8-vip.xcaas.com:8800/react/main/dbrest/saleOrder

接口案例

查询全部数据

查询全部数据，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 如下：

{% raw %}
域名/微服务名/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]
{% endraw %}

去重

去重查询销售订单中的客户 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 连接

插入一条数据

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

接口说明

请求 URL：
    域名/微服务名/模块名/dbrest/数据集标识
请求方法：
    POST
请求头：
    dbrest-resource : class - 固定值，表示参数中使用的是数据集中定义的标识
请求体:
    JSON，新增的数据
请求返回:
    JSON，格式如下
    {
        message: 消息，例如：插入成功
        result: 实际插入记录数
        status: 状态码，执行成功返回 201
    }

接口案例

新增一条数据

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

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

插入/更新多条数据

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

接口说明

请求 URL：
    域名/微服务名/模块名/dbrest/数据集标识?pk=主键列标识
请求方法：
    PUT
请求头：
    dbrest-resource : class - 固定值，表示参数中使用的是数据集中定义的标识
请求参数：
    pk：主键列标识
请求体:  
    JSON 数组，新增/修改的数据
请求返回
    JSON，格式如下
    {
        message: 消息，例如：插入/更新成功
        result: 实际插入/更新记录数
        status: 状态码，执行成功返回 201
    }

接口案例

新增/修改一条数据

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

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

删除数据

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

接口说明

请求 URL：
    域名/微服务名/模块名/dbrest/数据集标识
请求方法：
    DELETE
请求头：
    dbrest-resource : class - 固定值，表示参数中使用的是数据集中定义的标识
请求参数：
    下面的两个参数设置一个即可
    列名：删除条件
    $body：要删除数据的 JSON 数组，可以只包括主键的值
返回数据
    JSON，格式如下
    {
        message: 消息，例如：删除成功
        result: 实际删除记录数
        status: 状态码，执行成功返回 200
    }

接口案例

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

根据主键删除一条数据，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

js 中调用示例代码如下：

let param = encodeURIComponent("[{'fid':'1'},{'fid':'2'}]");
$page.request({
    url : "$serviceName/main/dbrest/zidian?$body=" + param,
    method : 'delete",
    header : {'dbrest-resource':'class'}
})

数据访问接口

数据访问接口

查询数据

接口说明

接口案例

查询全部数据

分页查询数据

指定数据列

过滤数据

数据排序

关联查询

去重

统计

子查询

插入一条数据

接口说明

接口案例

插入/更新多条数据

接口说明

接口案例

删除数据

接口说明

接口案例

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

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

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

results matching ""

No results matching ""