最近更新时间:2022.09.07 11:50:09
首次发布时间:2022.07.26 11:41:17
根据实际业务场景,您可以通过自定义SQL的脚本模式,自行编写API的查询SQL,实现更复杂的查询需求。本文为您介绍如何通过脚本模式生成API。
登录 DataLeap租户控制台 。
在 概览 界面顶部服务窗口,点击 数据服务 ,可快速进入到 数据服务 功能界面。
在上方导航栏中,点击 Query 进入界面。
左侧导航栏中,点击 新建Query,在弹窗中填写以下参数完成新建:
参数 | 说明 |
---|---|
类型 | 表查询类型,可选择向导式、脚本式、原生Query,此处选择脚本式创建。 |
Query名称 | 输入Query名称,只允许英文,数字和下划线。 |
Query存放目录 | 选择Query存放的目录,下拉选择已创建的Query目录,目录创建方式详见:Query目录。 |
网络协议 | 仅支持HTTPS协议。 |
返回类型 | 仅支持JSON返回类型。 |
负责人 | 下拉选择Query负责人。 |
最大QPS | 设置每秒向服务发送的请求数量峰值,需正整数。 |
用途描述 | 输入该Query使用场景,方便后续管理。 |
初始Query版本 | 输入Query版本,三段式个位数,如1.0.0。 |
版本描述 | 输入版本描述,方便后续多版本管理。 |
更多配置(可选) |
|
参数填写完整后,点击 确认 按钮,完成新建Query。
点击Query名称右侧的 更多 按钮,您可以进行以下操作:
详情:查看当前Query的详情,查看通用信息、版本信息、接口信息等。
编辑:进入当前Query编辑界面,配置Query的请求参数、返回参数等。
移动:移动当前Query到其他Query目录文件夹下。
删除:删除当前Query。
点击Query名称,进入编辑界面,选择数据集信息。
下拉选择,或输入关键字搜索 数据集 中创建的 数据集目录文件夹 名称。
下拉选择,或输入关键字搜索目录文件夹下已导入的数据集名称。
数据集相关操作详见:创建数据集
脚本式API需要您在编辑器自行编写Query,脚本编辑目前支持 SQL编辑器 和 XML编辑器, 您可以在下方入口进行切换:
说明
除 请求参数推断 功能添加的请求参数外,您也可以自行新增一些请求参数,而不必在SQL中使用它,请求参数推断 功能不会覆盖掉您自己新增的请求参数。同理 推断返回参数 也不会覆盖您已经指定的返回参数。
手动新增参数详见:向导式Query---参数设置。
功能 | 说明 |
---|---|
编辑框 | 您可以在此输入代码逻辑,语法规则详见:SQL语法详情。
|
请求参数推断 |
|
格式化 | 格式化您书写的代码,使其可读性、结构上更清晰明了。 |
清空 | 一键清空编辑器中您书写的代码。 |
编辑器语法说明:
语法 | 说明 |
---|---|
#{} | 根据数据类型自动生成 SQL 片段,应当尽量使用 #{} 符号,这可以有效避免 SQL 注入问题。 |
${} | 直接将对应的数据插入到 SQL 中。 |
@dataset | 作为数据集占位符,如select p_date from @dataset。 |
注释 | 支持块级注释 /*comment*/,行级:--comment,不支持 <!---->。 |
XML编辑器 | 动态SQL的格式是XML,最外层(根节点)必须要以<select></select>元素包裹。 |
XML转义 | 在XML格式的动态sql中如果包含 > 或 < 等符号, 有些情况会导致XML解析失败,此时需要对xml元素包裹的sql使用转义字符,常用的转义字符见下方表格。 |
常用转义字符
操作符 | 转义字符 | 说明 |
---|---|---|
| 空格 | |
< | < | 小于号 |
> | > | 大于号 |
& | & | 且 |
" | " | 双引号 |
' | ' | 单引号 |
系统策略:默认600s 缓存时间。
手动设置缓存时间,单位:秒。
关闭缓存时间。
数据集、参数等信息配置完成后,您可以点击右上角 保存 按钮,保存该Query:
点 保存 按钮,直接保存当前版本。
若当前线上有已发布的版本,直接修改会影响调用,您可以选择以下保存方式:
另存为新的版本:将当前的修改另存为新版本保存,在弹窗中填写 新版本号 即可完成保存。
另存为新的Query:将当前的修改另存为新Query保存,在弹窗中填写 Query基本信息 完成新建。
或者在右侧 版本信息 内可将当前版本Query下线之后,再进行修改保存。
点击界面右侧导航栏中的 基本信息,即可实现基本信息的修改,支持修改Query名称、负责人、QPS限流、SLA、PCT99、超时等Query基本信息,修改完成后,点击 保存基本信息 按钮,即可完成修改。
点击界面右侧导航栏中的 版本信息,记录历史各Query版本:
您可以点击历史版本号,编辑界面将会切换到历史版本。
您也可以在Query编辑界面上方的导航栏中,选择历史版本号,点击进入编辑。
版本对比:您可以勾选两个版本号,点击右上角 对比 按钮,进行基本信息、参数等对比。
提交日期:您可以点击说明栏的 排序 按钮,根据日期先后进行排序。
操作栏:
下线-线上:将线上已有的版本下线操作。
发布-线上:将未发布的版本操作上线,会覆盖之前已发布的版本。
详情:点击后跳转到详情界面,查看Query的通用信息、版本信息、HTTPS接口信息等详情。
删除:允许删除未发布的版本。
点击界面右侧导航栏中的 SQL语法详情,详细了解语法详情。
仅支持一条 SQL 语句,不支持多条 SQL 语句。
仅支持 SELECT 语句,不支持非 SELECT 语句,如 UPDATE, DESCRIBE 等。
数据集使用字符串 @dataset 进行占位。如select p_date from @dataset。或者使用数据集目录名和数据集名字占位。比如 select p_date from `dir_name`.`dataset_name`。
不支持 SELECT * 语句,必须明确指出需要查询的列。
SELECT 语句的返回结果字段必须和 API 定义的返回参数名字、类型、个数保持一致。如果返回字段是聚合函数或其他表达式,请对其重命名。
SQL 语法是 dynamic unified sql(暂不支持直接使用底层引擎SQL语法)。 使用 #{} 符号来引用请求参数。比如需要引用参数 date 则写作#{date}, #{} 符号会根据参数类型将参数拼接到查询的最终SQL中。
也可以使用 ${} 符号引用参数, ${} 符号不会根据数据类型将参数拼接到最终的SQL中,而是将${}内的参数的值作为字符串直接拼接到SQL中。比如参数 app (类型是string, 值是video), 对于表达式 app_name=#{app} 生成的查询语句是 app_name='video', 对于表达式 app_name=${app} 生成的查询语句是 app_name=video。
支持多种函数,例如日期函数date、adddate、datediff等,您可以在搜索框中输入函数关键字进行搜索。
更多函数列表,详见界面右侧导航栏 SQL语法详情。