脚本/MyBatis方式生成API

本文将为您介绍如何通过脚本或MyBatis方式生成API。

为了满足高阶用户的个性化查询需求，数据服务提供了自定义SQL的脚本/MyBatis取数方式，允许您自行编写API的查询SQL，并支持多表关联、复杂查询条件以及聚合函数等能力。

脚本方式：仅支持普通SQL语法。
MyBatis方式：仅专享版数据服务支持此方式，此方式下脚本支持Mybatis标签语法。Mybatis方式下参数解析格式为#{parameter}，支持if、choose、when、foreach和where等标签语法，您可以借助标签语法来灵活实现空值校验、多值遍历、动态查表、动态排序及聚合等复杂查询逻辑。

配置API基本信息

在DataArts Studio控制台首页，选择实例，单击“进入控制台”，选择对应工作空间的“数据服务”模块，进入数据服务页面。
图1 选择数据服务

在左侧导航选择服务版本（例如：专享版），进入总览页。

进入“API管理”页面，单击“新建”，填写API基本信息。

表1 API基本信息
配置	说明
API名称	支持中文、英文、数字、下划线，且只能以英文或中文开头，3-64个字符。
API目录	一个特定功能或场景的API集合，类似文件夹，指定当前API保存的位置，后续可以在指定的API目录中检索当前API。 API目录是数据服务中API的最小组织单元，也是API网关中的最小管理单元。您可单击“新建”进行新建，也可选择新建API目录已创建的API分组。
请求Path	API访问路径，例如：/getUserInfo。请求Path即完整的URL中，域名之后、查询参数之前的部分，如图2中的“/blogs/xxxx”。图2 统一资源定位符URL说明在请求Path中，可以使用大括号{}标识路径中的参数作为通配符。如“/blogs/{blog_id}”表示/blogs后可以携带任何参数，例如“/blogs/188138”和“/blogs/0”均会匹配至/blogs/{blog_id}，由此API统一处理。此外，相同域名下，不允许重复的请求路径出现。路径参数作为通配符时，名称不具备唯一性，例如“/blogs/{blog_id}”和“/blogs/{xxxx}”，会被视作相同路径。
参数协议	用于传输请求的协议，共享版支持HTTP或HTTPS协议，专享版支持HTTPS协议。推荐选择HTTPS协议，HTTP安全性欠佳，可能会存在安全风险。 HTTP属于基础的网络传输协议，无状态、无连接、简单、快速、灵活、使用明文传输，在使用上较为便捷，但是安全性欠佳。 HTTPS是在HTTP协议上进行了SSL或TLS加密校验的协议，能够有效验证身份以及保护数据完整性。相对的，访问HTTPS的API，需要配置相关的SSL证书或跳过SSL校验，否则将无法访问。
请求方式	HTTP请求方式，表示请求什么类型的操作，包含GET、POST等，遵循resultful风格。 GET：请求服务器返回指定资源，推荐使用GET请求。 POST：请求服务器新增资源或执行特殊操作，仅在注册API时使用。POST请求当前不支持body体，而是直接透传。
描述	对API进行简要描述。
标签	对API设置标签。用于标记当前API的属性，创建后可以通过标签快速检索定位API。单个API最多可设置20个标签。
审核人	审核人拥有API的审核权限。可单击“新建”，进入“审核中心 > 审核人管理”页面，新建审核人。
安全认证	创建API时，有如下三种认证方式可选。三种方式的区别在于认证方式和调用方法不同，推荐使用安全性更高的“APP认证方式”。 “APP认证方式”：API调用者通过APP认证方式调用API。Appkey & Appsecret安全级别高，推荐使用。使用APP认证时，需要通过SDK访问，其中SDK访问提供了基于Java、Go、Python、JavaScript、C#、PHP、C++、C、Android等多种语言的SDK包。各语言调用API示例请参考使用APP认证调用API章节。 “IAM认证”：需要借助IAM服务进行安全认证。IAM认证只允许华为云用户访问，安全级别中等。使用IAM认证时，需要通过调用IAM服务的获取用户Token接口获取Token，然后通过在请求消息头中添加“X-Auth-Token”参数并将所获取的Token作为参数值，再通过API调用工具或SDK方式调用已发布的API。 “无认证”：不需要认证。安全级别低，所有用户均可访问，建议仅在测试接口时使用，不推荐正式使用。若调用方为不可信任用户，则存在数据库安全风险（如数据泄露、数据库高并发访问导致宕机、SQL注入等风险）。使用无认证方式时，无需鉴权认证信息。通过API调用工具或SDK方式，直接使用已发布API域名并填写入参即可进行调用。
服务目录可见性	发布后，所选范围内的用户均可以在服务目录中看到此API。当前工作空间可见当前项目可见当前租户可见
访问日志	勾选，则此API的查询结果将会产生记录并被保留7天，可以在“运营管理 > 访问日志”处通过选择“请求日期”的方式查看对应日期的日志。
最低保留期限	API发布状态预留的最低期限，单位为小时，0表示不设限制。如果需要停用/下线/解除授权，则停用/下线/解除授权时间必须选择在发布后的最低保留期限时间之后。选择时间后，停用/下线/解除授权会通知已授权用户。如果所有已授权用户均完成审核中心通知列表消息处理，或在应用中解绑与API的绑定关系，API就会停用/下线/解除授权；否则会以待停用/待下线/待解除授权状态，等待达到停用/下线/解除授权时间，再强制停用/下线/解除授权。例如，最低保留期限设置为24小时，则此API发布后需要停用时，停用时间必须选择在发布24小时后，即发布第二天之后。如果期间内已授权用户已完成审核中心通知列表消息处理或解绑应用与API的绑定关系，则会直接停用；如果未完成，则会以待停用状态等待达到停用时间，强制停用。
入参定义	配置调用API需要输入的参数，此处定义后即为配置取数逻辑时的请求参数。入参定义主要由参数位置、参数类型、是否必填以及默认值等组成。参数位置主要包括Query、Header、Path、Body四大类，另外还支持Static静态参数。 Query是位于URL后的查询参数内容，以“?”开始，通过“&”连接多个参数。 Header参数是位于请求消息头中的参数，常用于传递当前信息。例如host，token等。 Path是位于请求路径中的请求参数，如果定义了Path参数，则需要在请求Path中也添加此参数，作为请求Path的一部分。 Body是位于请求体内的参数，一般使用json格式表示。 Static是不随API调用者的传值变化的静态参数，参数值由API授权时确定（如果授权时未配置参数值，则会使用API入参默认值作为替代）。参数类型分为数值型Number与字符型String两大类。Number参数对应数据库中int、double、long等数值数据类型，String参数对应数据库中char、vachar、text等文本数据类型。是否必填以及默认值。如果设定为必填，则API在访问时，必须传入指定参数；如果非必填，则在API访问时，未传入的参数，会使用默认值进行代替。说明：入参定义中，参数大小限制如下： Query+Path，URL最大32KB Header，最大128KB Body，最大128KB 实际配置中，需要根据所设计的调用API时请求参数情况来设置入参。例如，在用户表中根据用户ID查询用户信息时，请求Path设置为：/getUserInfo。可按照如下不同场景来配置入参： API调用时请求参数为用户id，需要返回对应id的用户信息。单击“添加”，参数名配置为id。参数位置选择Query。类型设置为Number。是否必填选择必填。默认值保持默认，无需填写。 API调用时请求参数为用户id1和用户id2，需要返回id1-id2范围内的用户信息：单击“添加”，参数名配置为id1。参数位置选择Query。类型设置为Number。是否必填选择必填。默认值保持默认，无需填写。再次单击“添加”，按照id1参数的配置信息再配置id2。

配置好API基本信息后，单击“下一步”，即可进入API取数逻辑页面。

配置取数逻辑

本例中以脚本方式说明如何配置API取数逻辑。Mybatis方式与之相比差异在于参数解析形式和支持的语法差异，在使用流程上没有区别。

如果使用Mybatis方式生成API，则需要将本章节脚本中的参数解析格式由${parameter}修改为#{parameter}形式，另外Mybatis方式支持的标签语法可在界面中单击脚本编辑处的，查看弹出的Mybatis脚本编辑提示。

“取数方式”选择“脚本方式”或“MyBatis方式”：

选择数据源、数据连接、数据库等数据信息。

数据服务仅支持部分数据源，详情请参见DataArts Studio支持的数据源。您需提前在DataArts Studio管理中心中配置好数据源，按照脚本编辑提示要求输入SQL语句。
选择分页方式，推荐使用自定义分页方式。
- 默认分页是指在创建API时输入了SQL，数据服务会自动基于SQL外层包装分页逻辑。
  例如输入的SQL脚本为：
```
SELECT * FROM userinfo WHERE id=${userid}
```
  数据服务在处理调试或者调用时，将自动在用户SQL外层包装分页逻辑，从而变成以下脚本：
```
SELECT * FROM (SELECT * FROM userinfo WHERE id=${userid}) LIMIT {limitValue} OFFSET {offsetValue}
```
  其中limitValue表示读取的数据条数，offsetValue表示跳过的数据条数（即偏移量），例如limitValue为20、offsetValue为40时，表示跳过40条数据，然后读取20条数据。一般而言，limitValue和offsetValue可作为入参，在调试或者调用API时传入值。如果未定义limitValue或offsetValue，系统将默认赋值。
- 自定义分页是指在创建API时，数据服务将不对SQL进行处理，分页逻辑需要在写SQL时由用户自定义。
  如果已知需要读取的数据条数limitValue和需要跳过的数据条数offsetValue，则分页逻辑可以写成以下脚本：
```
SELECT * FROM userinfo WHERE id=${userid} LIMIT {limitValue} OFFSET {offsetValue}
```
  而在实际使用中，更多的是根据分页后的页面大小pageSize和页码pageNum定义分页逻辑，脚本样式如下：
```
SELECT * FROM userinfo WHERE id=${userid} LIMIT {pageSize} OFFSET {pageSize*(pageNum-1)}
```
  值得注意的是，不同的数据源具有不同的语法风格，分页脚本应按照数据源语法要求调整。例如：
  - DLI数据源不支持“LIMIT {limitValue} OFFSET {offsetValue}”的写法，仅支持“LIMIT {limitValue}” 。
  - HETU数据源分页需要反转，不支持“LIMIT {limitValue} OFFSET {offsetValue}”的写法，仅支持“OFFSET {offsetValue} LIMIT {limitValue}”。
编写API查询SQL。
在脚本编辑页面，单击脚本编辑处的，按照脚本编辑提示开发SQL查询语句。单击可将入参添加为SQL语句的API请求参数。

例如，需要在用户表中根据用户ID查询用户信息时，取值脚本可写为如下脚本。其中，“id”为userinfo表中的字段，“userid”为API中定义的入参。
```
SELECT * FROM userinfo WHERE id=${userid}
```
如果分页方式为自定义分页，页面大小pageSize为10、页码pageNum为2时，按照LIMIT {pageSize} OFFSET {pageSize*(pageNum-1)}转换方法，脚本可写为：
```
SELECT * FROM userinfo WHERE id=${userid} LIMIT 10 OFFSET 10
```
图3 编写API查询SQL

脚本编辑完成后，单击脚本编辑窗口下方的“测试SQL”，填写入参值，执行验证是否能返回预期结果。如果测试失败，可在“预览SQL”页签下查看实际运行的SQL语句是否符合预期，或者通过“日志”页签查看报错信息。

图4 测试SQL
- SELECT查询的字段即为API返回参数，支持通过AS返回别名。
- WHERE条件中的参数为API请求参数，脚本方式下参数格式为${参数名}，MyBatis方式下参数格式为#{参数名}。
- 专享版数据服务支持返回总条数，开启后可返回取值脚本执行结果数据的总条数。
- 如果单个参数需要传多个值时，写法如下：
  
  字符串：'a','b','c'
  
  数值：1,2
  
  字段：a,b,c
添加排序参数。
在排序参数列表中，单击“新建”可设置排序字段。
- 字段名称对外不可见，是所选的数据表中的字段，是API调用时实际访问的内容。在API查询SQL语句已编写完成且测试通过的前提下，可在“字段名称”输入框中选择排序字段。
- 变量可自定义，用于与字段名称关联。在“变量”输入框中输入参数名称（一般填写为参数名称即可），系统会自动修改为变量形式。
- 是否可选决定了调用API时此排序参数是否必选，勾选则表示可以不使用此参数。
- 排序方式分为升序、降序以及自定义，表示了当前参数允许使用的排序形式。如果设置为升序或降序，在API测试或调用时，如果排序参数描述pre_order_by的值与此处设置不符，则会导致调用失败。
排序字段需要添加到SQL脚本中才能生效，单击将排序参数添加到SQL语句，使用ORDER BY排序。

例如，需要在用户表中根据用户ID查询用户信息，通过age和kk两个字段排序，页面大小pageSize为10、页码pageNum为2时，脚本样例如下。
```
SELECT * FROM userinfo WHERE id=${userid} order by (${age},${kk}) LIMIT 10 OFFSET 10
```
图5 添加排序参数

脚本编辑完成后，单击脚本编辑窗口下方的“测试SQL”，填写入参值和pre_order_by参数值，执行验证是否能返回预期结果。其中pre_order_by参数值已由系统根据排序参数信息给出默认值，默认升序排序。一般而言，排序参数描述pre_order_by的值填写形式为“排序参数参数名:ASC”或“排序参数参数名:DESC”，其中ASC表示升序，DESC表示降序，多个排序参数描述以“英文分号”进行分隔。

如果测试失败，可在“预览SQL”页签下查看实际运行的SQL语句是否符合预期，或者通过“日志”页签查看报错信息。
- pre_order_by是非必填参数，默认取必选排序字段升序作为排序的依据。
- 当配置pre_order_by参数值时，需严格按照排序参数列表中配置的排序参数顺序、可选属性和排序方式进行配置，否则会调用失败。
图6 测试SQL
单击“下一步”，进行API测试页面。

测试API

填写入参取值。
如果单个参数需要传多个值时，写法如下：
- 字符串：'a','b','c'
- 数值：1,2
- 字段：a,b,c
图7 填写入参取值
（可选）调整排序参数描述pre_order_by的值。
系统根据排序参数信息已给出默认值，默认升序排序。一般而言，排序参数描述pre_order_by的值填写形式为“排序参数参数名:ASC”或“排序参数参数名:DESC”，其中ASC表示升序，DESC表示降序，多个排序参数描述以“英文分号”进行分隔。
- pre_order_by是非必填参数，默认取必选排序字段升序作为排序的依据。
- 当配置pre_order_by参数值时，需严格按照排序参数列表中配置的排序参数顺序、可选属性和排序方式进行配置，否则会调用失败。
图8 调整排序参数描述pre_order_by的值
（可选）查看分页参数值。
采用默认分页方式时，可以查看分页参数情况，其中pageSize表示分页后的页面大小，pageNum表示页码。默认按100的大小分页，返回第1页数据。

图9 查看分页参数值
完成API参数的配置并保存后，单击左下角的“开始测试”，可进入API测试环节。
填写参数值，单击“开始测试”，即可在线发送API请求，在右侧可以看到API请求详情及返回内容。
- 测试过程中，当数据服务API查询返回值超过默认30秒无结果时，会报超时错误。
- 如果测试失败，请仔细查看错误提示并做相应的修改重新测试。