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

前提条件

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

生成API

  1. 进入数据服务页面。
    1. 登录DataWorks控制台
    2. 在左侧导航栏,单击工作空间列表
    3. 选择工作空间所在地域后,单击相应工作空间后的进入数据服务
  2. 服务开发页面,鼠标悬停至新建图标,单击API > 生成API
    您也可以打开相应的业务流程,右键单击API,选择新建 > 生成API
  3. 生成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
    协议 支持HTTPHTTPS协议。

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

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

配置API

  1. 双击打开API的编辑页面,在选择表区域,选择数据源类型数据源名称
    选择表
    说明 必须先选择一个数据源,并且仅支持同一个数据源的多表关联查询。
  2. 环境配置区域,设置内存超时时间
    环境配置
  3. 编写查询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’)实现。
        • 不支持设置参数为可选。
        • 不支持在注释中写入${param}。例如--${id}
      • 如果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。

  4. 单击API编辑页面右侧的请求参数,配置各项参数。
    如果您选择的是高级SQL模式,为了确保API详情的参数说明与实际调用情况一致,请您根据SQL脚本,手动新增所有请求参数至列表中。请求参数
    参数 描述
    参数名称 请求参数的名称,支持英文、数字、下划线、连字符(-),且仅支持以英文开头,不能超过64个字符。
    参数类型 包括STRINGINTLONGFLOATDOUBLEBOOLEAN
    是否必填 该请求参数是否必填。
    示例值 该请求参数的示例值。
    默认值 该请求参数的默认值。
    描述 该请求参数的简要说明。
    如果您需要对API的请求参数进行预处理,请选中高级配置区域的使用前置过滤器。详情请参见创建和使用前置过滤器
    说明
    • 仅华东2(上海)地域的DataWorks专业版及以上版本支持使用前置过滤器。
    • 尽量设置有索引的字段为请求参数。
    • 为方便API调用者了解API详情,请尽量设置API参数的示例值、默认值、描述等信息。
  5. 单击API编辑页面右侧的返回参数,配置各项参数。
    如果您选择的是高级SQL模式,为了确保API详情的参数说明与实际调用情况一致,请您根据SQL脚本,手动新增所有返回参数至列表中。返回参数
    参数 描述
    参数名称 返回参数的名称,支持英文、数字、下划线、连字符(-),且仅支持以英文开头,不能超过64个字符。
    参数类型 包括STRINGINTLONGFLOATDOUBLEBOOLEAN
    示例值 该返回参数的示例值。
    描述 该返回参数的简要说明。

    您还可以在高级配置区域,设置是否返回结果分页使用过滤器

    返回结果分页的说明如下:
    • 如果不开启返回结果分页,则API默认最多返回2000条记录。
    • 如果返回结果可能超过2000条,请开启返回结果分页功能。
    开启返回结果分页后,会自动增加以下公共参数:
    • 公共请求参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
    • 公共返回参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
      • totalNum:总记录数。
    如果您需要对API的查询结果进行二次处理,请选中使用过滤器。详情请参见创建和使用后置过滤器
    说明
    • 仅华东2(上海)地域的DataWorks专业版及以上版本支持使用后置过滤器。
    • API允许不设置请求参数,当无请求参数时,必须开启返回结果分页
  6. 单击工具栏中的保存图标。
    配置API后,您可以对其进行测试。详情请参见测试API

    测试成功后,请关闭API测试对话框,单击右上方的发布

    您还可以在服务开发页面,展开API列表,查看已发布API的详情,并进行克隆和删除等操作。详情请参见管理API