基于HTTP的API服务接口说明书

HTTP协议与ScadaCloud通信说明书(V1.0.0.0)

基于HTTP的API服务接口说明书

(V1.0.0.0)

MinP Technology

Address:深圳市龙岗区吉祥路风临国际A1404

Tel:0755-********

Fax:0755-********

目录

1. SCADACLOUD APP服务介绍 (3)

1.1简介 (3)

1.2请求参数 (3)

1.3举例 (4)

2. 服务详解 (5)

2.1注册 (5)

2.2登陆 (5)

2.3读取数据点当前值 (5)

2.4读取数据点历史数据 (6)

2.5设置数据点 (7)

2.6读取未确认事件 (7)

2.7确认指定的事件 (8)

2.8确认所有的事件 (8)

2.9取最大的告警级别 (9)

注意事项 (10)

附录A： (11)

1. ScadaCloud APP 服务介绍

1.1 简介

ScadaCloud 为终端提供基于HTTP 的接口：登陆，读取数据点的实时数据，读取数据点的历史数据，设置数据点,读取未确认事件，确认事件，确认所有未确认的事件，取当前最大告警级别。 设备ScadaCloud

服务器HTTP 终端设备

ScadaCloud M2M 与APP 通信模型

参与ScadaCloud APP 服务的实体有两个：ScadaCloud 服务器,它提供基于HTTP 的APP 服务，链接为https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp ；终端设备，如智能手机。

在本文档中，时间用距离1970年元月1日0时0分0秒的毫秒数来表示；二进制值用”true ”和”false ”来表示；多状态变量用由"0"~"9"组成的非负整数表示，如"0"，"21"，分别表示状态0和状态21；数字量的值用由"-"，"0"~"9"，"."表示的浮点数，或科学计数法表示的浮点数。本文档对此约定不再另做说明。

API 服务的返回值为UTF-8编码的字符串。

1.2 请求参数

使

用GET 方式时,格式是 'https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=SERVICE&PARAM=VALU

E.....

各参数的含义如下： 参数

含义 service 服务名，当前提供的服务有：login ，登陆服务；dpvalue ，

取数据点当前值；dphistory ，取数据点的历史数据；setdp ，

设置数据点；pendingevents ，取未确认事件；ackevents ，

确认事件；ackpendingevents ，确认所有未确认的事件；

maxalarmlevel ，取账户当前最大的报警级别。

PARAM

服务的参数；不同的服务参数的个数和含义不一样，详见后续说明。

1.3 举例

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=login&user=12228074645@ https://www.sodocs.net/doc/0912773952.html,&password=123456

它表示用户1228074645@https://www.sodocs.net/doc/0912773952.html,登陆。

2. 服务详解

2.1 注册

链接格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=register&username=USERNAME &password=PASSWORD&confirmpassword=PASSWORD

参数说明：

username表示用户名；

password表示密码；

confirmpassword表示确认密码

返回值格式：

如果注册成功，返回字符串“error=OK”，其他字符串表示注册错误。

2.2 登陆

链接格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=login&username=USERNAME& password=PASSWORD

参数说明：

username表示登陆用户名；

password表示登陆密码。

返回值格式：

如果登陆成功，返回字符串“OK”，其他字符串表示登陆错误。

2.3 读取数据点当前值

参数格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=dpvalue & dpxid=DP_XID0&dpxid= DP_XID1……

参数说明：

dpxid表示数据点的XID值，多个dpxid表示一次取多个数据点的当前值，ScadaCloud 对一次取多少个数据点的当前值没有限制，由此带来的带宽问题由用户自己考虑。

返回值格式：

一、e rror=Fault string，表示错误信息。

二、count=COUNT&dpxid=DP_XID0&timevalue=TIME0;VALUE0…

count=COUNT：COUNT表示实际返回值多少个数据点的值。

dpxid=DP_XID0：表示数据点的XID为DP_XID0，随后的timevalue=TIME0;VALUE0数据点的时间和值。

比如，count=1&dpxid=DP_001210&timevalue=1396744235937;false,表示返回一个数据点的值，该数据点的xid为DP_001210，值的时间为1396744235937，值为false。

假如没有当前值返回，返回”count=0”。

2.4 读取数据点历史数据

参数格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=dphistory& & dpxid=DP_XID&starttime=TIME0&finaltime=TIME1

参数说明：

dpxid表示数据点的XID值，一次只能取一个数据点的历史数据。

starttime表示开始时间，starttime=0表示从最早的开始时间。

finaltiem表示结束时间，finaltime=0表示结束时间为当前时间。

Starttime=0&finaltime=0表示取全部的历史数据。

一次最多能取1K个历史数据。如果要取大于1K的历史数据，可以多次取，即每次的starttime为上一次的最后的那个历史数据的时间值加1.

一次只能取一个数据点的历史数据。

返回值格式：

一、e rror=Fault string，表示错误信息。

二、dpxid=DP_XID&count=COUNT&timevalue=TIME0;VALUE0;TIME1;VALUE1……dpxid=DP_XID表示数据点的XID为DP_XID。

count=COUNT表示包含多少个历史数据。

timevalue为历史数据的时间和值，时间和值总是成对出现，时间与值用分号隔开。

比如，dpxid=DP_001210&count=2&timevalue=1367243381729;true;13672436

81729;false，表示返回数据点DP_001210的两个历史数据，时间和值分别为1367243381729;true和1367243681729;false。

假如没有历史数据返回，返回” dpxid=DP_XID&count=0”。

2.5 设置数据点

参数格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=setdp&dpxid=DP_XID&value=V ALUE……

参数说明：

dpxid表示数据点的XID，多个dpxid表示一次设置多个数据点的值。

Value表示设置的值。

dpxid与value总是成对出现。

返回值格式：

一、e rror=Fault string，表示错误信息。

二、count=COUNT&dpxid=DP_XID……，count表示设置成功的数据点个数，dpxid表示设置成功的数据点。未在返回值列出的数据点表示没有设置，比如，该数据点没有激活。

2.6 读取未确认事件

参数格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=pendingevents

一次最多读取100条未确认事件。

参数说明：

无参数

返回值格式：

一、error=FAULT STRING，表示错误信息。

二、

count=COUNT&event=EVENT_ID;ALARM_LEVEL;ACTIVE_TIME_STAMP;CONTENT; RETURN_TO_NORMAL_TIME_STAMP;RETURN_TO_NORMAL_MESSAGE;IS_SILEN CED……。

count=COUNT，表示返回至中有COUNT条事件。

event=

EVENT_ID;ALARM_LEVEL;ACTIVE_TIME_STAMP;CONTENT;RETURN_TO_NORMA L_TIME_STAMP;RETURN_TO_NORMAL_MESSAGE;IS_SILENCED，

表示事件的内容，事件的各自断由分号隔开，依次分别为事件ID，告警级别，生成时间，内容，返回正常状态时间，返回正常状态内容，是否是静音。

2.7 确认指定的事件

参数格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=ackevents&eventid=EVENTID……

参数说明：

eventide=EVENTID，表示需要确认的事件ID。

返回值格式：

一、error=FAULT STRING，表示错误信息。

二、count=COUNT&eventid=EVENTID……，

count=COUNT，表示确认了多少条事件，

eventide=EVENTID，表示被确认的事件ID。

2.8 确认所有的事件

参数格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=ackpendingevent

一次最多确认100条未确认事件。

参数说明：

无

返回值格式：

一、error=FAULT STRING，表示错误信息。

二、count=COUNT，表示确认了多少条事件。

eventide=EVENTID，表示被确认的事件ID。

2.9 取最大的告警级别

参数格式：

https://www.sodocs.net/doc/0912773952.html,/ScadaCloud/api/ext.jsp?service=maxalarmlevel

参数说明：

无

返回值格式：

一、error=FAULT STRING，表示错误信息。

二、maxalarmlevel=MAX_ALARM_LEVEL，表示账户的当前的最大告警级别。

注意事项

无

附录A：

无