数据管理DMS的数据服务是将您在DMS上管控的数据以API的形式快速对外输出的功能,本文将介绍如何新增、发布、测试与调用API。

前提条件

已开通API网关

准备工作

本示例已提前创建 student_courses表,并插入部分测试数据,SQL语句如下:
/** 创建表 **/
CREATE TABLE `student_courses` (
  `id` BIGINT(20) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
  `student_id` BIGINT(20) DEFAULT NULL COMMENT '学生ID',
  `course_id` BIGINT(20) DEFAULT NULL COMMENT '课程ID',
  `start_time` DATETIME DEFAULT NULL COMMENT '创建时间',
  `score` int(11) DEFAULT NULL COMMENT '考试成绩',
  KEY `idx_student_course` (`student_id`,`course_id`),
  KEY `idx_student_time` (`student_id`,`start_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='数据服务测试表';

/** 插入数据 **/
INSERT INTO `student_courses` VALUES (1,1,1,'2020-11-24 11:19:54',78);
INSERT INTO `student_courses` VALUES (2,1,2,'2020-11-24 05:51:36',68);
INSERT INTO `student_courses` VALUES (3,1,3,'2020-11-24 05:28:08',60);
INSERT INTO `student_courses` VALUES (4,2,1,'2020-11-24 07:21:17',67);
INSERT INTO `student_courses` VALUES (5,2,2,'2020-11-24 02:07:52',91);
INSERT INTO `student_courses` VALUES (6,2,3,'2020-11-24 10:35:35',94);
INSERT INTO `student_courses` VALUES (7,3,1,'2020-11-24 03:19:03',53);
INSERT INTO `student_courses` VALUES (8,3,2,'2020-11-24 08:19:18',94);
INSERT INTO `student_courses` VALUES (9,3,3,'2020-11-24 02:04:17',89);

步骤一:新增并发布API

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

    API的属性包含属性配置执行配置请求参数返回参数,共4个部分,由于配置信息较多,系统用4个页签展示。本示例仅介绍部分涉及到的参数,完整的参数说明,请参见新增API

    • 属性配置
      名词 名词解释
      API名称(必选) 数据API的名称,支持汉字,英文,数字,下划线(_),且只能以英文和汉字开头,4~100个字符。

      本示例的API名称为POC_API_test

      路径(必选) 该路径为API调用地址的组成部分。

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

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

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

      请求方式(必选) 通用的API请求方式,支持的选项:
      • POST
      • GET
      本示例的请求方式为GET
      属性配置_poc_API_test
    • 执行配置

      本示例的执行配置单实例查询表引导模式,并设置student_id字段为请求参数,student_idcourse_idscore字段为返回参数。

      名词 名词解释
      实例查询类型 实例查询的类型,支持的权限:
      • 单实例查询:仅查询一个数据库实例。可以通过表引导模式和SQL脚本模式定义API。
      • 跨实例查询:通过编写跨数据库查询DSQL,来实现多个不同实例数据的关联查询,详细信息,请参见官方文档。仅支持SQL脚本模式定义API。
      数据源 待查询的数据库。通过输入关键字,可查询当前用户有查询权限的数据库。

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

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

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

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

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

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

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

      配置执行方式POC_api_test
    • 请求参数
      名词 名词解释
      参数名称 调用API时的入参名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。
      变量名称字段名称 这里显示该参数来源,可来源于表引导模式的字段,也可来源于脚本模式的变量。
      数据类型 包括字符串整型浮点三种基本类型,默认为字符串。本示例将student_id参数的数据类型设置为整型

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

      请求参数
    • 返回参数
      名词 名词解释
      参数名称 返回参数名称,支持英文、数字、横杠(-)、下划线(_),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。
      变量名称字段名称 仅显示返回的字段名。
      数据类型 包括字符串整型浮点三种基本类型,默认为字符串

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

      返回参数
  6. 配置完成后,单击发布按钮。
    说明 您也可以单击 保存按钮,保存该API的配置。
    至此,已发布该API接口。

步骤二:测试API

验证API配置是否正确。

  1. 登录新版DMS控制台
  2. 在页面顶部,选择全部功能 > 数据工厂 > 数据服务
  3. 在左侧导航栏,单击API测试
  4. 在下拉框中,选择POC_API_test
  5. 参数值文本框中。输入1,单击测试按钮。
    执行后,右侧会显示执行信息以及执行的返回结果(以表格和JSON两种方式呈现)。 测试API返回结果

步骤三:调用API

您可以通过多种方式调用API,例如使用SDK调用API和客户端调用API,调用时认证方式包括简单认证(AppCode)和摘要签名认证方式。具体操作,请参见API调用概述

本示例介绍使用简单认证(AppCode)方式调用API。API调用地址的结构为:https://{Endpoint}{API路径}?AppCode=AppCode值&请求参数1=xxx&请求参数2=xxx。您可以在DMS控制台上获取EndpointAppCode值等信息。

  1. 登录新版DMS控制台
  2. 在页面顶部,选择全部功能 > 数据工厂 > 数据服务
  3. 在左侧导航栏,单击API调用
  4. API调用页面,获取Endpoint(API调用地址)与AppCode值。

    本示例的API调用地址为:https://xxxe3e-cn-hangzhou.alicloudapi.com/item/POC_API_test?AppCode=3284xxxxx&student_id=1

    调用api
    您可以将API调用地址复制到浏览器或通过curl命令调用该API。