全部产品
云市场

API开发

更新时间:2020-06-28 17:30:21

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

新增API

  1. 登录DMS控制台

  2. 在顶部菜单栏,单击数据工厂 > 数据服务

  3. DMS数据服务页,单击左侧导航栏的API开发

  4. 单击右上角的新增API,进入API定义页面,如下图所示。

    1

  5. 参考以下说明填写配置信息。API的属性包含4个部分,由于配置信息较多,分别用4个Tab页面展示,包括属性配置执行配置请求参数返回参数

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

      名词 名词解释
      API名称(必选) 数据API的名称,支持汉字,英文,数字,下划线,且只能以英文和汉字开头,4~100个字符。
      描述(可选) 用以描述API逻辑,如描述返回的是什么数据,用于什么场景。
      路径(必选) 用于在调用API时,组成调用URL的一部分。调用的URL结构为:https://{分组域名}{路径}。如分组域名为xxxx-cn-hangzhou.alicloudapi.com,路径定义为/item/monthly_data,则最终调用API的URL为https://xxxx-cn-hangzhou.alicloudapi.com/item/monthly_data。路径只能以/开头,只支持英文、数字、下划线、横杠,如/item/add
      返回格式(必选) 目前仅支持以JSON格式返回API的数据。
      请求方式(必选) 支持以POST和GET2种通用请求方式。
      超时时间(必选) 执行API时,允许的最大耗时,单位为毫秒。
      调用API时,当执行时间超过该属性值,将返回超时错误。该值最大允许30000(毫秒),即30秒。
      返回最大记录数(必选) 调用API允许返回的最大记录数。该属性定义,将在查询时限制返回的记录数。需要注意的是,当实例处于安全管控模式下,安全规则中同样定义了返回最大记录数,此时,API的最大记录数,不允许超过安全规则中的返回最大记录数。因此定义此值时,需要确保小于安全规则中的最大记录数定义。
    • 执行配置页包含API执行时读取数据的配置,各属性定义如下。

      名词 名词解释
      实例查询类型 包含单实例查询跨实例查询单实例查询为读取的数据仅限于同一个数据库实例。跨实例查询为可以通过编写DSQL,来实现多个不同实例数据的关联查询,更详细信息请阅读官方文档。此外,单实例查询支持表引导模式定义API,而跨实例查询仅支持SQL脚本模式定义API。
      数据源(选择单实例查询后) 执行API查询所在的数据库。通过输入关键字,可查询当前用户有查询权限的数据库。
      配置方式(选择单实例查询后) 包含表引导模式脚本模式表引导模式可通过选择表和字段的快捷操作,定义数据查询配置。脚本模式则是通过手动编写SQL脚本+变量的方式来定义数据查询配置。当用户选择了跨实例查询时,仅支持脚本模式。
      选择表(选择单实例查询后) 表引导模式下,可选择需要执行查询的表。可通过输入关键字快捷查找表。
      字段列表(选择单实例查询后) 此界面主要为了方便用户基于字段列表快速定义请求参数和返回参数。选择了表后,系统自动显示该表的所有字段。用户可通过勾选的方式,把字段定义为API的请求参数和返回参数。
      脚本模式(选择单实例查询脚本模式后) 通过编写脚本的方式定义数据查询逻辑。需要注意的是,当从表引导模式切换为脚本模式时,会提示用户当前的请求参数和返回参数定义。
      查询SQL(选择跨实例查询后或选择单实例查询脚本模式后) 选择脚本模式时,将显示查询SQL输入框。用户可在该输入模式编写查询SQL。所支持的语法,以所选择的数据源的语法类型一致。当用户选择跨实例查询时,则只支持DSQL语法,详细信息请阅读DSQL语法
      SQL脚本支持变量的定义。通过定义变量,可映射成为API的请求参数。
      变量在SQL中,以${变量名}的方式书写。例如${category},完整的带变量的SQL为select item_id, item_name from ex_item where category=${category}
      在编写完成SQL脚本后,需要单击解析脚本按钮解析脚本的正确性以及变量定义。解析成功后,系统会自动基于定义的变量作为请求参数

      32

    • 请求参数页包含API的入参定义信息,通过在表引导模式下勾选字段,或者在脚本模式下编写变量来定义。各项属性定义如下。

      名词名词解释
      参数名称调用API时的入参名称,支持英文,数字,横杠,下划线,且只能以英文或下划线开头,1~50个字符。
      变量名称字段名称这里显示该参数来源,可来源于表引导模式下的字段,也可来源于脚本模式下的变量。
      不能为空该项定义请求参数在调用时,是否为必需项。脚本模式下,所有参数均为必需,不可去勾选;表引导模式下,则可选。勾选则代表请求参数为必须输入项。
      描述用于描述该请求参数。
      数据类型包括字符串、整形、浮点三种基本类型。此定义,作用在两处,第一是在调用时将校验请求参数值是否符合对应的类型,第二是在执行API时,影响最终执行的SQL。默认为字符串。
      示例值请求参数的示例值。在生成SDK和文档时,供使用者阅读,便于正确调用API。
      默认值当请求参数为可选时,如果存在该定义,则以该定义作为入参执行API。

      4

    • 返回参数页包含API执行后,返回的数据结构。由于当前只支持读取表数据,因此返回参数列表的组合也代表了所执行数据查询的二维表结构。各项属性定义如下。

      名词 名词解释
      参数名称 返回参数名称,支持英文,数字,横杠,下划线,且只能以英文或下划线开头,1~50个字符。
      变量名称字段名称 仅显示返回的字段名。
      描述 用于描述返回参数。
      数据类型 包括字符串、整形、浮点三种基本类型。此处定义与请求入参的作用不同,此处定义会把查询后的数据,按照此处定义进行数据转换,最终影响返回数据JSON中的数据。
      示例值 返回参数的示例值。在生成SDK和文档时,供使用者阅读,便于正确了解API返回信息。

      5

  6. 单击保存按钮,完成新增API操作。

    单击发布按钮即可直接发布该API。

发布API

  1. 登录DMS控制台

  2. 在顶部菜单栏,单击数据工厂 > 数据服务

  3. DMS数据服务页,单击左侧导航栏的API开发

  4. API管理页,找到未发布的API,在发布状态列显示为未发布,可单击目标API右侧操作列下的发布按钮。

    7

    也可在API编辑界面,单击发布按钮进行发布操作。

  5. 在弹出的窗口中单击确认按钮即可。

发布后的API处于上线状态,可使用SDK进行调用。由于API与API网关集成,因此发布后的API,可在API网关的控制台中看到,但不可编辑,否则将影响API的可用性。

修改API

  1. 登录DMS控制台
  2. 在顶部菜单栏,单击数据工厂 > 数据服务
  3. DMS数据服务页,单击左侧导航栏的API开发
  4. API管理页中,点击每个API右侧操作列下的修改按钮,可进入修改API界面。
  5. 修改API的配置规则与新增API一致,详情可参见新增API配置说明

  • 该操作支持修改API的任何属性,但修改API操作需要确保不影响线上正在调用的应用。如请求参数变更、返回参数变更,均可能影响API的调用。需要根据变更,调整调用API的参数请求和返回参数处理逻辑。
  • 修改后的API,需要进行重新发布才会生效。

删除API

  1. 登录DMS控制台
  2. 在顶部菜单栏,单击数据工厂 > 数据服务
  3. DMS数据服务页,单击左侧导航栏的API开发
  4. 在API管理页中,单击目标API右侧操作列下的删除按钮,
  5. 在弹出的窗口中单击确认按钮,即执行删除操作。

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