通过数据源生成API（API网关）

前提条件

• 已在工作空间管理 > 数据源管理页面配置数据源。详情请参见配置数据源。

• 数据服务需提前准备资源组，生产环境建议使用Serverless资源组，详情请参见资源组与网络连通。

进入数据服务页面

登录DataWorks控制台，切换至目标地域后，单击左侧导航栏的数据分析与服务 > 数据服务，在下拉框中选择对应工作空间后单击进入数据服务。

步骤一：开通API网关并创建API分组

在创建业务流程之前，您需要先在API网关控制台完成以下准备工作。

1. 登录API网关控制台，开通API网关服务。

2. 在API网关控制台中，新建一个API分组。API分组是指针对某一个功能或场景的API集合，也是API网关对API的最小管理单元。

   重要

   API网关的地域必须与DataWorks工作空间地域一致。

步骤二：创建业务流程

数据服务基于业务流程实现以业务为单元的API开发，每个业务流程需绑定一个API分组。在生成API前，您需要先创建业务流程。

1. 在服务开发页面，单击图标，选择新建业务流程。

2. 在新建业务流程对话框中，配置各项参数。

   参数	描述
   业务名称	在所属工作空间中必须唯一。支持汉字、英文字母、数字、下划线（_），以英文字母或汉字开头，4~50个字符。
   API分组	选择您在步骤一中创建的API分组。如果需要新建分组，请进入API网关创建。 重要 业务流程绑定API分组后，不支持修改。请谨慎选择。
   业务描述	对业务流程进行描述，不能超过180个字符。

3. 单击确定。新建完成后，您可以在业务流程列表中查看。

步骤三：选择API创建模式

数据服务支持通过向导模式和脚本模式两种方式生成API。两种模式共享相同的API基础配置流程，但在查询逻辑的构建方式上有本质区别。

步骤四：生成API

1. 在服务开发页面，鼠标悬停至图标，单击新建API > 生成API。

   您也可以打开相应的业务流程，右键单击API，选择新建API > 生成API。

2. 在生成API对话框中，配置各项参数。

   参数	描述
   API 模式	选择向导模式或脚本模式。选择脚本模式时，还需进一步选择SQL 模式（基础SQL或高级SQL）。 基础SQL：通过基础SQL语法编写查询逻辑。 高级SQL：通过支持MyBatis标签的SQL语法编写查询逻辑。支持的标签类型包括：if、choose、when、otherwise、trim、foreach和where。
   API名称	支持中文、英文、数字、下划线（_），且只能以英文或中文开头，4~50个字符。
   APIPath	API存放的路径，即相对于服务host的请求路径，例如/user。支持英文、数字、下划线（_）和连字符（-），以（/）开头，不超过200个字符。
   协议	支持HTTP和HTTPS。 如果您需要通过HTTPS协议调用API，请您发布API至网关后，在API网关控制台绑定独立域名，并上传SSL证书。详情请参见支持HTTPS。
   请求方式	支持GET和POST。 说明 选择GET时，请求参数位置仅支持QUERY。选择POST时，支持QUERY和Body。
   返回类型	仅支持JSON返回类型。
   可见范围	工作空间：该API对本工作空间内的所有成员可见。 私有：该API仅对API的负责人可见，且暂不支持授权。
   标签	从标签列表中选择，最多5个标签，每个不超过20个字符。详情请参见创建及管理API标签。
   描述	对API进行简要描述，不超过2000个字符。
   目标文件夹	选择已创建的业务流程作为API存放目录。默认格式为："业务流程/业务流程名称/API"。

3. 单击确定，进入API编辑页面。

步骤五：配置API

步骤六：保存并提交

单击工具栏中的图标，保存API后，所选资源组将在测试时生效。

附录：向导模式转脚本模式

您可以将向导模式生成的API转换为脚本模式：

1. 在服务开发页面，展开目标API所在的业务流程 > API。

2. 双击相应的API名称，打开该API的编辑页面。

3. 单击工具栏中的图标。

4. 在提示对话框中，单击确定。

   警告

   • 仅支持将向导模式转换为脚本模式。

   • 转换后无法回退至向导模式，请谨慎操作。

附录：高级SQL（MyBatis语法）示例

以下示例展示脚本模式下使用高级SQL编写复杂查询逻辑的常见场景。使用时请将表名、字段和查询条件替换为您的实际内容。

select col01,col02
from table_name
<choose>
    <when test='var == 1'>
    order by col01
    </when>
    <when test='var == 2'>
    order by col02
    </when>
    <when test='var == 3'>
    order by col01,col02
    </when>
    <when test='var == 4'>
    order by col02,col01
    </when>
</choose>

select col01
from
<choose>
 <when test='var == 1'>
 table_name01
 </when>
 <when test='var == 2'>
 table_name02
 </when>
</choose>

SELECT area_id, area, amount
FROM table_name
<where>
	<if test='list!=null'>
	area in
		<foreach collection="list" open="(" close=")" separator="," item="area">
		#{area}
		</foreach>
	</if>
</where>

附录：最佳实践 — 选填参数设置

在实际业务中，经常需要部分请求参数为可选——调用方可自行决定是否传入某个参数值，未传值时该参数不参与查询条件。以下以ods_user_info_d表为例，将uid设为必填参数，gender设为选填参数。

SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
<where>
    <if test='gender!=null'>
    gender = ${gender}
    </if>
    and uid = ${uid}
</where>