第三方标准数据接口

标准接口仅平台版提供

如果第三方系统需要获取本系统数据,可以使用本接口功能,工程师务必先全文阅读此文档,此接口为通用文档,可读取系统接入的已知和未知设备数据,相关权限请联系平台运营方。


本系统提供数据接口基本方式为按照http post方式提交数据,结果以json格式返回,数据采用utf-8编码。


测试地址(url): http://www.c5ims.com/api_forthree.php

注:测试地址可以get方式提交数据,正式接口地址请联系平台运营方,且只能post获取数据  


参数:

action: 操作标识码

usercode:用户编码,联系平台运营方获取

par......... :提交的参数

checkcode:效验码,为提交参数与密钥key的md5码 。key为当天日期(服务器请保持与北京时间一致),格式为1970-01-01  

接口会校验usercode,且只能操作usercode相关权限的设备,无关设备无权限操作


接口中出现字母的地方无特殊约定一律采用小写



 准备工作(平台运营方操作)

添加帐号,并设定帐号权限如图所示:

image.png

请将UserCode值提供给对方工程师,接口当中需要此编码


image.png

请勾选允许开放数据的点位,如上示例:允许对方获取 1#温湿度传感器   测试热量积算仪   测试热量表    3个表具的数据。

注:示例3个表具实际属于2种不同的表具类型,实际项目中可能也会碰到这种情况,以下示例均以此说明


 接口协议 


获取设备类型编码

因为开放的数据可能属于不同的设备类型,所以第一步需要获取设备类型列表。


参数:

action:getdevicetype

usercode:XXXXXX

完整的get方式获取数据的地址为:

http://www.c5ims.com/api_forthree.php?action=getdevicetype&usercode=textqx_10311

测试如下:

image.png

备注:无须在程序中实现此接口,没有新的设备类型加入,返回值是固定不变的,且有新的设备类型加入的时候,已有的设备类型编码也不会改变,所以在接口中将此处返回值可以定义为常量

返回结果同时输出了原始数组及JSON格式,只是方便工程师查看,后续获取数据中仅输出json格式数据


获取类型属性

上一步中返回了2个设备类型 1029 1112,我们需要先获取这2种设备的相关属性

参数:

action:getdevicetypepar

typecode:1029

Usercode:XXXX

完整的get方式获取数据的地址为:

http://www.c5ims.com/api_forthree.php?action=getdevicetypepar&typecode=1029&usercode=textqx_10311


测试如下:

image.png

备注:为方便工程师对接,此处接口同时输出了2种格式的数据,数组及JSON格式,因为后续数据均只有JSON一种格式,此处输出2种格式只是便于工程师测试。

无须在程序中实现此接口,在平台管理方没有独立通知的情况下,每种设备的属性是不变的。


注:此处par001,par002,par003 不一定为连续 可能输出的只有par005,par007也是有可能的,完全取决于平台运营方的设定



读取所有表具实时数据

action : getalldata

checkcode: md5(“action=getalldata&usercode=xxxxxxx&key=2019-12-11”) 


所以完整的get方式获取数据的方式为:

http://www.c5ims.com/api_forthree.php?action=getalldata&usercode=textqx_10311&checkcode=8649394e3cffff7243f2c25d07fc9ce3

注意:此接口在正式服务器1分钟仅允许访问一次,高频率访问会被拒绝。


测试如下:


image.png


返回数据为:

[{"devicename":"\u6d4b\u8bd5\u70ed\u91cf\u8868","devicecode":"1029","uid":"AA0020_1","par001":"78.94","par002":"0.17","par003":"-125.04","par004":"-125.14","par005":"1.13","par006":"0","par007":"0","shijian":"2019-12-11 23:29:04"},{"devicename":"\u6d4b\u8bd5\u70ed\u91cf\u79ef\u7b97\u4eea","devicecode":"1029","uid":"C002_1","par001":"110355503.67","par002":"0","par003":"-125.28","par004":"-125.06","par005":"9507733.62","par006":"0","par007":"0","shijian":"2019-12-11 23:28:02"},{"devicename":"1#\u6e29\u6e7f\u5ea6\u4f20\u611f\u5668","devicecode":"1112","uid":"WQ08_1","par001":"21.4","par002":"49.3","shijian":"2019-12-11 23:29:03"}]


以上返回数据实际就是如下


image.png


uid 可以唯一定义一台设备,其他参数都不可以

uid 可以唯一定义一台设备,其他参数都不可以

uid 可以唯一定义一台设备,其他参数都不可以

重要的事情说3遍!!!!!!


注意:如果提交的验证码不对,浏览器会直接显示系统接受的md5码,以及参与运算的字符串(此功能为方便调试使用,仅测试平台具备,正式平台不具备此功能)

如下:

image.png

因为MD5运算因子中带有时间KEY,所以直接用上面给出的连接测试都是会报错的,只需要用页面显示的最后一串md5码替换连接中checkcode值即可。


读取单个表具(此接口不再提供,请勿尝试

action : getonedata

par1: uid (注意:此处采用原始返回数据中的大小写模式)

checkcode:同上


比如:

http://www.c5ims.com/api_forthree.php?action=getonedata&usercode=textqx_10311&par1=WQ08_1&checkcode=ba8adf5ee7d1ad62b017fbdcb1a0c5ad


具体不再赘述



《完》