管理API

更新时间: 2023-11-07 16:49:15

DMS数据服务提供了功能强大、开发便捷的API模块,本文介绍新增API、发布API、测试API的操作步骤。

前提条件

已开通API网关

步骤一:新增API

  1. 登录数据管理DMS 5.0
  2. 在顶部菜单栏中,选择集成与开发(DTS) > 数据应用 > 数据服务

    说明

    若您使用的是极简模式的控制台,请单击控制台左上角的2023-01-28_15-57-17.png图标,选择全部功能 > 集成与开发(DTS) > 数据应用 > 数据服务

  3. 进入数据服务页面后,在左侧导航栏,单击API开发

  4. 进入API管理页面,单击右上角的新增API

  5. 配置属性配置执行配置请求参数返回参数信息。

    属性配置

    参数

    说明

    API名称

    数据API的名称,支持以汉字,英文,数字或下划线(_)组成,且只能以英文和汉字开头,长度为4~100个字符。

    描述

    用于API的逻辑描述。例如描述API返回的数据,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时的入参名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。

    变量名称字段名称

    这里显示该参数来源,可来源于表引导模式的字段,也可来源于脚本模式的变量。

    不能为空

    该项定义请求参数在调用时,是否为必需项。勾选则代表请求参数为必须输入项。

    说明

    配置方式脚本模式时,所有参数均为必需,不可去勾选;表引导模式时,则可选。

    描述

    用于描述该请求参数。

    数据类型

    包括字符串整型浮点三种基本类型,默认为字符串。

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

    示例值

    请求参数的示例值。

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

    默认值

    当请求参数为可选时,如果存在该定义,则以该定义作为入参执行API。

    返回参数

    说明

    当前只支持读取表数据,因此返回参数列表的组合也代表了所执行数据查询的二维表结构。

    参数

    说明

    参数名称

    返回参数名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。

    变量名称字段名称

    仅显示返回的字段名。

    描述

    用于描述返回参数。

    数据类型

    包括字符串整型浮点三种基本类型,默认为字符串

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

    示例值

    返回参数的示例值。在生成SDK和文档时,供使用者阅读,便于正确了解API返回信息。

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

    说明

    您也可以单击发布按钮可直接发布API。

步骤二:发布API

在发布API后,API处于上线状态,此时,才可在应用中使用SDK进行调用。

API开发页签,单击目标API操作列下的发布,单击确认,完成发布。

说明

由于在DMS控制台定义的API与API网关集成,因此发布后的API,可在API网关的控制台中看到,但不可编辑。

步骤三:测试API

API发布后,您可以在API测试页签下,查看调用API的返回结果是否符合预期。

  1. API测试页签下,单击下拉列表选择目标API名称。

  2. 输入对应的请求参数值,单击测试,系统将以输入的参数值执行API。

    执行后,右侧会显示执行信息以及执行的返回结果(以表格和JSON两种方式呈现)。

后续步骤

调用API

其他操作

修改API

修改API操作支持修改API的任何属性,请在修改前确保不会影响线上正在调用该API的应用。

在API开发页面,单击目标API操作列下的修改,修改完成后,单击发布。属性配置的规则,请参见步骤一:新增API

说明
  • 如变更请求参数、返回参数均可能影响调用API。需要根据变更,调整调用API的参数请求和返回参数处理逻辑。

  • 修改后的API,需要进行重新发布才会生效。

删除API

API开发页面,单击目标API操作列下的删除,在弹出的对话框中,单击确认

说明

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

下线API

API发布页签下,单击目标API操作列下的下线

说明

API下线后,该API将从API发布列表中移除,同时从API网关中同步执行下线操作。此时,该API在API管理中显示未发布状态。

阿里云首页 数据管理 DMS 相关技术圈