DMS数据服务提供了功能强大与开发便捷的API模块,本文介绍新增API、管理API的操作说明。
前提条件
已开通API网关。
新增API
- 登录数据管理DMS 5.0。
- 在顶部菜单栏中,选择集成与开发(DTS) > 数据应用 > 数据服务,进入DMS数据服务页面。
- 在左侧导航栏,单击API开发。
- 进入API管理页面,单击右上角的新增API。
- 配置信息。
API的属性包含属性配置、执行配置、请求参数、返回参数,由于配置信息较多,控制台上将以4个页签展示。
-
属性配置
名词 名词解释 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
超时时间(必选) 执行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语法。
- 单实例查询的脚本模式,语法需要与选择的数据源语法类型一致。
- 请求参数
名词 名词解释 参数名称 调用API时的入参名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。 变量名称或字段名称 这里显示该参数来源,可来源于表引导模式的字段,也可来源于脚本模式的变量。 不能为空 该项定义请求参数在调用时,是否为必需项。勾选则代表请求参数为必须输入项。 说明 当配置方式为脚本模式时,所有参数均为必需,不可去勾选;表引导模式时,则可选。描述 用于描述该请求参数。 数据类型 包括字符串、整型、浮点三种基本类型,默认为字符串。 此参数的作用为:在调用时将校验请求参数值是否符合对应的类型,且在执行API时,保障SQL的正常执行。
示例值 请求参数的示例值。 在生成SDK和文档时,供使用者阅读,便于正确调用API。
默认值 当请求参数为可选时,如果存在该定义,则以该定义作为入参执行API。 - 返回参数说明 当前只支持读取表数据,因此返回参数列表的组合也代表了所执行数据查询的二维表结构。
名词 名词解释 参数名称 返回参数名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。 变量名称或字段名称 仅显示返回的字段名。 描述 用于描述返回参数。 数据类型 包括字符串、整型、浮点三种基本类型,默认为字符串。 此参数的作用为:系统把查询后的数据,按照此处定义进行数据转换,最终将数据写入返回的JSON中。
示例值 返回参数的示例值。在生成SDK和文档时,供使用者阅读,便于正确了解API返回信息。
-
- 单击保存按钮,完成新增API操作。说明 您也可以单击发布按钮可直接发布API。
管理API
- 登录数据管理DMS 5.0。
- 在顶部菜单栏中,选择集成与开发(DTS) > 数据应用 > 数据服务,进入DMS数据服务页面。
- 在左侧导航栏,单击API开发,进入API管理页面。
- 发布API
单击操作列下的发布,单击确认,完成发布。说明 发布后的API处于上线状态,可使用SDK进行调用。由于API与API网关集成,因此发布后的API,可在API网关的控制台中看到,但不可编辑,否则将影响API的可用性。
- 修改API
单击操作列下的修改,修改完成后,单击发布。属性配置的规则,请参见新增API。说明
- 该操作支持修改API的任何属性,但修改API操作需要确保不影响线上正在调用的应用。如请求参数变更、返回参数变更,均可能影响API的调用。需要根据变更,调整调用API的参数请求和返回参数处理逻辑。
- 修改后的API,需要进行重新发布才会生效。
- 删除API
单击操作列下的删除,在弹出的对话框中,单击确认。说明 删除API的同时,会对API进行下线处理,也会同步删除API网关中对应的API。
- 发布API