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

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

配置API基础信息

  1. 登录DataWorks控制台,单击相应工作空间后的进入数据服务
  2. 鼠标悬停至新建图标,选择生成API > 脚本模式
    脚本模式
  3. 填写生成API对话框中的配置。
    生成API
    配置 说明
    API名称 支持中文、英文、数字、下划线,且只能以英文或中文开头,4~50个字符。
    API分组 API分组是指针对某一个功能或场景的API集合,也是API网关对API的最小管理单元。在阿里云API市场中,一个API分组对应于一个API商品。

    您可以将鼠标悬停至新建图标,单击新建分组进行新建。

    API Path API存放的路径,如/user。
    协议 目前支持HTTP和HTTPS协议。
    请求方式 目前支持GET和POST请求方式。
    返回类型 目前仅支持JSON返回类型。
    描述 对API进行简要描述。
    说明 API分组的设置示例如下:

    例如您要配置一个天气查询的API产品,天气查询API由城市名称查询天气API、景点名称查询天气API和邮编查询天气API三种API组成,那么就可以创建一个名为天气查询的API分组,并把以上三种API放在这个分组中。然后把这个API上架到API市场中销售时,就会呈现为一个天气查询的API产品。

    如果您生成的API是在自己的APP中使用,则可以把分组当作分类来使用。

  4. 完成API基础信息的填写后,单击确认,即可进入API参数配置页面。

配置API查询SQL及参数

  1. 选择数据源类型数据源名称
    选择表
    说明
    • 您需要提前在数据集成中配置好数据源。
    • 必须先选择一个数据源,并且只支持同一个数据源的多表关联查询,不支持跨数据源的关联查询。
  2. 设置内存超时时间
    环境配置
  3. 在代码编辑区中输入查询SQL。
    编写SQL
    说明 SELECT查询的字段为API的返回参数,WHERE条件处的参数为API的请求参数,请求参数请使用${}标识。
  4. 编辑请求参数信息。
    编写好API查询SQL后,单击右侧的请求参数,设置参数名称参数类型是否必填示例值默认值描述
    请求参数
    说明 为帮助API的调用者更全面地了解API,请尽量全面地填写API的参数信息。
  5. 编辑返回参数信息。
    单击右侧的返回参数,设置参数名称参数类型示例值描述,并可以进行返回结果分页使用过滤器等高级配置。
    返回参数
    配置过程中需要注意返回结果分页的设置。
    • 如果不开启返回结果分页,则API默认最多返回500条记录。
    • 如果返回结果可能超过500条,请开启返回结果分页功能。
    开启返回结果分页后,会自动增加以下公共参数。
    • 公共请求参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
    • 公共返回参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
      • totalNum:总记录数。
    说明 SQL规则提示:
    • 仅支持1条SQL语句,不支持多条SQL语句。
    • 支持SELECT,不支持非SELECT语法,如INSERT、UPDATE和DELETE等。
    • SELECT的查询字段为API的返回参数,WHERE条件中的${param}内的变量param为API的请求参数。
    • 不支持SELECT \*,必须明确指定查询的列。
    • 支持同一数据源下的单表查询、多表关联查询和嵌套查询。
    • 如果SELECT查询列的列名带有表名前缀(如t.name),则必须取别名作为返回参数名(如t.name as name)。
    • 如果使用聚合函数(min/max/sum/count等),必须取别名作为返回参数名,如sum(num) as total\_num。
    • SQL中的${param}统一当请求参数进行替换,包含字符串中的${param}。当${param}前包含转义符\时,不做请求参数处理,作为普通字符串处理。
    • 不支持将${param}放在引号中,例如'${id}''abc${xyz}123'。如果需要可以通过concat('abc', ${xyz}, '123’)实现。
    • 不支持将参数设置为可选。

API测试

完成API参数的配置并保存后,单击右上角的测试,即可进入API测试环节。
测试

填写好参数值,单击开始测试,即可在线发送API请求,在右侧可以看到API请求详情及返回内容。如果测试失败,请仔细查看错误提示并做相应的修改重新测试。

配置过程中需要注意正常返回示例的设置。配置好API之后,系统会自动生成异常返回示例和错误码,但没办法自动生成正常返回示例。需要在开始测试前勾选保存为正常返回示例,将当前的测试结果保存为正常返回示例。如果返回结果中有敏感数据需要脱敏,可以手动编辑修改。
保存示例
说明
  • 正常返回示例对于API的调用者来说,具有非常重要的参考意义,请务必配置。
  • API调用延迟是本次API请求的延迟,供您评估的API性能。如果延迟较大,则要考虑进行数据库优化。

完成API测试后,返回服务开发页面,单击发布,即可成功生成一个数据API。

API详情查看

回到API服务列表页面,右键单击相应的API服务,选择详情,即可查看API的详情信息。API详情页面以调用者的视角展示了API的详细信息。