通过SQL直接从数据源创建API增删改数据。本文为您介绍如何使用直连数据源模式生成API。
使用限制
需购买数据增强操作功能后才能使用操作类型的增删改功能。
支持通过SQL直连数据源创建API以及支持增删改API的数据源，请参见数据服务支持的数据源。
Create、Update、Delete操作类API将占用较多计算资源，单条数据量请求占用2个并发，批量数据量请求占用
2*并行度个并发，建议结合业务场景，合理使用资源。当SQL模式为高级SQL且数据量为批量时，系统无法批量执行操作，仅可支持单独执行每条数据操作，会造成系统性能变差，建议Create、Update、Delete操作类API避免使用高级SQL模式。
若SQL中包含
in条件参数，则每条数据会单独执行，性能较差，请尽量避免使用in条件参数。
权限说明
支持服务的项目管理员和开发用户可以生成API。
当前用户需具有数据源的同步写或执行权限才可创建Create、Update、Delete操作类型的API。
步骤一：选择生成API的方式
在Dataphin首页的顶部菜单栏，选择服务 > API开发。
在左上角选择项目，单击左侧导航栏API服务，然后在API页面，单击新建API。
在新建API对话框中，选择直连数据源-SQL模式。
步骤二：配置API参数信息
在新建API页面，配置API基本信息和参数配置。
API基本信息配置
参数
描述
API名称
填写API的名称。命名规则如下：
支持中文、字母、数字或下划线（_）。
长度为4~100个字符。
必须以中文、英文开头。
全局唯一。
操作类型
Create：创建对象，支持单条或批量创建。
Update：更新对象，可支持单条或批量更新。
Delete：删除对象，可支持单条或批量删除。
API分组
选择API需要归属的分组。如需创建，请参见创建服务分组。
描述
填写对API的简单描述。不超过128个字符。
协议
数据生成API的接口协议，支持HTTP、HTTPS协议。
HTTP：即超文本传输协议HTTP（HyperText Transfer Protocol），是应用最为广泛的网络协议。
HTTPS：若网关配置为阿里公有云API网关（专享实例或共享实例）时，支持选中HTTPS协议，请确保独立域名的SSL证书有效，避免无法正常调用。请通过选择平台管理网络配置，在网络配置页面，进行SSL证书配置。
数据量
选择数据的处理量，支持单条或批量处理数据。
调用模式
用于客户端和服务器之间的通信，以获取或处理数据。仅支持同步调用。
同步调用：客户端发送请求后，必须等服务器返回结果后才能继续执行其他请求，针对复杂查询语句，响应时间较长且在等待过程中会占用服务器连接数，造成服务器压力。适用于实时性要求高、处理时间短的场景。
最大输入条数
当数据量为批量时支持配置。API的最大输入条数，默认为1000条，支持输入1~1000000（百万）之间的正整数。系统根据网关配置支持不同容量的请求包体：
当网关配置为阿里公共云API网关-专享实例时，请求包体不超过8MB。
当网关配置为阿里公共云API网关-共享实例/内置网关时，请求包体不超过32MB。
超时时间
用于监控API调用的最大时长。当调用模式为同步调用时，默认为3秒，支持设置的时间范围为3到60秒的正整数；当调用模式为异步调用时，默认为600秒，支持设置的时间范围为3到7200秒（2小时）的正整数。
调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。关于异常情况的查看，详情请参见查看及管理运维监控API。
错误处理
当数据量为批量时支持配置。针对SQL运行错误时处理方式，支持允许部分成功和全部成功才可成功。仅当数据源支持事务，才能选择全部成功才可成功配置。
版本号
请填写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版本。
SQL模式
支持选择基础SQL和高级SQL两种模式。
事务处理模式
当数据源支持事务时，支持配置。执行数据时，事务的处理模式。
当数据量为单条时，仅支持选择无事务，即不使用事务处理。
当数据量为批量时，支持不分批和分批处理。
不分批：整批数据在一个事务中处理。
分批处理：仅错误处理为允许部分成功时支持配置，按批次分割事务处理。
单批处理数据量
当事务处理模式为分批处理时支持配置。单次运行数据的数据量，系统将多次调用的SQL合并为一个批次，批次内顺序保持一致，但是批次间无法保序。默认为1000条数据，支持输入大于1的整数。
系统根据并行度将总批数分配到不同任务，批数计算逻辑为：
总数据量/单批处理数据量。并行度
当事务处理模式为分批处理时支持配置。用于控制同时运行SQL的任务批次数，默认为1个，支持输入1~5个。
API SQL脚本编辑
API SQL脚本帮助您在编辑脚本时需遵循的SQL编辑规范，详情请参见API SQL脚本编辑说明。
参考示例
Dataphin能解析出返回参数和请求参数的SQL脚本模板如下：
Create基础/高级SQL示例：
-- 示例1：插入数据行 INSERT INTO customers ( customer_id, first_name, last_name, ) VALUES ( ${customerId}, ${firstName}, ${lastName}, ) -- 示例2：插入数据行, customer_id 是自增字段 INSERT INTO customers ( first_name, last_name, ) VALUES ( ${firstName}, ${lastName}, ) RETURNING customer_id -- 示例3：Upsert数据 <choose> <!-- 场景1：如果记录已存在，则更新 --> <when test="exists == true or forceUpdate == true"> UPDATE customers SET first_name = #{firstName}, last_name = #{lastName}, WHERE customer_id = ${customerId} </when> <!-- 场景2：如果记录不存在，则插入 --> <otherwise> INSERT INTO customers ( customer_id, first_name, last_name, ) VALUES ( #{customerId}, #{firstName}, #{lastName}, ) </otherwise> </choose>Update基础/高级SQL示例：
-- 示例：更新数据 UPDATE customers SET first_name = ${firstName}, last_name = ${lastName}, WHERE customer_id = ${customerId}Delete基础/高级SQL示例：
-- 示例：删除数据 DELETE FROM customers WHERE customer_id = ${customerId}
格式化
支持对SQL语句格式化处理展示，仅支持基础SQL。
字段参考
在字段参考面板中，为您展示已选择数据表中的所有字段。
复制：支持复制表名称、全表字段或单个字段。
快捷插入：单击快捷插入，系统根据操作类型插入SQL脚本语句，脚本语句详情请参见API SQL脚本快捷导入SQL。
异常字段用告警
图标标识，您需要查看该字段所属的服务单元是否已发布至生产环境或该服务单元是否存在。
单击解析参数，系统会自动解析出API SQL的入参和出参并分别添加至请求参数和返回参数区域。若SQL模式选择高级SQL，支持勾选保留手动配置，当修改SQL脚本需再次解析参数时，系统将保留已填写的参数信息；如需删除无用参数信息，请手动删除。适用于复杂的SQL语句参数无法解析，需手动填写参数信息的场景。
说明若SQL模式为高级SQL，以
var_cols开头的参数为动态参数，支持通过传参的方式动态指定SQL语句查询返回的字段，可将所有支持的字段添加到返回参数中。调用API时，在动态参数中传入需要查询的字段，若未传入，则字段在返回参数中为Null值。若SQL模式为基础SQL，当参数为非必填且无输入参数时，系统将自动改写SQL，忽略对应的筛选条件；若参数值类型为between，则该参数值为必填。
高级SQL语句较为复杂，SQL编译解析的参数不一定完整且正确。因此，您可根据SQL语句对解析结果进行删除参数、新增请求参数和新增返回参数操作。
系统根据SQL操作类型校验不同的权限：
SELECT：需具有数据源同步读或执行权限。
INSERT、UPDATE、DELETE：需具有数据源同步写或执行权限。
参数
描述
请求参数
参数名称
必填，显示对外开放的参数名，系统从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，都为必填参数，传参不同会有不同的结果：
同时输入ID和name，正常执行SQL：
update tableA set name='Tom' where ID=5;。未输入ID或name时，API请求报错。
默认值
当是否必填为否时支持配置。若参数值未指定，则使用默认值（未设置时为NULL），支持输入不超过1000个字符。
操作
支持批量修改请求参数的参数类型、参数值类型、参数处理（仅操作符为LIKE时支持操作）、是否必填及批量删除参数（仅高级SQL模式支持操作）。
当选择高级SQL模式，支持单击新增请求参数，手动添加参数。
返回参数
操作成功
必填，当数据量为批量时支持配置。针对操作成功的数据，设置是否返回结果数据以及返回结果数据格式。默认为否，无需配置返回参数；选择是，可单击新增返回参数按钮，手动添加操作成功的数据返回参数。
若为高级SQL模式，还可根据SQL试运行结果导入返回字段作为返回参数。
操作失败
必填，当数据量为批量时支持配置。针对操作失败的数据，设置是否返回结果数据以及返回结果数据格式。默认为是，可单击新增返回参数按钮，手动添加操作失败的数据返回参数；若为否，无需配置返回参数。
若为高级SQL模式，还可根据SQL试运行结果导入返回字段作为返回参数。
参数名称
必填，显示对外开放的参数名。
当数据量为单条时，系统从API SQL脚本中解析字段作为请求参数和返回参数，请求参数不支持新增和删除，返回参数支持新增和删除。
当数据量为批量且SQL模式为基础SQL时，系统从API SQL脚本中解析字段作为请求参数和返回参数，请求参数不支持新增和删除，返回参数支持新增和删除。
当数据量为批量且SQL模式为高级SQL时，系统从API SQL脚本中解析字段作为请求参数和返回参数，请求参数和返回参数均支持新增和删除。
数据来源
用于标识参数的数据来源。
当SQL模式为基础SQL时，系统解析API SQL脚本中的返回参数，数据来源不可修改。
当SQL模式为高级SQL时，系统解析API 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且已有试运行结果记录时，支持单击填充返回参数/从试运行结果导入，在填充参数对话框中，配置参数的添加方式及同名参数处理方式。
添加方式：导入参数时的添加策略，支持追加新参数和全量替换已有参数。
追加新参数：保留返回参数列表中已有参数并追加本次试运行结果中的解析的参数，根据参数名称唯一性，添加列表中不同名参数。
全量替换已有参数：将返回参数列表中已有参数全部替换为试运行结果中解析的参数。
同名参数处理：当添加方式为追加新参数时支持配置。针对添加的参数名称重复时处理策略，支持保持不变或替换。
保持不变：保留原有参数信息不变更。
替换：若试运行结果的参数名称和列表中的参数名称重复，以本次试运行结果中解析的参数类型和示例值为准更新列表中的信息；若试运行结果的值为空，则不进行替换。
若选中同步填充请求参数的示例值，将根据填充参数的配置同步替换请求参数列表中的示例值。
单击提交，系统将校验API引用的字段在所属的数据源中是否存在，校验通过后，完成API的生成。