EG系列网关API使用手册

API（Application Programming Interface，应用程序接口）是一些预先定义的函数，或指软件系统不同组成部分衔接的约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机制的细节。

举例：研发人员A开发了软件A，研发人员B正在研发软件B。有一天，研发人员B想要调用软件A的部分功能来用，但是他又不想从头看一遍软件A的源码和功能实现过程，怎么办呢？研发人员A想了一个好主意：我把软件A里你需要的功能打包好，写成一个函数；你按照我说的流程，用咱们约定好的协议和我提供给你的URL来调用我的函数，就相当于使用我A软件的功能！其中，API就是研发人员A说的那个函数。

1. 天气API，为第三方系统提供天气数据，比如中国天气网

2. 地图API，为第三方系统提供地图服务，比如定位，导航，经纬度，比如百度地图开放平台

3. 支付类API，为第三方系统提供线上支付服务，比如，支付宝商户平台，微信商户平台

4. 短信类API，为第三方系统提供验证码服务或短信服务，比如聚合数据

为了满足客户和合作伙伴和多样化需求，EMCP物联网云平台为用户开放了API，支持用户的三方系统或软件，通过API接口获取需要的设备实时数据，历史数据，报警数据，对设备发送读写命令等操作，

用于也可基于此API 文档进行第三方系统开发，保持企业产品独立性，全面提升企业品牌影响力和竞争力。

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

平台将等级共分为了3个，如果您对于调用次数有更多需求，您可以联系您的商务人员申请应用等级调整。

初级、中级、高级的调用额度参考下表。

具体的API调用情况，可按照下图步骤进行查询。

阅读本文之前，您需要具备基础编程知识及面向对象编程的概念。需要对于物联网云平台有一定的了解。

所有开发者，都需要阅读应用和AppKey鉴权部分；

对于初级开发者，本文将从通过快速示例等为您介绍通过API进行接入开发等基础概念，帮助您快速入门，为进一步开发提供指引

对于具备物联网云平台开发经验者，建议直接查询参考API手册获取信息；

针对于具有风格定制需求的用户或开发者，可阅读如何搭建自己企业API服务板块，了解如何构建具备自己企业标识的API服务。

应用是EMCP平台通过API与第三方系统建立关联的纽带，如果您希望通过API搭建或对接企业专属系统，您需要首先在您的EMCP物联网云平台账户中，找到API配置功能，并创建您的应用，创建应用后，可使用应用中对应的Appkey和AppSecret，用于生成token，即可实现从EMCP平台调取对应设备的数据。

企业可根据需要，申请1个或多个应用，用于应对不同系统的接入需求。

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

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

token是服务端生成的一串字符串，作为客户端进行请求的一个令牌，当第三方系统请求token接口后，EMCP服务平台会生成一个Token便将此Token返回给第三方系统，以后第三方系统请求设备数据时只需带上这个Token前来请求数据即可，无需用户名和密码。

通俗意义上来说，token就是一个通行证，去我们系统里调取数据时，告诉系统我们有这个通行证，系统就会允许我们调取数据。

PC浏览器：Chrome、IE6+、Firefox、Opera、Safari

移动设备：iPhone、iPad、Android

步骤1、使用EMCP物联网云平台企业账号，配置好网关，保证能够正常采集和查看对应设备的数据（驱动、变量、报警、报表等）。

步骤2、开通 API功能使用资格。联系您的商务人员，申请开通API配置功能使用资格。

待商务人员受理并分配API资格完成以后，在API列表中可以看到API的信息，如下图所示。

步骤3、根据此API提供的接口，通过AppKey、appSecret，对应账户的用户名，调用接口，获取访问令牌（accessToken），然后通过令牌调用open API接口获取数据，从而能够开发您专属的系统应用。

步骤4、建立使用该API的内部账号，并将需要使用API调用数据的设备授权给该内部账号。

可以创建多个内部账号，授权不同的设备，所有的内部账号共用API的调用次数。

创建好应用后，您可以通过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

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

服务器默认采用UTF-8编码，数据采用JSON格式

请求：Context-Type:application/x-www-form-urlencoded

响应：Context-Type:application/json charset=utf-8

返回时间统一采用UTC时间，北京时间，格式yyyy-MM-dd HH:mm:ss

公版平台、风格定制用户接口IP如下：

API接口ip：http://api.lfemcp.com/

EG设备图片地址ip: http://cdn.lfemcp.com/

私有云用户接口IP如下：

API接口ip：http://私有云域名/api/

EG设备图片地址ip: http://私有云域名/

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

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

接口功能：

获取后续访问接口的令牌
备注：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的过期时间(单位：秒)

接口功能：

获取账号下设备列表

请求地址：

${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：在线

接口功能：

开启设备监控接口

请求地址：

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

请求方式：

POST

请求参数：

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

返回数据

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

返回字段

字段名称	参数类型	参数说明
code	string	200表示开启监控成功，如果失败，再发送一次

详细说明：

1.使用API查询EG设备的实时数据之前，必须调用“开启设备监控”接口，作用是向网关下发一个指令，请求成功后，网关才开会开启设备实时监控

2.“开启设备监控”接口的有效时间为600秒，超出时间后需要重新获取，建议开发者设置590秒作为为一个周期进行校验，防止接口失效，无法调取实时数据

EG设备通过API获取实时数据流程如下：

接口功能：

查询该设备的变量列表

请求地址：

${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",
            "isFormula": 0,
            "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	数据类型
isFormula	Boolean	变量是否有公式，当isFormula=1 && dataType!=boolean && dataType!=string时，该变量采集值按照浮点类型处理
scale	Integer	小数位数
privilege	Integer	读写权限：0-只读，1-只写，2-读写
unit	string	单位
note	string	备注

映射参数说明

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

接口功能：

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

请求地址：

${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	采集时间

接口功能：

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

请求地址：

${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	采集时间

接口功能：

查询该设备下的报警记录

请求地址：

${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	解除时间

接口功能：

报警记录确认

请求地址：

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

请求方式：

POST

请求参数：

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

返回数据

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

接口功能：

查询该设备下所有报表

请求地址;

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

请求方式：

POST

请求参数：

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

返回数据

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

返回字段

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

接口功能：

分页查询历史记录

请求地址：

${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

接口功能：

查询该报表下所有变量

请求地址：

${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	映射文本

接口功能：

向变量写入值

请求地址：

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

请求方式：

POST

请求参数：

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

返回数据

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

返回字段

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

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

接口功能：

查询写入变量的结果的接口（支持异步操作）

请求地址：

${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常见问题

帮助中心

大约 3 小时前

7000

EG系列网关API使用手册

一、API概述

1.1 API概念介绍

1.2 API应用场景举例

1.3 EMCP平台API简介

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

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

二、基础知识

2.1 阅读引导

2.2 应用

2.3 AppKey鉴权

2.3.1 AppKey用途

2.3.2 如何获得Appkey

2.3.3 Token是什么

2.4 兼容性

2.5 如何接入API

2.6 获取token实例

三、API手册

3.1协议说明

3.2 IP说明

3.3 请求参数说明

3.4 返回数据格式

3.5 API接口详情

3.5.1 获取token

3.5.2 EG设备相关接口

3.5.2.1 获取账号下设备列表

3.5.2.2 开启设备监控

3.5.2.3 查询变量列表

3.5.2.4 查询设备下所有变量值

3.5.2.5 查询单个变量的值

3.5.2.6 查询设备报警数据列表

3.5.2.7 报警记录确认

3.5.2.8 查询设备下所有报表

3.52.9 分页查询历史记录

3.5.2.10 查询报表中所有变量

3.5.2.11 向变量写入值

3.5.2.12 查询写入变量的结果

四、错误码说明