数据治理中心 DATAARTS STUDIO-脚本/MyBatis方式生成API:配置取数逻辑
配置取数逻辑
本例中以脚本方式说明如何配置API取数逻辑。Mybatis方式与之相比差异在于参数解析形式和支持的语法差异,在使用流程上没有区别。
如果使用Mybatis方式生成API,则需要将本章节脚本中的参数解析格式由${parameter}修改为#{parameter}形式,另外Mybatis方式支持的标签语法可在界面中单击脚本编辑处的,查看弹出的Mybatis脚本编辑提示。
- 选择数据源、数据连接、数据库等数据信息。
数据服务仅支持部分数据源,详情请参见DataArts Studio支持的数据源。您需提前在DataArts Studio管理中心中配置好数据源,按照脚本编辑提示要求输入SQL语句。
- 选择分页方式,推荐使用自定义分页方式。
- 默认分页是指在创建API时输入了SQL,数据服务会自动基于SQL外层包装分页逻辑。
数据服务在处理调试或者调用时,将自动在用户SQL外层包装分页逻辑,从而变成以下脚本:
SELECT * FROM (SELECT * FROM userinfo WHERE id=${userid}) LIMIT {limitValue} OFFSET {offsetValue}
其中limitValue表示读取的数据条数,offsetValue表示跳过的数据条数(即偏移量),例如limitValue为20、offsetValue为40时,表示跳过40条数据,然后读取20条数据。一般而言,limitValue和offsetValue可作为入参,在调试或者调用API时传入值。如果未定义limitValue或offsetValue,系统将默认赋值。
- 自定义分页是指在创建API时,数据服务将不对SQL进行处理,分页逻辑需要在写SQL时由用户自定义。
如果已知需要读取的数据条数limitValue和需要跳过的数据条数offsetValue,则分页逻辑可以写成以下脚本:
SELECT * FROM userinfo WHERE id=${userid} LIMIT {limitValue} OFFSET {offsetValue}
而在实际使用中,更多的是根据分页后的页面大小pageSize和页码pageNum定义分页逻辑,脚本样式如下:
SELECT * FROM userinfo WHERE id=${userid} LIMIT {pageSize} OFFSET {pageSize*(pageNum-1)}
值得注意的是,不同的数据源具有不同的语法风格,分页脚本应按照数据源语法要求调整。例如:
- DLI数据源不支持“LIMIT {limitValue} OFFSET {offsetValue}”的写法,仅支持“LIMIT {limitValue}” 。
- HETU数据源分页需要反转,不支持“LIMIT {limitValue} OFFSET {offsetValue}”的写法,仅支持“OFFSET {offsetValue} LIMIT {limitValue}”。
- 默认分页是指在创建API时输入了SQL,数据服务会自动基于SQL外层包装分页逻辑。
- 编写API查询SQL。
在脚本编辑页面,单击脚本编辑处的,按照脚本编辑提示开发SQL查询语句。单击可将入参添加为SQL语句的API请求参数。
例如,需要在用户表中根据用户ID查询用户信息时,取值脚本可写为如下脚本。其中,“id”为userinfo表中的字段,“userid”为API中定义的入参。
SELECT * FROM userinfo WHERE id=${userid}
如果分页方式为自定义分页,页面大小pageSize为10、页码pageNum为2时,按照LIMIT {pageSize} OFFSET {pageSize*(pageNum-1)}转换方法,脚本可写为:
SELECT * FROM userinfo WHERE id=${userid} LIMIT 10 OFFSET 10
图3 编写API查询SQL
脚本编辑完成后,单击脚本编辑窗口下方的“测试SQL”,填写入参值,执行验证是否能返回预期结果。如果测试失败,可在“预览SQL”页签下查看实际运行的SQL语句是否符合预期,或者通过“日志”页签查看报错信息。
图4 测试SQL
- 添加排序参数。
- 字段名称对外不可见,是所选的数据表中的字段,是API调用时实际访问的内容。在API查询SQL语句已编写完成且测试通过的前提下,可在“字段名称”输入框中选择排序字段。
- 变量可自定义,用于与字段名称关联。在“变量”输入框中输入参数名称(一般填写为参数名称即可),系统会自动修改为变量形式。
- 是否可选决定了调用API时此排序参数是否必选,勾选则表示可以不使用此参数。
- 排序方式分为升序、降序以及自定义,表示了当前参数允许使用的排序形式。如果设置为升序或降序,在API测试或调用时,如果排序参数描述pre_order_by的值与此处设置不符,则会导致调用失败。
排序字段需要添加到SQL脚本中才能生效,单击将排序参数添加到SQL语句,使用ORDER BY排序。
例如,需要在用户表中根据用户ID查询用户信息,通过age和kk两个字段排序,页面大小pageSize为10、页码pageNum为2时,脚本样例如下。
SELECT * FROM userinfo WHERE id=${userid} order by (${age},${kk}) LIMIT 10 OFFSET 10
图5 添加排序参数
脚本编辑完成后,单击脚本编辑窗口下方的“测试SQL”,填写入参值和pre_order_by参数值,执行验证是否能返回预期结果。其中pre_order_by参数值已由系统根据排序参数信息给出默认值,默认升序排序。一般而言,排序参数描述pre_order_by的值填写形式为“排序参数参数名:ASC”或“排序参数参数名:DESC”,其中ASC表示升序,DESC表示降序,多个排序参数描述以“英文分号”进行分隔。
如果测试失败,可在“预览SQL”页签下查看实际运行的SQL语句是否符合预期,或者通过“日志”页签查看报错信息。
- pre_order_by是非必填参数,默认取必选排序字段升序作为排序的依据。
- 当配置pre_order_by参数值时,需严格按照排序参数列表中配置的排序参数顺序、可选属性和排序方式进行配置,否则会调用失败。
图6 测试SQL
- 单击“下一步”,进行API测试页面。