通过脚本模式生成API

1. 选择表

双击打开API的编辑页面，在选择表区域，配置数据源类型和数据源名称、数据源环境等参数。

不同数据源类型的配置参数略有不同，具体配置参数以界面为准。

2. 编写查询SQL

在编写查询SQL区域，输入查询SQL语句。

• 如果您选择的是基础SQL模式，则仅支持普通SQL语法。

  说明

  SELECT查询的字段为API的返回参数，WHERE条件处的参数为API的请求参数，请使用${}标识请求参数。

  输入SQL语句时，您需要遵循以下规则：

  • 支持同一数据源下的单表查询、多表关联查询和嵌套查询。

  • 不支持以下语句：

    • 不支持多条SQL语句。

    • 不支持写入注释。

    • 不支持INSERT、UPDATE和DELETE等非SELECT语法。

    • 不支持SELECT \*，必须明确指定查询的列。

    • 不支持将${param}放在引号中。例如'${id}'、'abc${xyz}123'。如果您有相关需求，请通过concat('abc', ${xyz}, '123’)实现。

    • 不支持设置参数为可选。

  • 如果SELECT查询列的列名带有表名前缀（例如t.name），则必须取别名作为返回参数名（例如t.name as name）。

  • 如果使用聚合函数（min、max、sum和count等），必须取别名作为返回参数名。例如sum(num) as total\_num。

  • SQL中的${param}统一作为请求参数进行替换，包含字符串中的${param}。当${param}前包含转义符（\）时，作为普通字符串处理。

• 如果您选择的是高级SQL模式，则支持MyBatis标签语法。

  高级SQL支持的Mybatis标签类型包括if、choose、when、otherwise、trim、foreach和where，您可以借助标签语法来灵活实现空值校验、多值遍历、动态查表、动态排序及聚合等复杂查询逻辑，常见场景的代码示例请参见脚本模式：高级SQL（Mybatis语法）示例。

  如果在高级SQL中编辑Mybatis标签时包含了特殊字符，则需要将特殊字符进行转义处理。常见的转义处理可参考下表：

  特殊字符	转义字符	含义
  >	>	大于
  >=	>=	大于等于
  <	&lt;	小于
  <=	&lt;=	小于等于
  &	&amp;	和
  '	&apos;	单引号
  "	&quot;	双引号

3. 配置请求参数

单击API编辑页面右侧的请求参数，配置各项参数。

如果您选择的是高级SQL模式，为了确保API详情的参数说明与实际调用情况一致，请您根据SQL脚本，手动新增所有请求参数至列表中。

4. 配置返回参数

单击API编辑页面右侧的返回参数，配置各项参数。

1. 配置返回参数。

   如果您选择的是高级SQL模式，为了确保API详情的参数说明与实际调用情况一致，请您根据SQL脚本，手动新增所有返回参数至列表中。

   参数	描述
   参数名称	返回参数的名称，支持英文、数字、下划线、连字符（-），且仅支持以英文开头，不能超过64个字符。
   参数类型	包括STRING、INT、LONG、FLOAT、DOUBLE和BOOLEAN。
   示例值	该返回参数的示例值。
   描述	该返回参数的简要说明。

2. 在高级配置区域，设置是否返回结果分页。

   • 如果不开启返回结果分页，则API默认最多返回2000条记录。

   • 如果返回结果可能超过2000条，请开启返回结果分页功能，开启后，您可以进入右侧导航栏的服务资源组页面，根据资源组类型设置单页条数上限。

   说明

   当数据服务的API在编辑页面右侧导航栏的返回参数已经开启了返回结果分页，如果您在该API编辑页面的编写查询SQL区域，使用SQL语句配置了limit限制（即返回结果的条数限制），则该limit限制不生效，返回结果的条数限制仍然会以返回结果分页的配置内容为准。

   开启返回结果分页后，会自动增加以下公共参数：

   • 公共请求参数

     • returnTotalNum：用于确定单次请求中是否要返回数据总条数。

     • pageNum：当前页号。

     • pageSize：页面大小，即每页记录数。

   • 公共返回参数

     • pageNum：当前页号。

     • pageSize：页面大小，即每页记录数。

     • totalNum：总记录数。

   说明

   API允许不设置请求参数，当无请求参数时，必须开启返回结果分页。

5. 配置过滤器

当您需要对API的请求参数进行预处理或对查询结果进行二次加工时，您可以在API编辑页面的右侧导航栏中，单击过滤器，根据需要勾选使用前置过滤器或使用后置过滤器，并选择函数类型后，单击前置过滤器或后置过滤器右侧的下拉框选择目标函数（可添加多个函数，执行时会按添加顺序对参数进行处理），完成后，您可以单击API返回结果预览查看使用过滤器后的结果是否符合预期。创建和使用过滤器详情请参见：创建Aviator函数、创建Python函数。

6. 配置服务资源组

1. 在API编辑页面的右侧导航栏中，单击服务资源组，您可以在资源组类型区域配置API调用时使用的资源组类型。

   支持您选择独享服务资源组或公共服务资源组，独享服务资源组可以在列表中选择目标资源组名称。公共服务资源组不可选择资源组名称，由DataWorks内部自动维护。

   说明

   • 若在列表中未看到目标资源组名称，请进入资源组列表页，单击指定资源组操作列的绑定工作空间，将资源组与工作空间进行绑定。

   • 若在列表中已展示目标资源组，但无法选中，请进入资源组列表页，单击指定资源组操作列的 > 配额管理，手动设置资源组数据服务用途的当前占用CU（按量付费资源组设置）或CU保障（包年包月资源组设置）取值。

2. 在环境配置区域，您可设置内存、超时时间和单次请求数据条数上限。

   • 所选DataWorks服务资源组和API网关实例的类型不同，允许设置的超时时间上限不同：

     • API网关共享实例：公共服务资源组不超过30000ms，独享数据服务资源组不超过30000ms。

     • API网关专享实例：公共服务资源组不超过30000ms，独享数据服务资源组不超过90000ms。

     说明

     API的响应时间取决于SQL实际的执行时间，请根据实际SQL的执行时间合理配置API超时时间，避免因响应超时导致请求失败。

   • 所选服务资源组类型不同，允许设置的单页条数上限不同：

     • 如果选择公共服务资源组，开启分页后的每页数据记录最多支持2000条。

     • 如果选择独享服务资源组，开启分页后的每页数据记录最多支持10000条。

     说明

     API返回结果总数暂无上限控制，返回结果数与实际查询结果数一致。

7. 保存并提交

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