DMS数据服务提供了功能强大与开发便捷的API模块,本文介绍新增API、管理API的操作说明。

前提条件

已开通API网关

新增API

  1. 登录新版DMS控制台
  2. 在页面顶部,选择全部功能 > 数据工厂 > 数据服务
  3. 在左侧导航栏,单击API开发
  4. 单击右上角的新增API,进入API定义页面,如下图所示。
  5. 配置信息。

    API的属性包含属性配置执行配置请求参数返回参数,由于配置信息较多,控制台上将以4个页签展示。

    • 属性配置页包含API的基本属性,各属性定义如下。

      名词 名词解释
      API名称(必选) 数据API的名称,支持汉字,英文,数字,下划线(_),且只能以英文和汉字开头,4~100个字符。
      描述(可选) 用于API的逻辑描述,如描述返回的是什么数据,用于什么场景。
      路径(必选) 该路径为API调用地址的组成部分。

      路径只能以/开头,只支持英文、数字、下划线(_)、横杠(-),如/item/add

      API调用地址结构为:https://{分组域名}{路径}

      如路径定义为/item/test、分组域名为xxxx-cn-hangzhou.alicloudapi.com,则最终API调用地址为https://xxxx-cn-hangzhou.alicloudapi.com/item/test

      返回格式(必选) 目前仅支持以JSON格式返回API的数据。
      请求方式(必选) 通用的API请求方式,支持的选项:
      • POST
      • GET
      本示例的请求方式为GET
      超时时间(必选) 执行API时的最大耗时,单位为毫秒,默认值为10000。

      调用API时,当执行时间超过该参数值,将返回超时错误。该值最大允许30000(毫秒),即30秒。

      返回最大记录数(必选) 调用API允许返回的最大记录数。默认值为1000。
      说明 当实例处于安全管控模式下,安全规则中同样定义了返回最大记录数,此时,API的最大记录数,不允许超过安全规则中的返回最大记录数。
    • 执行配置页包含API执行时读取数据的配置,各属性定义如下。
      名词 名词解释
      实例查询类型 实例查询的类型,支持的权限:
      • 单实例查询:仅查询一个数据库实例。可以通过表引导模式和SQL脚本模式定义API。
      • 跨实例查询:通过编写跨数据库查询DSQL,来实现多个不同实例数据的关联查询,详细信息,请参见官方文档。仅支持SQL脚本模式定义API。
      数据源 待查询的数据库。通过输入关键字,可查询当前用户有查询权限的数据库。

      该参数仅当实例查询类型单实例查询模式时显示。

      配置方式 选择API的配置方式,支持的选项:
      • 表引导模式:通过可视化的方式选择表、字段,定义API的数据查询配置。
      • 脚本模式:通过手动编写SQL脚本+变量的方式来定义API的数据查询配置。
      说明表引导模式切换为 脚本模式时,系统将提示切换模式将清空请求参数和返回参数。

      该参数仅当实例查询类型单实例查询模式时显示。

      选择表 表引导模式下,可选择需要执行查询的表。可通过输入关键字快捷查找表。

      该参数仅当配置方式表引导模式时显示。

      字段列表 该字段列表会展示当前选择的数据表中的所有字段,您可以通过勾选的方式,快速定义目标字段作为API的请求参数和返回参数。

      该参数仅当配置方式表引导模式时显示。

      查询SQL 您可以在此编写查询SQL。

      SQL脚本支持变量的定义。通过定义变量,可映射成为API的请求参数。变量在SQL中,以${变量名}的方式书写。例如${category},完整带变量的SQL为select item_id, item_name from ex_item where category=${category}

      在编写完成SQL脚本后,需要单击解析脚本按钮解析脚本的正确性以及变量定义。解析成功后,系统会自动基于定义的变量作为请求参数。

      该参数仅在以下两种情况显示:
      • 跨实例查询,且只支持DSQL语法,更多信息,请参见DSQL语法
      • 单实例查询脚本模式,语法需要与选择的数据源语法类型一致。
    • 请求参数页包含API的入参定义信息,通过在表引导模式下勾选字段,或者在脚本模式下编写变量来定义。各项属性定义如下。
      名词 名词解释
      参数名称 调用API时的入参名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。
      变量名称字段名称 这里显示该参数来源,可来源于表引导模式的字段,也可来源于脚本模式的变量。
      不能为空 该项定义请求参数在调用时,是否为必需项。勾选则代表请求参数为必须输入项。
      说明配置方式脚本模式时,所有参数均为必需,不可去勾选; 表引导模式时,则可选。
      描述 用于描述该请求参数。
      数据类型 包括字符串整型浮点三种基本类型,默认为字符串。

      此参数的作用为:在调用时将校验请求参数值是否符合对应的类型,且在执行API时,保障SQL的正常执行。

      示例值 请求参数的示例值。

      在生成SDK和文档时,供使用者阅读,便于正确调用API。

      默认值 当请求参数为可选时,如果存在该定义,则以该定义作为入参执行API。
    • 返回参数页包含API执行后,返回的数据结构。由于当前只支持读取表数据,因此返回参数列表的组合也代表了所执行数据查询的二维表结构。各项属性定义如下。
      名词 名词解释
      参数名称 返回参数名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。
      变量名称字段名称 仅显示返回的字段名。
      描述 用于描述返回参数。
      数据类型 包括字符串整型浮点三种基本类型,默认为字符串

      此参数的作用为:系统把查询后的数据,按照此处定义进行数据转换,最终将数据写入返回的JSON中。

      示例值 返回参数的示例值。在生成SDK和文档时,供使用者阅读,便于正确了解API返回信息。
  6. 单击保存按钮,完成新增API操作。
    说明 单击 发布按钮可直接发布该API。

发布API

  1. 登录新版DMS控制台
  2. 在页面顶部,选择全部功能 > 数据工厂 > 数据服务
  3. 在左侧导航栏,单击API开发
  4. API管理页,找到未发布的API,在发布状态列显示为未发布,可单击目标API右侧操作列下的发布按钮。
    说明 您也可在API编辑界面,单击 发布按钮进行发布操作。
  5. 在弹出的窗口中单击确认按钮。
    发布后的API处于上线状态,可使用SDK进行调用。由于API与API网关集成,因此发布后的API,可在API网关的控制台中看到,但不可编辑,否则将影响API的可用性。

管理API

  1. 登录新版DMS控制台
  2. 在页面顶部,选择全部功能 > 数据工厂 > 数据服务
  3. 在左侧导航栏,单击API开发
    • 修改API
      1. API管理页面中,点击每个API右侧操作列下的修改按钮。

        可进入修改API界面,修改API的配置规则与新增API一致,具体操作,可参见新增API

        说明
        • 该操作支持修改API的任何属性,但修改API操作需要确保不影响线上正在调用的应用。如请求参数变更、返回参数变更,均可能影响API的调用。需要根据变更,调整调用API的参数请求和返回参数处理逻辑。
        • 修改后的API,需要进行重新发布才会生效。
    • 删除API
      1. API管理页中,单击目标API右侧操作列下的删除按钮。
      2. 在弹出的窗口中单击确认按钮,即执行删除操作。

        删除API的同时,会对API进行下线处理,也会同步删除API网关中对应的API。