通过SQL直接从数据源创建API查询数据。本文为您介绍如何使用直连数据源模式生成API。
使用限制
需购买行级权限功能后才可使用行级权限功能。
在API调用时，若数据源本身支持分页，且AP操作方式为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限制返回查询的结果条数，则不支持使用分页查询。
支持通过SQL直连数据源创建API、关联行级权限以及分页查询的数据源，请参见数据服务支持的数据源。
权限说明
支持服务的项目管理员和开发用户可以生成API。
异步调用流程说明
下方流程图为您介绍使用异步调用进行数据查询的整个生命周期管理，包括获取任务的ID、状态、结果、关闭查询任务各个流程之间的流转，详情如下：
异步调用查询流程：
GetJobStatus：获取API调用的执行状态。
GetJobResult：返回请求的结果，仅当Job的状态为Success时可调用成功，否则则调用失败，仅支持顺序获取查询结果。
GetJobExecutionLog：获取API执行的日志。
CloseJob：完成该请求，释放所有Job占用的资源，包括数据库连接、缓存等。Failed的状态也调用该接口释放资源。
异步调用取消查询流程：
CancelJob：取消查询请求。若有执行中的数据库查询请求，将同步取消查询；若未开始或已经完成数据库的查询，则不可取消对数据库的查询。
步骤一：选择生成API的方式
在Dataphin首页的顶部菜单栏，选择服务 > API开发。
在左上角选择项目，单击左侧导航栏API服务，然后在API页面，单击+新建API。
在新建API对话框中，选择直连数据源-SQL模式。
步骤二：配置API参数信息
在新建API页面，配置API基本信息和参数配置。
API基本信息配置
参数
描述
API名称
填写API的名称。命名规则如下：
支持中文、字母、数字或下划线（_）。
长度为4~100个字符。
必须以中文、英文开头。
全局唯一。
操作类型
GET：请求服务器获取指定的某个资源。
LIST：请求服务器获取某一部分的资源。
数据更新频率
定义API返回数据的更新频率，便于调用方了解数据的时效性，支持的更新频率为每天、每小时、每分钟以及自定义，若选择自定义，支持输入不超过128个字符。
API分组
选择API需要归属的分组。如需创建，请参见创建服务分组。
描述
填写对API的简单描述。不超过128个字符。
协议
数据生成API的接口协议，支持HTTP、HTTPS协议。
HTTP：即超文本传输协议HTTP（HyperText Transfer Protocol），是应用最为广泛的网络协议。
HTTPS：若网关配置为阿里公有云API网关（专享实例或共享实例）时，支持选中HTTPS协议，请确保独立域名的SSL证书有效，避免无法正常调用。请通过选择平台管理网络配置，在网络配置页面，进行SSL证书配置。
调用模式
用于客户端和服务器之间的通信，以获取或处理数据。支持选择同步调用和异步调用，默认为同步调用。
同步调用：客户端发送请求后，必须等服务器返回结果后才能继续执行其他请求，针对复杂查询语句，响应时间较长且在等待过程中会占用服务器连接数，造成服务器压力。适用于实时性要求高、处理时间短的场景。
异步调用：客户端发送请求后，无需等待服务器响应，可继续执行其他请求，服务器处理完成后再通知客户端，在批量获取数据时，可降低数据库查询结果的重复率，用数据服务API进行数据获取。适用于处理时间长、实时性要求不高的场景，如批量处理等。
执行超时时间
当调用模式为异步调用时支持该配置项。用于监控SQL执行的时长。默认为60秒，支持设置的时间范围为1到7200秒（2小时）的正整数。
超时时间
用于监控API调用的最大时长。当调用模式为同步调用时，默认为3秒，支持设置的时间范围为3到60秒的正整数；当调用模式为异步调用时，默认为600秒，支持设置的时间范围为3到7200秒（2小时）的正整数。
调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。关于异常情况的查看，详情请参见查看及管理运维监控API。
最大返回条数
当操作类型为LIST时支持该配置项。API最大的返回条数为10000条。支持输入1~10000之间的正整数。
缓存设置
当调用模式为同步调用时支持该配置项。支持开启或关闭。开启后需配置缓存时长。默认300秒，支持设置60秒~1000000秒（约277.78小时）之间的正整数。
版本号
请填写API的版本号，每份配置信息会有所属版本号，以便于和上个版本信息对比。该API下版本号唯一。命名规则如下：
不超过64个字符。
支持输入大小写英文字母、数字、下划线（_）、半角句号（.）、短划线（-）。
返回类型
默认JSON。
API请求参数和返回参数配置
在配置API请求参数和返回参数的过程中，您需要先确定输入参数和输出参数的来源表，再编写API SQL并解析出请求参数和返回参数，最后配置请求参数和返回参数的基本信息。
在API参数配置区域，确定输入参数和输出参数的来源表，并根据参考示例编写API SQL脚本。
参数
描述
模式
选择数据来源环境，支持Basic或Dev-Prod。
Basic模式下开发时、提交及发布线上均读取生产库。
Dev-Prod模式下开发及提交读取开发库，发布线上读取生产库。
数据源
根据数据源类型选择数据源，支持异步调用模式的数据源，请参见数据服务支持的数据源。
说明MySQL支持MySQL5.1.43、MySQL5.6/5.7和MySQL8版本。
查询加速
当数据源为MaxCompute时可配置此参数。开启后，将使用MaxCompute MCQA加速查询，可提升任务的查询速度，将执行时间缩短至秒级。MCQA每一个租户下，作业数量与并发数有限制，可能会导致加速失败，执行报错解决方式请参见查询加速（MCQA）。
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中定义的排序设置。
说明当数据源为HBase0.9.4/1.1.x/2.x、TDengine、SAP HANA时，不支持配置排序优先级。
API SQL脚本编辑
API SQL脚本帮助您在编辑脚本时需遵循的SQL编辑规范，详情请参见API SQL脚本编辑说明。
参考示例
Dataphin能解析出返回参数和请求参数的SQL脚本模板如下：
Get/List基础SQL示例：
-- 示例一：根据条件查询单条记录；id非必填且未传参时，自动忽略该条件 SELECT id,name FROM tablename WHERE id = ${id} -- 示例二：In条件批量查询，id_list参数按“,”分隔 SELECT id,name FROM tablename WHERE id in (${id_list}) -- 示例三：使用Like模糊匹配，聚合函数使用语义化别名 SELECT MAX(a) AS max_a, SUM(a) AS sum_a, MIN(a) AS min_a, COUNT(*) AS count_all FROM tableName WHERE name LIKE ${name_pattern} -- 示例四：带标别名的查询 SELECT t.name as name FROM tablename t WHERE id=${id_card} -- 示例五：表达式计算+多条件查询 SELECT (a+b) as sum_ab, (b+c) as sum_bc FROM tablename WHERE id=${id_card} and b>=${num} and c<=${num1} -- 示例六：分组 + CASE统计 SELECT category, SUM(CASE WHEN name LIKE ${name_pattern} THEN 1 ELSE 0 END) AS proj_score FROM table WHERE id=${id} GROUP BY categoryGet/List高级SQL示例：
-- 目前支持的Mybatis标签类型包括：if、choose、when、otherwise、trim、foreach和where。 -- 标签内的SQL参数支持$或者#符号标识，具体示例如下 -- 示例1：使用 <where> + <if> 实现条件过滤 SELECT id, name, age FROM tableName <where> <if test="name != null and name != ''"> AND age > #{age} </if> <if test="name == null"> AND age < #{age} </if> </where> -- 示例2：使用 <choose> 实现互斥条件 SELECT id, name, age FROM tableName <where> <choose> <when test="name != null and name != ''"> AND age > #{age} </when> <when test="age != null"> AND age < #{maxAge} </when> <otherwise> AND status = 'active' </otherwise> </choose> </where> -- 示例3：使用 <foreach> 实现 IN 查询 SELECT id, name FROM tableName <where> id IN <foreach item="item" index="index" collection="idList" open="(" separator="," close=")"> #{item} </foreach> </where> -- 示例4：使用 <trim> 自定义前缀（替代 <where>） SELECT id, name, age FROM ${tableName} <trim prefix="WHERE" prefixOverrides="AND | OR "> <if test="name != null"> AND name LIKE #{namePattern} </if> <if test="minAge != null"> AND age >= #{minAge} </if> <if test="status != null"> AND status = #{status} </if> </trim> -- 示例5：动态字段查询（var_cols） SELECT category,${var_cols_metrics} FROM tableName WHERE id = ${id} GROUP BY category
格式化
支持对SQL语句格式化处理展示，仅支持对基础SQL。
字段参考
在字段参考面板中，为您展示已选择数据表中的所有字段。
复制：支持复制表名称、全表字段或单个字段。
快捷插入：单击快捷插入，系统根据操作类型插入SQL脚本语句，脚本语句详情请参见API SQL脚本快捷导入SQL。
异常字段用告警
图标标识，您需要查看该字段所属的服务单元是否已发布至生产环境或该服务单元是否存在。
单击解析参数，Dataphin会自动解析出API SQL的入参和出参并分别添加至请求参数和返回参数区域。若SQL模式选择高级SQL，支持勾选保留手动配置，当修改SQL脚本需再次解析参数时，系统将保留已填写的参数信息；如需删除无用参数信息，请手动删除。适用于复杂的SQL语句参数无法解析，需手动填写参数信息的场景。
说明若SQL模式为高级SQL，以
var_cols开头的参数为动态参数，支持通过传参的方式动态指定SQL语句查询返回的字段，可将所有支持的字段添加到返回参数中。调用API时，在动态参数中传入需要查询的字段，若未传入，则字段在返回参数中为Null值。若SQL模式为基础SQL，当参数为非必填且无输入参数时，系统将自动改写SQL，忽略对应的筛选条件；若参数值类型为between，则该参数值为必填。
高级SQL语句较为复杂，SQL编译解析的参数不一定完整且正确。因此，您可根据SQL语句对解析结果进行删除参数、新增请求参数和新增返回参数操作。
参数
描述
请求参数
参数名称
必填，显示对外开放的参数名，系统从SQL中解析，不支持修改。
参数类型
必填，需选择参数名对应绑定字段的参数类型，支持选择DOUBLE、FLOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY。
如果逻辑表的字段类型不在待选参数类型范围内，推荐选择String。
参数值类型
必填，选择参数值的类型，支持单值、多值。
单值：根据参数类型传入，传入参数将被解析为单一值，适用的操作符为
=、like、>=、<=、>、<、!=、between。多值：传入参数将被解析为多个值，多个值之间使用半角逗号（,）分隔，适用的操作符为
in。
参数处理
当操作符为LIKE时需配置。若未选择参数处理，需在入参时手动输入通配符进行匹配。支持选择模糊匹配（%keyword%）、右匹配（%keyword）、左匹配（keyword%）。
示例
填写请求参数值和返回参数值的示例，便于开发者理解。支持输入不超过1000个字符。
描述
填写对请求参数和返回参数的简单描述。支持输入不超过1000个字符。
是否必填
选择请求参数是否为调用API时的必填参数。
选择否：调用API的语句中没有该参数也可以执行调用API的SQL语句。
选择是：调用API的语句中没有该参数，将无法执行调用API的SQL语句。
例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回：
返回对应的name字段及数据：
select name from tableA where id=5;。SQL语句执行报错：
select name from tableA;。
操作
支持批量修改请求参数的参数类型、参数值类型、参数处理（仅操作符为LIKE时支持操作）、是否必填及批量删除参数（仅高级SQL模式支持操作）。
当选择高级SQL模式，支持单击新增请求参数，手动添加参数。
返回参数
参数名称
必填，显示对外开放的参数名，系统从SQL中解析，不支持修改。
参数类型
必填，需选择参数名对应绑定字段的参数类型，支持选择DOUBLE、FLOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY。
如果逻辑表的字段类型不在待选参数类型范围内，推荐选择String。
示例
填写请求参数值和返回参数值的示例，便于开发者理解。支持输入不超过1000个字符。
描述
填写对请求参数和返回参数的简单描述。支持输入不超过1000个字符。
操作
支持批量修改返回参数的参数类型及批量删除参数（仅高级SQL模式支持操作）。
当选择高级SQL模式时，支持单击新增返回参数按钮，手动添加参数。
单击SQL试运行，在请求参数输入对话框中，选择参数类型、参数值类型、参数处理和试运行输入值，然后单击确认。
运行日志：支持查看SQL试运行时实际执行的SQL语句。
试运行输入值：需要配置绑定字段的字段值，可以在数据预览面板查看绑定字段的字段值。
批量操作：支持批量修改请求参数的参数类型、参数值类型、参数处理（仅操作符为LIKE时支持操作）及批量删除参数（仅高级SQL模式支持操作）。
单击填充参数示例值，系统会将最近一次试运行成功的示例值填充至请求参数和返回参数。如果示例有值，则不进行覆盖，支持修改。
仅当SQL模式为高级SQL且已有试运行结果记录时，支持单击填充返回参数/从试运行结果导入，在填充参数对话框中，配置参数的添加方式及同名参数处理方式。
添加方式：导入参数时的添加策略，支持追加新参数和全量替换已有参数。
追加新参数：保留返回参数列表中已有参数并追加本次试运行结果中的解析的参数，根据参数名称唯一性，添加列表中不同名参数。
全量替换已有参数：将返回参数列表中已有参数全部替换为试运行结果中解析的参数。
同名参数处理：当添加方式为追加新参数时支持配置。针对添加的参数名称重复时处理策略，支持保持不变或替换。
保持不变：保留原有参数信息不变更。
替换：若试运行结果的参数名称和列表中的参数名称重复，以本次试运行结果中解析的参数类型和示例值为准更新列表中的信息；若试运行结果的值为空，则不进行替换。
若选中同步填充请求参数的示例值，将根据填充参数的配置同步替换请求参数列表中的示例值。
仅当SQL模式为基础SQL时支持展示关联行级权限。单击解析参数按钮，系统自动为您解析数据源表所关联的行级权限信息，包括行级权限名称、描述说明、控制字段、数据源环境、关联表、关联字段。同时，您可以执行如下操作。
开启或关闭行级权限：控制行级权限的生效状态以及在查看API、版本对比、调试/测试API时是否可见行级权限列表信息。
去创建行级权限：操作人需具有行级权限创建权限。单击跳转至管理中心 > 权限管理的行级权限创建页面，新建行级权限。
说明调用该API所返回的数据范围受到行级权限的管控，行级权限不一致时，数据返回结果会存在差异。
当模式为Basic时，展示生产环境关联的数据源表行级权限；模式为Dev-Prod时，展示开发环境和生产环境关联的数据源表行级权限。
单击提交，系统将校验API引用的字段在所属的数据源中是否存在，校验通过后，完成API的生成。