DEM-API接口调用示例-新增数据库监控过程

环境信息

应用	配置
DEM	dem7.7.1
tomcat	apache-tomcat-8.5.88
DM8	8.1.4.80
接口调试工具	Apifox

  本次示例部署DEM地址为192.168.19.11:8080/dem，已略去DEM的部署过程。

DEM新增管理员用户

  调用接口过程需要验证用户登录和权限，为了避免直接使用超级管理员admin，我们需要先在DEM新增一个额外的管理员用户。
  使用admin管理员用户登录DEM后，新增一个test01管理员用户，用于接口调用调试，密码设置为Test@2025，如图1。

调用encrypt接口获取用户密码加密后数据

  调用api接口时传输的所有密码数据均需要通过该接口加密后的密文数据来使用，我们新建的DEM用户test01密码明文是Test@2025，需要获取其加密后的密文数据。
  encrypt接口请求基础参数和返回数据如下：
请求路径

POST /api/v2/sysconfig

请求参数

• 基础请求参数

参数	类型	必选	示例值	描述
action	String	是	getToken	接口名称，本接口值：getToken。
version	Integer	否	1	接口版本，默认值：1，本接口值：1。
demUser	String	是	admin	用户名。
demPwd	String	是	xxx	密码，需使用加密引擎进行加密。
validTime	Long	否	600	有效期，单位：秒，取值范围：大于0。

返回结果

• 基础数据结构

参数	类型	说明
data	String	token。
successful	Boolean	请求是否成功。
timestamp	String	服务端完成请求的时间戳。
duration	Integer	服务端处理请求的时间（毫秒）。
status	Integer	符合 HTTP Status 规范的编码。
message	String	返回消息。
本次测试的接口调用地址完整如下：

http://192.168.19.11:8080/dem/api/v2/sysconfig?action=encrypt&version=1&content=Test@2025

  在headers设置新增Content-Type，值application/json ：

  用post方式调用接口地址，返回状态200为成功，返回的data数据即为我们需要的加密后数据，（如下图2）“Test@2025”加密后的密文数据为“500E4A9EE38737E41B831331C7C3125C”。

调用getToken接口登录dem用户获取验证token

  其他所有查询、修改、新增操作权限接口的调用，均需要getToken接口登录后返回的token数据认证。所以调用其他接口前我们先获取token，token数据存在时效性，即时更新即时使用。
  token接口请求参数和返回数据结构如下：
请求路径

POST /api/v2/sysconfig

请求参数

• 基础请求参数

参数	类型	必选	示例值	描述
action	String	是	getSYSConfig	接口名称，本接口值：getSYSConfig。
version	Integer	否	1	接口版本，默认值：1，本接口值：1。
keyword	String	否	foo	检索关键字，不区分大小写。查询字段：配置项，属性，描述。

返回结果

• 基础数据结构

参数	类型	说明
data	ObjectArray	系统配置信息。
successful	Boolean	请求是否成功。
timestamp	String	服务端完成请求的时间戳。
duration	Integer	服务端处理请求的时间（毫秒）。
status	Integer	符合 HTTP Status 规范的编码。
message	String	返回消息。

• 系统配置(Item)的数据结构

参数	类型	说明
group	String	配置项组。
name	String	配置项。
value	String	属性值。
desc	String	描述。

  我们使用test01用户登录，密码值需为encrypt接口加密后的密文数据，本次测试接口调用完整地址如下：

http://192.168.19.11:8080/dem/api/v2/sysconfig?action=getToken&version=1&demUser=test01&demPwd=500E4A9EE38737E41B831331C7C3125C&validTime=300

  使用post方式调用，如下图4，调用接口返回200提示成功，其中返回的data数据即为token数据。

调用getMainframes接口获取DEM已监控成功的主机列表

  getMainframes接口可以获取已监控成功的主机列表和主机信息，方便确认主机是否在线。
  getMainframes接口请求参数和返回数据结构如下：
请求路径

POST /api/v2/resource

请求参数

• 基础请求参数

参数	类型	必选	示例值	描述
action	String	是	getMainframes	接口名称，本接口值：getMainframes。
version	Integer	否	1	接口版本，默认值：1，本接口值：1。
keyword	String	否	192.168.1.1	IP地址或主机名的关键字，不区分大小写。
status	String	否	success,unknown	主机状态，可查询多个状态，以','间隔，取值范围: * success: 成功 * unknown: 未知

返回结果

• 基础数据结构

参数	类型	说明
data	ObjectArray	主机(Mainframe)列表。
successful	Boolean	请求是否成功。
timestamp	String	服务端完成请求的时间戳。
duration	Integer	服务端处理请求的时间（毫秒）。
status	Integer	符合 HTTP Status 规范的编码。
message	String	返回消息。

• 主机(Mainframe)的数据结构

参数	类型	说明
id	Long	主机ID。
outerIp	String	外网IP。
innerIp	String	内网IP。
ips	ObjectArray	IP信息(IP)列表。
name	String	主机名称。
status	String	状态，取值范围: * success: 成功 * unknown: 未知
osName	String	系统名称。
osArch	String	系统架构。
cpuDesc	String	CPU型号。
cpuCount	Integer	CPU核数。
menSize	Long	内存大小，单位：B。
agentVersion	String	代理根版本。
agentHome	String	代理根目录。
gmtRegister	String	注册时间。
gmtUpdate	String	上次监控时间。

• IP信息(IP)的数据结构

参数	类型	说明
ip	String	IP地址。
mac	String	MAC地址。

  本次测试接口调用完整地址如下：

http://192.168.19.11:8080/dem/api/v2/resource?action=getMainframes&version=1&status=success

  headers里新增设置参数token，值为getToken接口返回的data数据，如图：

  post方式调用，调用成功后结果如下图6，其中id和outerip为主要关注数据：

调用createDatabase接口完成单机数据库实例监控添加

  该接口请求基础参数和返回数据结构如下：
请求路径

POST /api/v2/resource

请求参数

• 基础请求参数

参数	类型	必选	示例值	描述
action	String	是	createDatabase	接口名称，本接口值：createDatabase。
version	Integer	否	1	接口版本，默认值：1，本接口值：1。

• 请求体

参数	类型	必选	示例值	描述
id	Long	是	0	ID。 新增数据库监控时，值取0； 修改数据库监控时，值为修改对象编号
type	String	否	DB	站点类型，取值范围: DB,MP,SP,BP,BS,ASM,ASMM,CSS,CSSM, MONITOR,WATCHER,AMON,JMON,IMON,AP,GRPMON 其中，DB,MP,SP,BP,BS属于数据库实例类型站点 默认值：DB action=createDatabase时，值必为DB
mfId	Long	否	72066525171512854	主机ID。 主机ID和外网IP不能同时为空。
outerIp	String	否	192.168.1.100	外网IP。 主机ID和外网IP不能同时为空。
port	Integer	否	5236	端口号。 type为数据库实例类型时，不可为空。
userName	String	否	SYSDBA	用户名。 type为数据库实例类型时，不可为空。
password	String	否	xxx	密码。 type为数据库实例类型时，不可为空。
name	String	否	192.168.1.100:5236	名称。 最大长度100。不指定将使用IP/PORT等信息进行标识
connParams	String	否	logLevel=error&logDir=/home/test/dmdbms/log	连接参数。 格式: key1=value1&key2=value2, 多个参数间用'&'分隔
backupSeachPath	String	否	/home/test/dmdbms/bak	备份扫描路径。 格式: path1;path2, 多个路径间用';'分隔
serviceName	String	否	DmServiceDMSERVER	服务名。 如果站点以服务方式启动,请填写服务名。 type非数据库实例类型时，服务名和启动命令不能同时为空。
startParam	String	否	/home/test/dmdbms/bin/DmService.sh start	启动命令。 如果站点以脚本方式启动,请选择启动脚本。 type非数据库实例类型时，服务名和启动命令不能同时为空。
autoRestart	Boolean	否	false	是否自动拉起。
desc	String	否	这是描述信息	附加的描述信息。 描述长度不能超过500。
config	String	否	gather_db_info_freq = [60] gather_db_stat_freq = [60]	监控参数配置。 每行配置一个参数。

返回结果

• 基础数据结构

参数	类型	说明
data	Object	添加成功的单实例(Database)信息。
successful	Boolean	请求是否成功。
timestamp	String	服务端完成请求的时间戳。
duration	Integer	服务端处理请求的时间（毫秒）。
status	Integer	符合 HTTP Status 规范的编码。
message	String	返回消息。

• 数据库(Database)的数据结构

参数	类型	说明
id	Long	ID。
instName	String	实例名。
type	String	站点类型，取值范围: DB,MP,SP,BP,BS,ASM,ASMM,CSS,CSSM, MONITOR,WATCHER,AMON,JMON,IMON,AP,GRPMON 其中，DB,MP,SP,BP,BS属于数据库实例类型站点
status	String	状态，取值范围: * success: 成功 * fail: 失败 * unknown: 未知
mfId	Long	主机ID。
outerIp	String	外网IP。
innerIp	String	内网IP。
port	Integer	端口号。
name	String	名称。
connParams	String	连接参数。
backupSeachPath	String	备份扫描路径。
serviceName	String	服务名。
startParam	String	启动命令。
autoRestart	Boolean	是否自动拉起。
desc	String	附加的描述信息。
config	String	监控参数配置
gmtRegister	String	注册时间。
gmtUpdate	String	上次监测时间。

  本次测试接口调用完整地址如下：

http://192.168.19.11:8080/dem/api/v2/resource?action=getMainframes&version=1&status=success

  同样需要设置token参数值：

  并且在body中传入需要的数据库实例信息和监控参数，需要注意的是password的值也是需要经过encrypt接口加密后返回的密文数据，此次不再演示获取过程，body传入的json如下：

{
"mfId": "72271158497319004",
"outerIp": "192.168.19.1",
"port": 5236,
"userName": "SYSDBA",
"password": "22785034D96D38352A388B0323D105EF",
"name":"测试新增单机1",
"desc":"测试库"
}

  通过post方式调用，调用成功后如下图，会返回数据库监控信息：

  登录DEM的数据库监控确认，单机实例监控已添加成功。

其他接口使用

  其他更多API接口使用说明详见DEM的api.md接口说明文档。

常见问题

1. 调用接口失败，提示“dempwd is illegal”。
     参数中涉及密码的值未使用encrypt接口加密后的密文替换时，就会出现此提示。
2. createDatabase接口返回成功，但是DEM监控界面数据库监控是失败状态
     如果是新加入监控的主机，未配置内外网ip的时候，此时监控数据库界面会提示主机无效，导致监控数据库实例失败，只需要在DEM主机监控界面，找到该数据库实例所在主机，配置网络-设置外网ip保存即可。