EG系列网关API使用手册


一、API概述

1.1 API概念介绍

API(Application Programming Interface,应用程序接口)是一些预先定义的函数,或指软件系统不同组成部分衔接的约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程,而又无需访问源码,或理解内部工作机制的细节。
举例:研发人员A开发了软件A,研发人员B正在研发软件B。有一天,研发人员B想要调用软件A的部分功能来用,但是他又不想从头看一遍软件A的源码和功能实现过程,怎么办呢?研发人员A想了一个好主意:我把软件A里你需要的功能打包好,写成一个函数;你按照我说的流程,用咱们约定好的协议和我提供给你的URL来调用我的函数,就相当于使用我A软件的功能!其中,API就是研发人员A说的那个函数。

1.2 API应用场景举例

1. 天气API,为第三方系统提供天气数据,比如中国天气网
2. 地图API,为第三方系统提供地图服务,比如定位,导航,经纬度,比如百度地图开放平台
3. 支付类API,为第三方系统提供线上支付服务,比如,支付宝商户平台,微信商户平台
4. 短信类API,为第三方系统提供验证码服务或短信服务,比如聚合数据

1.3 EMCP平台API简介

为了满足客户和合作伙伴和多样化需求,EMCP物联网云平台为用户开放了API,支持用户的三方系统或软件,通过API接口获取需要的设备实时数据,历史数据,报警数据,对设备发送读写命令等操作,
用于也可基于此API 文档进行第三方系统开发,保持企业产品独立性,全面提升企业品牌影响力和竞争力。

1.4 EMCP平台API能够帮助企业做什么

1.4.1 设备数据对接到第三方平台

可将设备数据对接到第三方的系统如 OA、ERP 、企业管理系统 、设备管理系统等,借助物联网技术,搭建企业完整的设备管理体系闭环

二、基础知识

2.1 阅读引导

阅读本文之前,您需要具备基础编程知识及面向对象编程的概念。需要对于物联网云平台有一定的了解。
所有开发者,都需要阅读应用和AppKey鉴权部分;
对于初级开发者,本文将从通过快速示例等为您介绍通过API进行接入开发等基础概念,帮助您快速入门,为进一步开发提供指引
对于具备物联网云平台开发经验者,建议直接查询参考API手册获取信息;
针对于具有风格定制需求的用户或开发者,可阅读如何搭建自己企业API服务板块,了解如何构建具备自己企业标识的API服务。 

2.2 应用

应用是EMCP平台通过API与第三方系统建立关联的纽带,如果您希望通过API搭建或对接企业专属系统,您需要首先在您的EMCP物联网云平台账户中,找到API配置功能,并创建您的应用,创建应用后,可使用应用中对应的Appkey和AppSecret,用于生成token,建立与EMCP平台的
企业可根据需要创建1个或多个应用,用于应对不同系统的接入需求,对于应用,也可以授权给企业的外部账号(即客户账号),

2.3 AppKey鉴权

2.3.1 AppKey用途

每一个应用都具有一个唯一的Appkey ,用于识别所创建应用的身份,通过AppKey、AppSecret,账户用户名称调用获取token接口获取访问令牌(accessToken),然后通过令牌调用open API接口才能正常获取数据

2.3.2 如何获得Appkey

  您可以联系您的商务人员申请API配置使用资质,申请资质使用成功后,可创建您的应用,并获得相应AppKey和AppSecret,用于您的系统应用开发

2.3.3 Token是什么

token是服务端生成的一串字符串,以作客户端进行请求的一个令牌,当第三方系统请求token接口后,EMCP服务平台会生成一个Token便将此Token返回给第三方系统,以后第三方系统请求设备数据时只需带上这个Token前来请求数据即可,无需用户名和密码
通俗意义上来说,token就是一个通行证,去我们系统里调取数据时,告诉系统我们有这个通行证,系统就会允许我们调取数据。

2.4 兼容性

PC浏览器:Chrome、IE6+、Firefox、Opera、Safari
移动设备:iPhone、iPad、Android

2.5 如何接入API

1、开通EMCP物联网云平台企业账号
您需要开通EMCP物联网云平台企业账号,配置好智能网关后,能够正常采集和查看对应设备的数据。
2、开通 API功能使用资格
你可以联系您的商务人员,申请开通API配置功能使用资格,
3、创建应用
获得相应API功能授权后,您可以在API功能中创建您的应用,并获得相应AppKey,AppSecret,用于您的系统应用开发
4、接入开发
您可以根据此API文档提供的接口,通过AppKey、appSecret,对应账户的用户名称,调用接口获取访问令牌(accessToken),然后通过令牌调用open API接口获取数据,从而能够开发您专属的系统应用

三、快速入门

3.1 获取token

创建好应用后,您可以通过appKey、appSecret,用户名,调用获取token接口获取访问令牌(accessToken),本示例的中Appkey仅为演示使用,实际开发及上线时,请务必使用您申请的Key。
以下是javascript代码示例:
var url = "http://api.lfemcp.com/token/get";         var xhr = new XMLHttpRequest(); //第一步:新建对象         xhr.open('POST', url, true); //第二步:打开连接         xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded"); //设置请求头 注:post方式必须设置请求头(在建立连接后设置请求头)         var obj = 'appKey=10ea3707317249dea85f94a5b9770226&appSecret=a91e87103c48409f8b2da84c1ddce33d&account=gl3';         xhr.send(obj); //将appkey,appsecret和用户名传入         /**          * 获取数据后的处理程序          */         xhr.onreadystatechange = function() { //请求后的回调接口,可将请求成功后的逻辑             if (xhr.readyState == 4 && xhr.status == 200) { //验证请求是否发送成功                 var res = xhr.responseText; //获取到服务端返回的数据                 console.log(res)             }         }
通过控制台输出结果,可查看已经成功请求接口,并获得accesstoken

四、API详情

4.1 协议说明

服务器默认采用UTF-8编码,数据采用JSON格式
请求:Context-Type:application/x-www-form-urlencoded
响应:Context-Type:application/json charset=utf-8
返回时间统一采用UTC时间,北京时间,格式yyyy-MM-dd HH:mm:ss

4.2 IP说明

公版平台、风格定制用户接口IP如下:
API接口ip:http://api.lfemcp.com/
EG设备图片地址ip: http://cdn.lfemcp.com/
私有云用户接口IP如下:
API接口ip:http://私有云域名/api/
EG设备图片地址ip: http://私有云域名/

4.3 请求参数说明

除获取token的接口(${API接口ip}/token/get)外,其他接口的head中需要传入Authorization=“Bearer+空格+获取token接口得到的token的值”。

4.4 返回数据格式

参数 类型 描述
code Integer 结果码
message String code说明
data Object 返回数据

4.5 接口列表和调用次数额度说明

类别 地址 描述 接口调用额度(零点重新计算)
认证 /token/get 获取token 1000次/天
设备 /eg/equip/list 获取EG设备列表 50000次/天
变量 /eg/signal/list 查询EG设备的变量列表 50000次/天
实时数据 /eg/monitor/open
/eg/signal/value
/eg/signal/singleVal
EG设备开启设备监控接口
查询EG设备下所有变量值
查询EG设备下单个变量的值
50000次/天
读写数据 /eg/signal/writeVal EG设备向变量写入值 5000次/天
读写数据 /eg/signal/callback 查询EG设备写入变量的结果 100000次/天
历史数据 /eg/report/history 查询EG设备的历史记录列表 5000次/天
历史数据 /eg/report/list 查询EG设备下所有报表 5000次/天
历史数据 /eg/report/cols 查询EG设备报表中所有变量 5000次/天
报警 /eg/alarm/list 查询EG设备的报警数据列表 5000次/天
报警 /eg/alarm/confirm EG设备报警记录确认 50000次/天

4.6 API接口详情

4.6.1 获取token

接口功能:

  • 获取后续访问接口的令牌
    备注:token的有效时间为2个小时,重新获取token,会让旧token失效。

请求地址:

  • ${API接口ip}/token/get

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
appKey String 应用键值(分配给客户的appKey)
appSecret String 应用密钥(分配给客户的appSecret)
account String 用户名

返回示例

{
 "code": "200",
 "message": "请求成功",
 "data": {
   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiI5NDM0ZmQ2Yy1mYTgxLTQzNDctOWY1YS00ZWU2YjA3ZDRlYWUiLCJ1c2VySWQiOiJOekE1IiwiaXNzIjoibGFuZmVuZyIsImlhdCI6MTU4MjAyNDEwNiwiZXhwIjoxNTgyMDMxNjA2fQ.rDcaY8T4UM0Pa_awWfkCXb4AjnlxkBDHXYyegDAesbIVtAK9XZrlvN90ut_ru1SsAL6PCMFLPBC5CrFsf_kJ9Q",
   "expires_in": 7200
 }
} 

返回字段

字段名称 参数类型 参数说明
access_token string token的值
expires_in long token的过期时间(单位:秒)

4.6.2 EG设备相关接口

4.6.2.1 获取账号下设备列表

接口功能:

  • 获取账号下设备列表

请求地址:

  • ${API接口ip}/eg/equip/list

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
pagenum Integer 1 当前页数(页码必须大于0)
count Integer 10 每页显示多少条数据(一次性获取最大列表数不能小于1且不能超过1000)
queryParam String 根据“设备名称、备注、绑定的网关SN、详细地址”查询

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": {
        "totalPage": 1,
        "totalCount": 1,
        "list": [
            {
                "id": 7108,
                "sn": "200121011041",
                "title": "200121011041ws",
                "imgUrl": "upload/equipment/multi/1768/dce514da-0f22-4b1d-b2bf-97300bed7139.jpg",
                "address": "山东省威海市文登区",
                "longitude": 122.243416,
                "latitude": 37.1789,
                "note": null,
                "online": true
            }
        ]
    }
}

返回字段

字段名称 参数类型 参数说明
totalPage Integer 总页数
totalCount Integer 总条数
id Integer 设备的id
sn string 绑定的网关SN
title string 设备名称
imgUrl string 图片地址:如使用,请在地址前面加上(${EG设备图片地址ip})
address string 详细地址
longitude Integer 经度
latitude Integer 维度
note string 备注
online boolean 设备是否在线,true:离线,false:在线

4.6.2.2 开启设备监控

接口功能:

  • EG设备开启设备监控接口

请求地址:

  • ${API接口ip}/eg/monitor/open

请求方式:

  • POST

请求参数:

参数名 参数类型 是否必填 默认值 参数说明
equipmentId Integer 设备id

返回数据

  {
    "code": "200",
    "message": "开启数据监控"
  }

返回字段

字段名称 参数类型 参数说明
code string 200表示开启监控成功,如果失败,再发送一次
详细说明:
1.使用API查询EG设备的实时数据之前,必须调用“开启设备监控”接口,作用是向网关下发一个指令,请求成功后,网关才开会开启设备实时监控
2.“开启设备监控”接口的有效时间为600秒,超出时间后需要重新获取,建议开发者设置590秒作为为一个周期进行校验,防止接口失效,无法调取实时数据
EG设备通过API获取实时数据流程如下:

4.6.2.3 查询变量列表

接口功能:

  • 查询变量列表

请求地址:

  • ${API接口ip}/eg/signal/list

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
equipmentId Integer 设备id
queryParam string 查询条件:变量名称/寄存器地址
privilege string 读写权限:0-只读,1-只写,2-读写

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": [
        {
            "id": 380743,
            "imgUrl": "",
            "title": "浮点型读写4位小数",
            "dataType": "boolean",
            "scale": 3,
            "privilege": "2",
            "unit": "WWW",
            "note": "",
            "signalMaps": [
                {
                    "signalValue": "1.0",
                    "signalText": "一二三四五六七八九十"
                },
                {
                    "signalValue": "0.0",
                    "signalText": "零伊尔萨第三方"
                }
            ]
        }
    ]
}

返回字段

字段名称 参数类型 参数说明
id Integer 变量
imgUrl string 图片地址,如使用,请在地址前面加上(${EG设备图片地址ip})
title string 变量名称
dataType Integer 数据类型
scale Integer 小数位数
privilege Integer 读写权限:0-只读,1-只写,2-读写
unit string 单位
note string 备注

映射参数说明

字段名称 参数类型 参数说明
signalValue string 映射值
signalText string 映射文本

4.6.2.4 查询设备下所有变量值

接口功能:

  • 查询设备下所有变量值接口
    说明:查询设备所有变量接口之前,必须 请求“开启设备监控接口”,向网关下发一个指令,请求成功后后,网关才开会开启设备实时监控,才能正常获取到实时数据
    具体可见接口详情:开启设备监控

请求地址:

  • ${API接口ip}/eg/signal/value

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
equipmentId Integer 设备id

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": {
        "390464": {
            "code": "200",
            "dataType": "boolean",
            "value": 0,
            "time": "2021-07-27 11:24:11"
        },
        "390463": {
            ...
        },
        ...
    }
}

返回字段

字段名称 参数类型 参数说明
data中的key值 Integer 变量id
code string 请求结果
dataType string 变量的数据类型
value string 变量值
time string 采集时间

4.6.2.5 查询单个变量的值

接口功能:

  • 查询设备下单个变量值接口
    说明:查询设备所有变量接口之前,必须 请求“开启设备监控接口”,向网关下发一个指令,请求成功后后,网关才开会开启设备实时监控,才能正常获取到实时数据
    具体可见接口详情:开启设备监控

请求地址:

  • ${API接口ip}/eg/signal/singleVal

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
equipmentId Integer 设备id
signalId Integer 变量id

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": {
        "code": "200",
        "dataType": "boolean",
        "value": 1,
        "time": "2021-07-20 09:27:39"
    }
}

返回字段

字段名称 参数类型 参数说明
code string 请求结果
dataType string 变量的数据类型
value string 变量值
time string 采集时间

4.6.2.6 查询设备报警数据列表

接口功能:

  • 查询设备报警记录

请求地址:

  • ${API接口ip}/eg/alarm/list

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
pagenum Integer 1 当前页数(页码必须大于0,默认为1)
count Integer 10 每页显示多少条数据(默认值是10条,一次性获取最大列表数不能小于1且不能超过1000)
equipmentId Integer 设备id
from string 开始时间:格式 "yyyy-MM-dd HH:mm:ss"
end string 结束时间:格式 "yyyy-MM-dd HH:mm:ss"
state boolean 报警状态:false:未解除,否则不要传这个参数
type String 报警类型signal-变量报警offline-离线报警 poweroff-断电报警

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": {
        "totalPage": 1,
        "totalCount": 3,
        "list": [
            {
                "id": 1433915,
                "sn": "200121011045",
                "type": "offline",
                "state": true,
                "value": null,
                "msg": "一号离线报警",
                "gmtTrigger": "2021-07-21 15:10:47",
                "gmtRelease": "2021-07-21 15:31:04"
            },
            { ... },
            { ... }
        ]
    }
}

返回基础字段

字段名称 参数类型 参数说明
totalPage Integer 记录总页数
totalCount Integer 记录总条数
list array 查询结果

返回字段

字段名称 参数类型 参数说明
id Integer 报警记录id
sn String 网关sn
type String 报警类型 signal-变量报警offline-离线报警poweroff-断电报警
state boolean 报警状态:false-触发,true-解除
value string 报警值
msg string 报警信息
gmtTrigger string 触发时间
gmtRelease string 解除时间

4.6.2.7 报警记录确认

接口功能:

  • 报警记录确认

请求地址:

  • ${API接口ip}/eg/alarm/confirm

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
id Integer 报警记录id

返回数据

 {
    "code": "200",
    "message": "请求成功"
}

4.6.2.8 查询设备下所有报表

接口功能:

  • 查询设备下所有报表接口

请求地址;

  • ${API接口ip}/eg/report/list

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
equipmentId Integer 设备id

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": [
        {
            "id": 10140,
            "title": "884878"
        }
    ]
}

返回字段

字段名称 参数类型 参数说明
id Integer 历史报表id
title string 历史报表名称

4.6.2.9 分页查询历史记录

接口功能:

  • 分页查询历史记录接口

请求地址:

  • ${API接口ip}/eg/report/history

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
reportId Integer 报表id
pagenum Integer 1 当前页数(页码必须大于0)
count Integer 10 每页显示多少条数据(一次性获取最大列表数不能小于1且不能超过1000)
from string 开始时间:格式 "yyyy-MM-dd HH:mm:ss"
end string 结束时间:格式 "yyyy-MM-dd HH:mm:ss"

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": {
        "totalPage": 10,
        "totalCount": 100,
        "list": [
            {
                "reportId": 10131,
                "time": "2021-07-23 10:19:51",
                "cols": {
                    "col390119": -0.2
                }
            },
            { ... },
            { ... },
            ...
        ]
    }
}

返回基础字段

字段名称 参数类型 参数说明
totalPage Integer 记录总页数
totalCount Integer 记录总条数
list array 查询结果

**返回字段 **

字段名称 参数类型 参数说明
reportId Integer 报表id
time string 采集时间
col${id} String 值 ,col后面的数字是变量对应的id

4.6.2.10 查询报表中所有变量

接口功能:

  • 查询报表下所有变量

请求地址:

  • ${API接口ip}/eg/report/cols

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
reportId Integer 报表id

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": [
        {
            "id": 390722,
            "imgUrl": "upload/equipment/multi/1768/6b67f6a8-ce60-4cc4-8c21-f31d65978200.png",
            "title": "bit",
            "dataType": "boolean",
            "scale": 2,
            "privilege": "2",
            "unit": "",
            "note": null,
            "signalMaps": [
                {
                    "signalValue": "1",
                    "signalText": "开阀门"
                },
                {
                    "signalValue": "0",
                    "signalText": "关阀门"
                }
            ]
        },
        {...}
    ]
}

返回字段

字段名称 参数类型 参数说明
id Integer 变量
imgUrl string 图片地址,如使用,请在地址前面加上${EG设备图片地址ip}
title string 变量名称
dataType Integer 数据类型
scale Integer 小数位数
privilege Integer 读写权限:0-只读,1-只写,2-读写
unit string 单位
note string 备注

映射字段说明

字段名称 参数类型 参数说明
signalValue string 映射值
signalText string 映射文本

4.6.2.11 向变量写入值

接口功能:

  • 向变量写入值

请求地址:

  • ${API接口ip}/eg/signal/writeVal

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
signalId Integer 变量id
value string 写入值

返回数据

  {
    "code": "200",
    "message": "请求成功",
    "data": {
        "uuid": "291c8dd5d8f34e83975e462c1e5771de"
    }
}
  

返回字段

字段名称 参数类型 参数说明
uuid string 异步回调标识(十分钟内有效)

特殊说明:如果希望获取到写入结果,请调用“查询写入变量结果”接口

4.6.2.12 查询写入变量的结果

接口功能:

  • 查询写入变量的结果的接口(支持异步操作)

请求地址:

  • ${API接口ip}/eg/signal/callback

请求方式:

  • POST

请求参数:

参数名称 参数类型 是否必填 默认值 参数说明
uuid String String 操作configid,唯一字符串

返回数据

{
    "code": "200",
    "message": "请求成功",
    "data": {
        "status": "success",
        "code": "200",
        "message": "请求成功",
        "data": [
            {
                "code": "200",
                "signalId": 391981,
                "message": "写入成功"
            }
        ]
    }
}

写入变量过程的data字段说明

字段名称 参数类型 参数说明
status string success:成功 running:进行中, failure:失败(若十分钟后仍处于running状态则证明通讯超时)
code string 错误码
message stirng 错误描述

写入变量返回结果的data字段说明

字段名称 参数类型 参数说明
code string 当前变量读写错误码
signalId string 变量id
message stirng 描述

常见错误

错误码 提示消息 原因
4009 查询数据为空! 输入的UUID不正确
4009 查询数据为空! UUID失效(UUID的有效时间是十分钟)

五、错误码说明

返回码 描述 备注
200 请求成功 操作成功
1000 AppKey不存在 appKey不存在
1001 AppKey与账号不匹配 appKey与账号不匹配
1002 AppSecret错误或者AppSecret与AppKey不匹配 appSecret错误或者appSecret与appKey不匹配
1003 token不能为空,请先获取token
1004 无效的token
1005 token过期 token有效期两个小时,超过两个小时token会过期
1006 当日请求次数超限
1007 AppKey停用
1008 该用户禁止登录!
1009 AppKey未授权
1711 下位设备故障
1712 下位设备忙
1713 数据校验错误
1714 变量不存在
1715 响应超时
1712 变量地址不存在
1722 数据类型错误
2000 设备不存在或没有权限访问
2001 设备离线
2002 设备没绑定sn
2003 设备没绑定规则
2004 设备绑定规则不存在
2005 设备关闭查看该功能 曲线,历史数据,读写,报警
2006 设备规则和参数不符 单个曲线,发送读写命令
2007 设备读命令异常
2008 设备写命令异常
2009 读写失败,非法功能
2010 读写失败,非法地址
2011 读写失败,非法数据值
2012 读写失败,从站设备故障
2013 读写失败,确认
2014 读写失败,从属设备忙
2016 读写失败,存储奇偶性差错
2018 读写失败,不可用网关路径
2019 读写失败,网关目标设备响应失败
2024 读写失败,编码错误
2025 读写失败, 超时
3000 参数校验失败
3001 参数数据类型错误
3002 缺少参数
4000 网关通讯超时!
4001 网关离线,无法操作!
4002 VPN模式禁止操作!
4003 当前设备未绑定网关!
4004 开始时间结束时间均不能为空!
4005 写变量超限!
4006 只读变量不可写入值!
4007 运算公式错误,请更改数值运算公式后执行写入操作!
4008 数值无法按照写入公式计算,请更改公式后再执行写入操作!
4009 查询数据为空!
4010 数据不存在或者没有访问权限!
100000 不支持的请求类型
100001 未知异常 sql错误redis错误、业务处理中各种异常
关于API中的常见问题与解决方案可参考API常见问题
帮助中心 帮助中心
1 年多前
3817

扫描下方二维码手机阅读文章

6 0