基于HTTP的AP服务接口说明书.doc

基于HTTP的API服务接口说明书(V) 目 录 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 M2M与APP通信模型 参与ScadaCloud APP服务的实体有两个：ScadaCloud服务器,它提供基于HTTP的APP服务，链接为/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方式时,格式是 /ScadaCloud/api/ext.jsp?service=SERVICEPARAM=VALUE 各参数的含义如下： 参数 含义 service 服务名，当前提供的服务有：login，登陆服务；dpvalue，取数据点当前值；dphistory，取数据点的历史数据；setdp，设置数据点；pendingevents，取未确认事件；ackevents，确认事件；ackpendingevents，确认所有未确认的事件；maxalarmlevel，取账户当前最大的报警级别。 PARAM 服务的参数；不同的服务参数的个数和含义不一样，详见后续说明。 1.3 举例 /ScadaCloud/api/ext.jsp?service=loginuser=12228074645@password=123456 它表示用户1228074645@登陆。 2. 服务详解 2.1 注册 链接格式： /ScadaCloud/api/ext.jsp?service=registerusername=USERNAMEpassword=PASSWORDconfirmpassword=PASSWORD 参数说明： username表示用户名； password表示密码； confirmpassword表示确认密码 返回值格式： 如果注册成功，返回字符串“error=OK”，其他字符串表示注册错误。 2.2 登陆 链接格式： /ScadaCloud/api/ext.jsp?service=loginusername=USERNAMEpassword=PASSWORD 参数说明： username表示登陆用户名； password表示登陆密码。 返回值格式： 如果登陆成功，返回字符串“OK”，其他字符串表示登陆错误。 2.3 读取数据点当前值 参数格式： /ScadaCloud/api/ext.jsp?service=dpvalue dpxid=DP_XID0dpxid= DP_XID1…… 参数说明： dpxid表示数据点的XID值，多个dpxid表示一次取多个数据点的当前值，ScadaCloud对一次取多少个数据点的当前值没有限制，由此带来的带宽问题由用户自己考虑。 返回值格式： error=Fault string，表示错误信息。 二、count=COUNTdpxid=DP_XID0timevalue=TIME0;VALUE0… count=COUNT：COUNT表示实际返回值多少个数据点的值。 dpxid=DP_XID0：表示数据点的XID为DP_XID0，随后的timevalue=TIME0;VALUE0数据点的时间和值。 比如，count=1dpxid=DP_001210timevalue=1396744235937;false,表示返回一个数据点的值，该数据点的xid为DP_001210，值的时间为1396744235937，值为false。 假如没有当前值返回，返回”count=0”。 2.4 读取数据点历史数据 参数格式： /ScadaCloud/api/ext.jsp?service=dphis