为满足高阶用户的个性化查询需求，数据服务为您提供自定义SQL的脚本模式，您可以自行编写API的查询SQL。在脚本模式下，支持多表关联、复杂查询和聚合函数等功能。本文为您介绍如何通过脚本模式生成API。

前提条件

配置API前，请先在工作空间管理 > 数据源管理页面配置数据源。详情请参见配置数据源。

进入数据服务页面

  1. 登录DataWorks控制台。
  2. 在左侧导航栏，单击工作空间列表。
  3. 选择工作空间所在地域后，单击相应工作空间后的更多 > 数据服务。

生成API

  1. 在服务开发页面，鼠标悬停至新建图标，单击API > 生成API。
    您也可以打开相应的业务流程，右键单击API，选择新建 > 生成API。
  2. 在生成API对话框中，配置各项参数。
    脚本模式
    参数 描述
    API模式 包括向导模式和脚本模式，此处选择脚本模式。
    SQL模式 包括基础SQL和高级SQL：
    • 基础SQL：通过基础SQL语法来编写查询逻辑，与旧版SQL的支持能力一致。
    • 高级SQL：通过支持Mybatis标签的SQL语法来编写查询逻辑。目前支持的标签类型包括：if、choose、when、otherwise、trim、foreach和where。
    API名称 支持中文、英文、数字、下划线（_），且只能以英文或中文开头，4~50个字符。
    API Path API存放的路径，例如/user。
    协议 支持HTTP和HTTPS协议。

    如果您需要通过HTTPS协议调用API，请您发布API至网关后，在API网关控制台绑定独立域名，并上传SSL证书。详情请参见支持HTTPS。

    请求方式 支持GET和POST请求方式。
    说明 当请求方式选择GET时，请求参数位置仅支持选择QUERY。当请求方式选择POST时，请求参数位置支持选择QUERY和BODY。
    返回类型 仅支持JSON返回类型。
    可见范围 包括工作空间和私有：
    • 工作空间：该API对本工作空间内的所有成员可见。
    • 私有：该API仅对API的负责人可见，且暂不支持授权。
      说明 如果设置可见范围为私有，在目录树中，仅自己可见，工作空间内的其他成员不可见。
    标签 从标签列表中选择相应的标签，详情请参见创建及管理API标签。
    说明 标签名称支持汉字、英文、数字和下划线（_），您最多可以设置5个标签，且每个标签不超过20个字符。
    描述 对API进行简要描述，不得超过2000个字符。
    目标文件夹 存放API的目录。
  3. 单击确认。

配置API

  1. 双击打开API的编辑页面，在选择表区域，配置数据源类型和数据源名称、数据源环境等参数。
    不同数据源类型的配置参数略有不同，具体配置参数以界面为准。选择表
    说明
    • 您需要提前在工作空间管理 > 数据源管理中配置好数据源，数据表下拉列表支持表名搜索。
    • 必须先选择一个数据源，并且仅支持同一个数据源的多表关联查询。
    • 标准模式工作空间支持在数据源环境配置项选择访问开发或生产环境数据源，详情请参见必读：简单模式和标准模式的区别。
    • 对于MaxCompute类的数据源表，您可以使用DataWorks数据服务的加速服务，或MaxCompute的MCQA加速服务进行加速，选择加速服务进行加速时，您需要先创建加速项，操作详情请参见加速服务。
  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标签语法。Mybatis

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

      如果在高级SQL中编辑Mybatis标签时包含了特殊字符，则需要将特殊字符进行转义处理。常见的转义处理可参考下表：
      特殊字符 转义字符 含义
      > > 大于
      >= >= 大于等于
      < &lt; 小于
      <= &lt;= 小于等于
      & &amp; 和
      ' &apos; 单引号
      " &quot; 双引号
  3. 单击API编辑页面右侧的请求参数，配置各项参数。
    如果您选择的是高级SQL模式，为了确保API详情的参数说明与实际调用情况一致，请您根据SQL脚本，手动新增所有请求参数至列表中。
    说明
    • 进行结果预览前请设置API参数的示例值、默认值、描述等信息。
    • 尽量设置有索引的字段为请求参数。
    请求参数
    参数 描述
    参数名称 请求参数的名称，支持英文、数字、下划线、连字符（-），且仅支持以英文开头，不能超过64个字符。
    参数类型 包括STRING、INT、LONG、FLOAT、DOUBLE和BOOLEAN。
    参数位置 包括QUERY和BODY。
    说明 当有一个或多个参数位置选择BODY时，需要对BODY位置的参数进一步设置Content-Type来定义调用方在消息体中的传参格式。
    Content-Type包括：
    • application/json;charset=utf-8（JSON格式）
    • application/xml;charset=utf-8（XML格式）
    • application/x-www-form-urlencoded;charset=utf-8（FORM格式）
    是否必填 该请求参数是否必填。
    示例值 该请求参数的示例值。
    默认值 该请求参数的默认值。
    描述 该请求参数的简要说明。
  4. 单击API编辑页面右侧的返回参数，配置各项参数。
    返回参数
    1. 配置返回参数。
      如果您选择的是高级SQL模式，为了确保API详情的参数说明与实际调用情况一致，请您根据SQL脚本，手动新增所有返回参数至列表中。
      参数 描述
      参数名称 返回参数的名称，支持英文、数字、下划线、连字符（-），且仅支持以英文开头，不能超过64个字符。
      参数类型 包括STRING、INT、LONG、FLOAT、DOUBLE和BOOLEAN。
      示例值 该返回参数的示例值。
      描述 该返回参数的简要说明。
    2. 在高级配置区域，设置是否返回结果分页。
      • 如果不开启返回结果分页，则API默认最多返回2000条记录。
      • 如果返回结果可能超过2000条，请开启返回结果分页功能，开启后，您可以进入右侧导航栏的服务资源组页面，根据资源组类型设置单页条数上限。
      说明 当数据服务的API在编辑页面右侧导航栏的返回参数已经开启了返回结果分页，如果您在该API编辑页面的编写查询SQL区域，使用SQL语句配置了limit限制（即返回结果的条数限制），则该limit限制不生效，返回结果的条数限制仍然会以返回结果分页的配置内容为准。
      开启返回结果分页后，会自动增加以下公共参数：
      • 公共请求参数
        • pageNum：当前页号。
        • pageSize：页面大小，即每页记录数。
      • 公共返回参数
        • pageNum：当前页号。
        • pageSize：页面大小，即每页记录数。
        • totalNum：总记录数。
      说明 API允许不设置请求参数，当无请求参数时，必须开启返回结果分页。
  5. 配置过滤器。
    当您需要对API的请求参数进行预处理或对查询结果进行二次加工时，您可以在API编辑页面的右侧导航栏中，单击过滤器，根据需要勾选使用前置过滤器或使用后置过滤器，并选择函数类型后，单击前置过滤器或后置过滤器右侧的下拉框选择目标函数（可添加多个函数，执行时会按添加顺序对参数进行处理），完成后，您可以单击API返回结果预览查看使用过滤器后的结果是否符合预期。创建和使用过滤器详情请参见：创建和使用Aviator函数（过滤器）、创建和使用Python函数（过滤器）。
    说明
    • 当使用Python函数作为过滤器时，请先开通DataWorks专业版及以上版本，并使用公共数据服务资源组。
    • 当使用Aviator函数作为过滤器时，无DataWorks版本限制，但需要使用独享数据服务资源组。
    • 若在过滤器的下拉列表中无法获取目标函数，请检查目标函数是否已发布，或尝试新建函数并发布。详情请参见发布函数。
    过滤器
  6. 配置服务资源组。
    1. 在API编辑页面的右侧导航栏中，单击服务资源组，您可以在资源组类型区域配置API调用时使用的资源组类型。
      支持您选择独享服务资源组或公共服务资源组，独享服务资源组可以在列表中选择目标资源组名称。公共服务资源组不可选择资源组名称，由DataWorks内部自动维护。API
      说明 若在列表中无法选中目标资源组名称，请进入DataWorks控制台通过“修改归属工作空间”将资源组与工作空间进行绑定。
    2. 在环境配置区域，您可设置内存、超时时间和单次请求数据条数上限。
      • 所选DataWorks服务资源组和API网关实例的类型不同，允许设置的超时时间上限不同：
        • API网关共享实例：公共服务资源组不超过30000ms，独享数据服务资源组不超过30000ms。
        • API网关专享实例：公共服务资源组不超过30000ms，独享数据服务资源组不超过90000ms。
      • 所选服务资源组类型不同，允许设置的单页条数上限不同：
        • 如果选择公共服务资源组，开启分页后的每页数据记录最多支持2000条。
        • 如果选择独享服务资源组，开启分页后的每页数据记录最多支持10000条。
  7. 单击工具栏中的保存图标，保存API后，所选资源组将在测试时生效。
    配置API后，您可以对其进行测试。详情请参见测试API。

    测试成功后，单击右上方的提交。

    在API编辑页面的右侧导航栏中，单击版本，找到待申请版本单击申请发布跳转到申请页面，申请类型默认为发布数据服务API，填写申请原因后单击申请权限完成发布申请。
    说明 工作空间定义审批流后需要走流程审批才可以发布API，详情请参见：审批中心概述

    发布API后，服务资源组的配置即可在调用API时生效。

    您还可以在服务开发页面左侧目录树中对目标API进行克隆和删除等操作。您也可以在服务管理页面，展开API列表，查看已发布API的详情。详情请参见查看、删除、移动、克隆API