直连数据源模式是通过SQL直接从数据源创建API。本文为您介绍如何使用直连数据源模式生成API。
权限说明
支持服务的项目管理员和开发用户可以生成API。
使用说明
在API调用时，若数据源本身支持分页，且API请求方式为List，则无论是否开启分页查询，均可使用PageStart及PageSize设置分页。
当使用高级SQL模式创建API时，若在SQL脚本中使用Limit限制返回查询的结果条数，则在API调用时，参数中指定的OrderByList仅针对Limit返回的数据进行排序，即Limit优先级高于OrderByList。例如：将phone_no排名前10的数据再根据paper_no排序。
SELECT * FROM ( select paper_no,phone_no,vip_no from aaaa order by phone_no limit 1,10 ) T0 --即API中的SQL脚本 ORDER BY paper_no ASC--调用时添加OrderByList的执行语句当使用基础SQL创建API时，SQL脚本中使用Limit限制返回查询的结果条数，则不支持使用分页查询。
步骤一：选择生成API的方式
在Dataphin首页，单击顶部菜单栏服务。系统默认进入市场页面。
单击顶部菜单栏开发，再选择项目，单击左侧导航栏API，在API页面，单击+新建API。
在API创建方式选择对话框中，选择直连数据源模式-SQL模式后，单击确定。
步骤二：配置API参数信息
在新建API页面，配置API基本信息和参数配置。
API基本信息配置
参数
描述
API名称
填写API的名称。命名规则如下：
支持汉字、字母、数字或下划线（_）。
长度为4~42个字符。
必须以中文、英文开头。
全局唯一。
请求方式
API请求方式包括GET和LIST：
GET：请求服务器获取指定的某个资源。
LIST：请求服务器获取某一部分的资源。
API分组
选择API需要归属的分组。如需创建，请参见创建服务分组。
描述
填写对API的简单描述。不超过128个字符。
协议
仅支持HTTP。HTTP即超文本传输协议（HyperText Transfer Protocol），是应用最广泛的网络协议。
若网关配置为阿里公有云API网关（专享实例或共享实例）时，支持选择HTTPS协议，请确保独立域名的SSL证书有效，避免无法正常调用。请通过选择平台管理网络配置，在网络配置页面，进行SSL证书配置。
超时时间
超时时间用于监控API调用的时长。调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。关于异常情况的查看，详情请参见查看及管理运维监控API。
最大返回条数
API最大的返回条数为10000条。支持输入1~10000之间的正整数。当请求方式选择为LIST时显示该配置项。
缓存设置
支持开启或关闭。开启后需配置缓存时长。默认300sec（秒），支持设置60秒~1000000秒（约277.78小时）之间的正整数。
版本号
请填写API的版本号，每份配置信息会有所属版本号，以便于和上个版本信息对比。该API下版本号唯一。命名规则如下：
不超过64字符。
支持输入大小英文字母、数字、下划线（_）、点（.）、短划线（-）。
返回类型
默认JSON。
API请求参数和返回参数配置
在配置API请求参数和返回参数过程中，您需要先确定输入参数和输出参数的来源表，再编写API SQL并解析出请求参数和返回参数，最后配置请求参数和返回参数的基本信息。
在参数配置区域，确定输入参数和输出参数的来源表，并根据参考示例编写API SQL脚本。
参数
描述
模式
选择数据来源环境，支持Basic或Dev-Prod。
Basic模式下开发时、提交及发布线上均读取生产库。
Dev-Prod模式下开发及提交读取开发库，发布线上读取生产库。
数据源
选择数据源类型及该类型的数据源。包含IMPALA、Oracle、MySQL、Elasticsearch、Hbase0.9.4/1.1.x/2.x、PostgreSQL、Microsoft SQL Server、Hologres、Lindorm、ClickHouse、StarRocks、TDengine、SAP HANA、DM。
说明MySQL支持MySQL5.1.43、MySQL5.6/5.7和MySQL8版本。
SQL模式
支持选择基础SQL和高级SQL两种模式。
结果分页
当请求方式为List时，支持设置结果分页。开启后，请务必指定排序字段，确保返回查询结果的稳定，避免导致分页查询的部分结果重复及丢失；关闭后，API调试或测试页面不展示分页参数（PageStart及PageSize），您可以取消勾选隐藏参数，展示分页参数。
排序优先级
当SQL模式选择基础SQL时，可以选择排序的优先级顺序，支持选择SQL脚本或OrderByList请求参数。
SQL脚本：若SQL脚本指定了排序，则公共请求参数中的OrderByList不生效。
OrderByList请求参数：在测试或调试API时，SQL脚本中定义的排序与OrderByList公共请求参数同时生效，OrderByList公共请求参数的优先级高于API中定义的排序设置。
当SQL模式选择高级SQL时，在测试或调试API时，SQL脚本中定义的排序与OrderByList公共请求参数同时生效，OrderByList公共请求参数的优先级高于API中定义的排序设置。
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中使用分页语句，需通过分页参数实现分页。
说明数据源类型为TDengine和SAP HANA时，需要在SQL中使用分页语句，定义分页参数。
高级SQL模式支持传参的方式动态指定SQL语句查询返回的字段，参数名必须以var_cols开头（格式：var_cols_xxx），并将参数写在查询语句内，返回参数中需要将所有可支持的字段添加为返回参数。调用API时，在动态参数中传入需要查询的字段即可，未传入的字段在返回结果中为null值。例如：
API的SQL语句：
select id,${var_cols_args} from table1。var_cols_args参数传入值：
name,age,old。API实际执行的SQL语句：
select id,name,age,old from table1。
数据源类型为Elasticsearch时：
当不指定scrollId时，最多只能查询前10000条数据，调用设置分页PageStart和PageSize时，请注意不要查询超过10000条数据，否则调用会失败。
例如：PageStart设置为9998，PageSize最大只能设置为2。
如果要查询10000条以后的数据，需要使用where语句指定scrollId，可以在API开发时指定一个请求参数scrollId，查询时传入对应的scrollId值。
说明指定了scrollId值查询时，就不能使用分页，即PageStart和PageSize不能传值，否则调用失败。
目前，只支持scrollId这个字段作为条件查询，其余字段不生效。例如：
select a from table where scrollId=${scrollId}。
参考示例
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语句。
试运行输入值：需要配置成绑定字段的字段值，可以在数据预览页面选择绑定字段的字段值。
单击解析参数，Dataphin会自动解析出API SQL的入参和出参并分别添加至请求参数和返回参数区域。若SQL模式选择高级SQL，支持勾选保留手动配置，当修改SQL脚本需再次解析参数时，系统将保留已填写的参数信息；如需删除无用参数信息，请手动删除。适用于复杂的SQL语句参数无法解析，需手动填写参数信息的场景。
请求参数和返回参数的基本信息基本一致，下表介绍请求参数和返回参数的基本信息说明。
参数
描述
参数名
显示对外开放的参数名。
参数类型
参数类型包括DOUBLE、FlOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY，需选择参数名对应的绑定字段的参数类型。
如果逻辑表的字段类型不在待选参数类型范围内，推荐选择String。
操作符
选择您所需的操作符。
说明expr代表高级SQL中标签参数表达式。
示例
填写请求参数值和返回参数值的示例，便于开发者理解。支持输入不超过50个字符。
描述
填写对请求参数和返回参数的简单描述。支持输入不超过100个字符。
是否必填
选择请求参数是否为调用API时的必填参数。
选择为否：调用API的语句中没有该参数也可以执行调用API的SQL语句。
选择为是：调用API的语句中没有该参数，将无法执行调用API的SQL语句。
例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回：
返回对应的name字段及数据：
select name from tableA where id=5；。SQL语句执行报错：
select name from tableA;。
说明高级SQL语句较为复杂，SQL编译解析的参数不一定完整且正确。因此，您可根据SQL语句对解析结果进行删除参数、新增请求参数和新增返回参数操作。
单击提交，系统将校验API引用的字段在所属的数据源中是否存在，校验通过后，完成API的生成。