SQL模式是基于服务单元编写SQL语句创建API。本文为您介绍如何使用SQL模式生成API。
前提条件
基于服务单元生成API，需先完成服务单元的创建。具体操作，请参见创建服务单元。
权限说明
支持服务的项目管理员和开发用户生成API。
使用说明
在API调用时，若数据源本身支持分页，且API请求方式为List，则无论是否开启分页查询，均可使用PageStart及PageSize设置分页。
当在SQL脚本中使用Limit语句指定返回查询的结果条数时，PageStart及PageSize参数将失效，结果将返回Limit语句指定的条数。
当使用基础SQL创建API时，SQL脚本中使用Limit限制返回查询的结果条数，则不支持使用分页查询。
注意事项
API的请求参数和返回参数需从同一个服务单元（单物理表服务单元或多物理表服务单元）中获取，否则后续无法正常调用该API。
基于服务单元编写SQL语句支持使用MySQL语法，不支持其他SQL语言。
步骤一：选择生成API的方式
在Dataphin首页，单击顶部菜单栏服务 > 开发。
选择项目，单击左侧导航栏API，在API页面，单击+新建API。
在API创建方式选择对话框中，选择服务单元API-SQL模式后，单击确定。
步骤二：配置API参数信息
在新建API页面，配置API基本信息和参数配置。
API基本信息配置
参数
描述
API名称
填写API的名称。命名规则如下：
只能包含汉字、字母、数字或下划线（_）。
长度为4~42个字符。
以字母开头。
全局唯一。
请求方式
API请求方式包括GET和LIST：
GET：请求服务器获取指定的某个资源。
LIST：请求服务器获取某一部分的资源。
数据更新频率
定义API返回数据的更新频率，便于调用方了解数据的时效性，支持每天、每小时、每分钟更新API返回的数据。
排序优先级
支持选择SQL脚本或OrderByList请求参数两种排序优先级顺序。
SQL脚本：若SQL脚本指定了排序，则公共请求参数中的OrderByList不生效。
OrderByList请求参数：在测试或调试API时，SQL脚本中定义的排序与OrderByList公共请求参数同时生效，OrderByList公共请求参数的优先级高于API中定义的排序设置。
API分组
选择API需要归属的分组。如需创建，请参见创建服务分组。
结果分页
当请求方式为List时，支持设置结果分页。开启后，请务必指定排序字段，确保返回查询结果的稳定，避免导致分页查询的部分结果重复及丢失；关闭后，API调试或测试页面不展示分页参数（PageStart及PageSize），您可以取消选中隐藏参数，展示分页参数。
描述
填写对API的简单描述。不超过128个字符。
协议
仅支持HTTP。HTTP即超文本传输协议（HyperText Transfer Protocol），是应用最广泛的网络协议。
若网关配置为阿里公有云API网关（专享实例或共享实例）时，支持勾选HTTPS协议，请确保独立域名的SSL证书有效，避免无法正常调用。请通过选择平台管理网络配置，在网络配置页面，进行SSL证书配置。
超时时间
超时时间用于监控API调用的时长。调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。异常情况查看，详情请参见运维监控概述。
缓存设置
支持开启或关闭。开启后需配置缓存时长。默认300（秒），支持设置60秒~1000000秒（约277.78小时）之间的正整数。
版本号
请填写API的版本号，每份配置信息会有所属版本号，以便于和上一个版本信息对比。支持输入不超过64个字符，且该API下版本号唯一。
返回类型
默认JSON。
API请求参数和返回参数配置
在配置API请求参数和返回参数过程中，您需要先确定入参和出参的来源（服务单元），再编写API SQL并解析出请求参数和返回参数，最后配置请求参数和返回参数的基本信息。
在参数配置区域，选择模式和服务单元后，系统会为您展示已选服务单元中所有的字段，便于作为编写API SQL时的参考。
参数
描述
模式
支持Basic或Dev_Prod两种模式。
Basic模式下开发时、提交及发布线上均读取生产库。
Dev-Prod模式下开发及提交读取开发库，发布线上读取生产库。
服务单元对应字段
支持复制全表字段或单个字段。异常字段用告警
图标标识，您需要查看该字段所属的服务单元是否已发布至生产环境或该服务单元是否存在。您可以根据参考示例编写API SQL。
Dataphin能解析出返回参数和请求参数的SQL脚本模板如下：
模板一：仅查询和返回服务单元中的字段。
命令格式
select <返回参数> from <服务单元名> where <请求参数>=${请求参数值}使用示例
--在服务单元A中查询当c=id_card时，返回id_card和name。 select id_card,name from 服务单元A where c=${id_card}
模板二：查询和返回服务单元包含的字段。
命令格式
select <返回参数> from <服务单元名> where <请求参数> in (${请求参数值})使用示例
--在服务单元A中查询当c %in% id_card时，返回id_card和name。 select id_card,name from 服务单元A where c in (${id_card})
模板三：字段间支持使用max、sum、min和count聚合函数，同时支持使用like进行模糊匹配。
命令格式
select max(<返回参数1>) as <别名c>,sum(<返回参数1>) as <别名b> ,min(<返回参数1>) as <别名d>,count(*) as <别名e> from <服务单元A> where <请求参数名1> like ${请求参数值1}使用示例
--在服务单元A中查询字段c %like% id_card时，返回字段a的最大值，参数名为c；返回a的最小值，参数名为d；返回a的总和，参数名为b。 select max(a) as c,sum(a) as b ,min(a) as d,count(*) as e from 服务单元A where c like ${id_card}
模板四：字段间的运算支持+（加法）、-（减法）、 * （乘法）、/（除法）、% （求余数）、 // （整除） **（幂次方），同时支持逻辑运算符and（与）和or（或）。
命令格式
select (<返回参数1>+<返回参数2>) as <别名>，(<返回参数2>+<返回参数3>) as <别名> from <服务单元A> where <字段c>=${请求参数名1} and <字段b>>=${请求参数名2} or <字段c><=${请求参数名3}使用示例
--在服务单元A中查询当字段c=id_card，或字段b>=num，且字段c<=num1时，返回a+b、b+c的参数值，参数名分别为acd、bcf。 select (a+b) as acd, (b+c) as bcf from 服务单元A where c=${id_card} aor b>=${num} or c<=${num1}
重要上述四种模板中API的请求参数和返回参数需从同一个服务单元（单物理表服务单元或多物理表服务单元）中获取，否则后续无法正常调用该API。
单击SQL试运行，在请求参数输入对话框中，输入试运行输入值，单击确认后即试跑运行SQL。
运行日志：支持查看SQL试运行实际执行的SQL语句。
试运行输入值：需要配置成绑定字段的字段值，可以在数据预览页面选择绑定字段的字段值。
单击解析参数后，Dataphin会自动解析出API SQL的入参和出参，并分别添加至请求参数和返回参数区域。请求参数和返回参数的基本信息基本一致，下表为您介绍请求参数和返回参数的基本信息及需要您配置的信息。
参数
描述
参数名
对外开放的参数。
参数类型
参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、BigDecimal、Binary。您需要选择参数名对应的绑定字段的参数类型。
服务单元字段类型与请求参数字段类型保持一致，您选择对应的字段类型即可。
示例
填写请求参数值和返回参数值的示例，便于开发者理解。输入不超过50个字符。
是否必填
选择请求参数是否为调用API时的必填参数。
选择为否：调用API的语句中没有该参数也可以执行调用API的SQL语句。
选择为是：调用API的语句中没有该参数，无法执行调用API的SQL语句。
例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回：
seclect name from tableA where id=5；：则返回对应的name字段及数据结果。seclect name from tableA;：则SQL语句执行报错。
描述
填写对请求参数和返回参数的简单描述。支持输入不超过100个字符。
单击提交，系统将校验API引用的字段在所属的服务单元中是否存在，校验通过后，完成API的生成。