通过直连数据源模式创建API
直连数据源模式是通过SQL直接从数据源创建API。本文为您介绍如何使用直连API模式生成API。
步骤一:选择生成API的方式
在Dataphin首页,单击顶部菜单栏服务。
系统默认进入市场页面。
按照下图操作指引,进入API创建方式选择对话框。
在API创建方式选择对话框直连数据源模式后,单击确定。
步骤二:配置API参数信息
在新建API页面,配置API基本信息和参数配置。
API基本信息配置
参数
描述
API名称
命名规则如下:
只能包含汉字、字母、数字或下划线(_)。
长度为4~42个字符。
以字母开头。
全局唯一。
请求方式
API请求方式包括GET和LIST:
GET:请求服务器获取指定的某个资源。
LIST:请求服务器获取某一部分的资源。
API分组
选择当前项目下配置的API分组,如需创建,请参见创建服务分组。
描述
填写对API简单的描述。
协议
默认选中HTTP。HTTP即超文本传输协议HTTP(HyperText Transfer Protocol),是应用最为广泛的网络协议。
勾选HTTPS协议时,请确保独立域名的SSL证书有效,避免无法正常调用。请通过选择平台管理网络配置,在网络配置页面,进行SSL证书配置。
超时时间
超时时间用于监控API调用的时长。调用API过程中如果超过了设定的超时时间,则调用API时会报错,便于您及时发现并处理调用API的异常情况。异常情况查看,详情请参见查看及管理运维监控API。
最大返回条数
API最大的返回条数。需输入1~10000的正整数。当请求方式选择为LIST时显示该配置项。
缓存设置
支持开启或关闭。开启后需配置缓存时长。
版本号
请填写API的版本号,每份配置信息会有所属版本号,以便于和上个版本信息对比。64字符以内。该API下版本号唯一。
API请求参数和返回参数配置
在配置API请求参数和返回参数过程中,您需要先确定输入参数和输出参数的来源表,再编写API SQL并解析出请求参数和返回参数,最后配置请求参数和返回参数的基本信息。
参照以下图表,确定输入参数和输出参数的来源表,并根据参考示例编写API SQL脚本。
参数
描述
模式
选择数据来源环境,支持Basic或Dev-Prod。
Basic模式下开发时、提交及发布线上均读取生产库。
Dev-Prod模式下开发及提交读取开发库,发布线上读取生产库。
数据源类型
选择数据源类型。包含IMPALA、Oracle、MySQL、PostgreSQL、Microsoft SQL Server、Hologres、Lindorm、ClickHouse和StarRocks。
说明MySQL支持版本5.x和8.x。
数据源
选择对应数据源类型的数据源。
SQL模式
支持选择基础SQL和高级SQL两种模式。
API SQL脚本编辑
支持同一数据源下的单表查询、多表关联查询和嵌套查询。
PostgreSQL数据源类型不支持跨Schema。
不支持以下用法:
不支持多条SQL语句。
不支持INSERT、UPDATE、CREATE和DELETE等非SELECT语法。
不支持
SELECT *
,查询时必须明确指定查询的列。不支持在SQL语句里设置参数的可选项。
如果SELECT查询列的列名带有表名前缀(例如
t.name
),则必须取别名作为返回参数名(例如t.name as name
)。如果使用聚合函数(MIN、MAX、SUM和COUNT等),必须取别名作为返回参数名。例如
sum(num) as total_num
。支持在SELECT区域配置参数,例如
select id_card, sum(case when id_card like ${id_card} then 1 else 0 end) as proj_score from 数据表A where c like ${id_card} group by id_card
。不支持在SQL中使用分页语句,需通过分页参数实现分页。
参考示例
Dataphin能解析出返回参数和请求参数的SQL脚本模板如下:
基础SQL示例:
模板一:
select id_card,name from 数据表A where c=${id_card}
模板二:
select id_card,name from 数据表A where c in (${id_card})
模板三:
select max(a) as c,sum(a) as b ,min(a) as d,count(*) as e from 数据表A where c like ${id_card}
模板四:
select t.name as name from 数据表A c=${id_card}
模板五:
select (a+b) as acd,(b+c) as bcf from 数据表A where c=${id_card} and/or b>=${num} and/or c<=${num1}
模板六:
select id_card, sum(case when name like ${name} then 1 else 0 end) as proj_score from 数据表A where c=${id_card} group by id_card
高级SQL示例:
示例一:
select id from 数据表 <where> <if test="name != null "> AND age > ${age} </if> <if test="name == null"> AND age < ${age} </if> </where>
示例二:
select id from 数据表 <where> <if test="name != null "> AND age > #{age} </if> <if test="name == null"> AND age < #{age} </if> </where>
格式化
支持对SQL语句格式化处理展示,仅支持对基础SQL。
数据表
选择数据源中的数据表。选择后,会在字段信息区域,展示已选择数据表中的所有字段。支持复制字段名称及支持复制全表字段或单个字段。
单击SQL试运行,在请求参数输入对话框中,选择参数类型、操作符和试运行输入值,单击确认。
运行日志:支持查看SQL试运行实际执行的SQL语句。
试运行输入值需要配置成绑定字段的字段值,可以在数据预览页面选择绑定字段的字段值。
单击SQL编译后(若选择基础SQL,则点击解析参数),配置请求参数和返回参数的基本信息。
单击SQL编译后,Dataphin会自动解析出API SQL的入参和出参并分别添加至请求参数和返回参数区域。请求参数和返回参数的基本信息基本一致,下表介绍请求参数和返回参数的基本信息说明。
参数
描述
参数名
显示对外开放的参数名。
参数类型
参数类型包括DOUBLE、FlOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY,需选择参数名对应的绑定字段的参数类型。
如果逻辑表的字段类型不在待选参数类型范围内,推荐选择String。
操作符
选择您所需的操作符。
说明expr代表高级SQL中标签参数表达式。
示例
填写请求参数值和返回参数值的示例,便于开发者理解。
描述
填写对请求参数和返回参数的简单描述。
是否必填
选择请求参数是否为调用API时的必填参数。
选择为否:调用API的语句中没有该参数也可以执行调用API的SQL语句。
选择为是:调用API的语句中没有该参数无法执行调用API的SQL语句。
例如,请求参数为id,请求参数为必填参数,返回参数为name;则执行以下语句会有不同的返回:
seclect name from tableA where id=5;
:则返回对应的name字段及数据。seclect name from tableA;
:则SQL语句执行报错。
说明高级SQL语句较为复杂,SQL编译解析的参数不一定完整且正确。因此,您可根据SQL语句对解析结果进行删除参数、新增请求参数和新增返回参数操作。
单击提交,即可完成API的生成。