• 跨平台实时数据库Rest API

    0. 综述

    0.1 开启Rest

    Rest API需授权并手动开启。

    1. Rest API默认对外暴露所有点的读写权限,如需对点的读写权限进行限制,需要在【数据点组态】中设置读写权限,并启用安全管理:

      设置读写权限:IDE左上角【数据库】→左侧导航树→数据点组态→右侧点列表中双击打开点属性设置→【安全】选项卡→开启访问限制并配置用户组

      img

      启用安全管理:IDE左上角【画面】→左侧导航树→【公共】文件夹→安全设置→【安全设置】选项卡→启用安全管理

      img

    2. Rest API需要开启REST服务,配置方式:左上角【数据库】→左侧导航树→对外发布(文件夹)→REST服务→勾选启用REST服务(默认端口号8000,可配置)

    img

    1. 确认Rest服务被勾选:【画面】→左侧导航树→公共→启动设置→REST服务(应已自动被勾选)→全部保存

    我们不建议您在公网可访问的服务器中开启Rest API,这可能招致恶意的网络攻击,引发严重的后果。如需在公网使用,请考虑开启安全管理

    如果您开启了安全管理,则需要先通过http请求进行用户认证,获取识别身份用的token,并在之后的请求中携带这个token(携带位置:URL 查询参数)。具体方法在下面的示例中体现。

    注意:所有API的返回值(response body)中都会携带一个code字段,用来标记请求是否成功,code为0表示成功,code为其它值表示失败或有错误。

    0.2 常见问题

    1. 获取对外发布数据项某节点下的所有点的实时数据(API文档第六项)时,返回的数据为空是什么原因?

     

    1. 获取或插入大量数据时,系统提示数据量过大,如何解决?

    为保护服务器不过载,单次查询或插入数据的最大条数有限制,您也可以在【数据库参数设置】中自行设置。

    db-setting

     

    1. 用户登录【GET】

    URL: /api/userlogin

    描述:开启安全管理后需要先用已注册的用户名和密码登录,获取token,并在之后的请求中携带这个token。token有效期为无限期。需要token失效时可使用登出API。未开启安全管理则不需要携带token。

    查询参数

    参数必须说明
    userstring
    用户名
    passstring
    密码

    示例

    请求示例

    GET方法:http://127.0.0.1:8000/api/userlogin/?user=user1&pass=123456

    返回示例

     

    2. 用户登出【GET】

    URL: /api/userlogout

    描述:可用此API携带token进行登出,登出后token失效。

    查询参数

    参数必须说明
    tokenstring
    登录时得到的token

    示例

    请求示例

    GET方法:http://127.0.0.1:8000/api/userlogout?token=MPzrIAj06iEx9dspMfMgMjdk

    返回示例

    登出成功时code为0,code不为0代表失败

     

    3. 获取实时数据(点名属性分离)【GET】

    URL:/api/realdata

    描述:这种方式适合获取多个点的多个属性值时使用。

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token
    tagsstring
    点名不带属性,多个值逗号隔开,如:A1,A2,A3
    parsstring
    属性名,多个值逗号隔开,如:PV,PVTIME,DESC
    decimalInteger
    返回数值小数点后位数,取值范围0~9
    valueonlyInteger
    是否只返回值,取值范围0或1,数字1代表开启"只返回值"模式,这种模式下,响应体中的数据会十分精简,适合获取的数据量很大,追求极快返回速度的情况。返回的值以数组形式表示,顺序与请求时tags参数的顺序相同,详见示例2

    示例1

    请求示例1

    GET方法:http://127.0.0.1/api/realdata?tags=A1,A2,A3&pars=PV,PVTIME,DESC&token=12345678

    返回示例1

    示例2(valueonly模式)

    请求示例2

    GET方法:http://127.0.0.1/api/realdata?tags=A1,A2,A3&pars=PV,DESC&token=12345678&valueonly=1

    返回示例2

     

    4. 获取实时数据(点名+属性)【GET】

    URL: /api/realdata

    描述:这种方式适合于获取每个点的某些特定属性值。

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token
    namesstring
    点名带属性,多个逗号隔开,如:A1.PV, A2.PV, A3.DESC
    valueonlyInteger
    是否只返回值,取值范围0或1,数字1代表开启"只返回值"模式,这种模式下,响应体中的数据会十分精简,适合获取的数据量很大,追求极快返回速度的情况。返回的值以数组形式表示,顺序与请求时names参数的顺序相同,详见示例2
    decimalInteger
    返回数值小数点后位数,取值范围0~9

    示例1

    请求示例1

    GET方法:http://127.0.0.1:8000/api/realdata?names=A1.PV,A1.DESC,A2.PV&token=12345678

    返回示例1

    示例2(valueonly模式)

    请求示例2

    GET方法:http://127.0.0.1:8000/api/realdata?names=A1.PV,A1.DESC,A2.PV&valueonly=1

    返回示例2

    数组内值的顺序与查询参数names的顺序一致,即A1.PV对应100.00,A1.DESC对应"第一个点",A2.PV对应50.00

    这种方式的返回值可读性较差,但体积小,传输效率高,适合对性能有极高要求的场景

    应对海量实时数据读取的API,详见 【获取对外发布数据项某个节点下的所有实时数据】【注册项获取实时数据】

     

    5. 获取【对外发布数据项】节点结构【GET】

    URL: /api/realdir/{subnode1}/...

    描述:REST服务提供通过对外发布数据项节点名获取该节点下所有点的实时数据的API,所以会有通过API获取对外发布数据项节点结构的需求。

    路径参数

    参数说明
    subnode1string
    节点名,如:group1

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token

    示例1

    请求示例1

    GET请求:http://127.0.0.1:8000/api/realdir

    返回示例1

    返回树状结构,此例中节点名为root,其下有两个子节点group1, group2,group1下还有一个子节点level2

    示例2

    请求示例2

    GET请求:http://127.0.0.1:8000/api/realdir/root/group1

    返回示例2

     

    6. 获取【对外发布数据项】某节点下的所有点的实时数据【GET】

    URL:/api/realdata/{nodeName1}/{nodeName2}/......

    描述:无需除token外的查询参数,可直接查询某个节点下的实时数据。响应体内包含【对外发布数据项】内配置的某节点下所有点数据。请求方式类似计算机的文件结构。

    注意:要查询的点必须配置在对外发布数据项中

    路径参数

    参数说明
    nodeName1string
    节点名,如:group1
    nodeName2string
    子节点名,如:level2

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token
    recursionInteger
    是否递归取值,0或1,1代表递归,此时当前节点及其所有子节点下面的点值都会被返回,默认为0不递归,详见示例2
    valueonlyInteger
    是否只返回值,取值范围0或1,数字1代表开启"只返回值"模式,这种模式下,响应体中的数据会十分精简,适合获取的数据量很大,追求极快返回速度的情况。返回的值以数组形式表示,顺序与节点中点的顺序相同,详见示例3
    decimalInteger
    返回数值小数点后位数,取值范围0~9

    示例1

    请求示例1

    GET方法:http://127.0.0.1:8000/api/realdata/group1

    返回示例1

    假设对外发布数据项中配置了【group1】,【group2】两个并列节点。

    group1节点下有一个点值【g1.PV】和一个子节点【level2】,level2下有一个点值【g2.PV】。

    group2节点下有一个点值【g3.PV】。

    则返回的响应体结构如下:

    示例2(递归)

    请求示例2

    GET方法:http://127.0.0.1/api/realdata/group1?recursion=1

    返回示例2

    递归时,group1以及它的子节点(level2)下面的所有点都会被返回

    示例3(valueonly)

    请求示例3

    GET方法:http://127.0.0.1/api/realdata/group1?valueonly=1

    返回示例3

    这种请求方式适合获取的数据量大,追求极快返回速度的情况。对外发布数据项的【group1】节点下有A1.PV,A2.PV两个数据,A1.PV值为60,A2.PV值为30,则返回如下

     

    7. 注册点名(用于批量快速取数据)【GET】

    URL: /api/realdata

    描述:有时我们需要频繁获取一些特定点的数据,而这些点数量较多且分布于不同节点之下。这时我们可以先把这些点在系统中注册成一个特定的名字,之后再通过这个名字简单快速地获取数据。

    注意:注册点名必须携带用户登录时得到的token。每个用户的注册行为是完全独立且相互隔离的。注册完的名字对于其他用户是不可见的。所以即使两个用户恰巧使用同一个名字注册了不同的两组点也不会冲突。

    查询参数

    参数必须说明
    tokenstring
    登录时得到的token,无论是否开启安全管理,注册点名前必须使用一个用户登录并获取token。
    regnamestring
    注册的名字,相当于给一组点起一个特殊的名字
    namesstring
    点名加属性,多个逗号隔开,例如:A1.PV,A2.PV,A3.PV

    示例

    请求示例

    GET方法:http://127.0.0.1:8000/api/realdata?regname=reg01&names=A1.pv,A2.PV,A3.PV&token=12345678

    返回示例

     

    8. 注册项获取实时数据【GET】

    URL: /api/realdata

    描述:将一些点注册成为注册项后,可直接用注册的名字获取这些点的实时数据。获取的实时数据,顺序与注册时的顺序相同。此API与注册点名的API配合,用于快速获取一组点的数据。

    查询参数

    参数必须说明
    tokenstring
    登录时得到的token,无论是否开启安全管理,取值时必须携带token以区分用户。
    regnamestring
    注册项的名称
    decimalInteger
    返回数值小数点后位数,取值范围0~9

    示例

    请求示例

    GET方法:http://127.0.0.1:8000/api/realdata?regname=reg01&token=12345678&decimal=2

    返回示例

     

    9. 设置实时数据【POST】

    URL: /api/realdata

    描述:利用POST方法+请求体的方式设置实时数据。请将需要设置的数据以JSON格式写在请求体(request body)中。

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token

    示例

    请求示例

    POST方法:http://127.0.0.1:8000/api/realdata?token=12345678

    请求体:其中根节点名为items,name为点名带属性,val为要设置的值

    返回示例

    code为0表示设置成功,此时message为空字符串,code不为0表示失败,此时message提示错误信息

     

    10. 设置实时数据(数组方式)【POST】

    URL: /api/realdata

    描述:利用POST方法+请求体的方式设置实时数据。请将需要设置的数据以JSON格式写在请求体(request body)中。与上一种方法不同的是

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token

    示例

    请求示例

    POST方法:http://127.0.0.1:8000/api/realdata?token=12345678

    请求体:其中names为点名带属性的数组,vals为要设置的值的数组,要求二者顺序一致

    返回示例

     

    11. 获取多个时间点历史数据【GET】

    URL: /api/hisdata

    描述:获取多个时间点历史数据

    请求参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token
    timesstring
    格式:yyyy-MM-DDTHH:mm:ss.zzz(日期与时间用T隔开,zzz毫秒值可不带),多个时间点逗号隔开
    如:2022-02-22T14:22:33.444,2022-02-22T15:22:34.555
    names点名带属性,多个值逗号隔开,如:A1.PV,A2.DESC
    decimalInteger
    返回数值小数点后位数,取值范围0~9
    valueonlyInteger
    是否只返回值,取值范围0或1,数字1代表开启"只返回值"模式,这种模式下,响应体中的数据会十分精简,适合获取的数据量很大,追求极快返回速度的情况。返回的值以数组形式表示,按times参数排序,详见示例2

    示例1

    请求示例

    GET方法:http://127.0.0.1:8000/api/hisdata?times=2022-02-22T14:22:33.444,2022-02-22T15:22:34.555&names=A1.PV,A2.DESC

    返回示例

    示例2(valueonly)

    请求示例2

    GET方法:http://127.0.0.1:8000/api/hisdata?times=2022-02-22T14:22:33.444,2022-02-22T15:22:34.555&names=A1.PV,A2.DESC&valueonly=1

    返回示例2

     

    12. 获取一段时间内历史数据【GET】

    URL: /api/hisdata

    描述:获取多个点一段时间内历史数据,注意:除开始时间和结束时间外,还需要设置时间间隔。

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token
    startTimestring
    格式:yyyy-MM-ddThh:mm:ss.zzz(日期与时间用T隔开,zzz毫秒可不带)
    如:2022-01-03T14:25:56.333
    endTimestring
    格式:yyyy-MM-ddThh:mm:ss.zzz(日期与时间用T隔开,zzz毫秒可不带)
    如:2022-01-03T14:25:58.333
    intervalinteger
    间隔时间毫秒值,2500代表2.5秒
    names点名带属性,多个值逗号隔开,如:A1.PV,A2.DESC
    valueonlyInteger
    是否只返回值,取值范围0或1,数字1代表开启"只返回值"模式,这种模式下,响应体中的数据会十分精简,适合获取的数据量很大,追求极快返回速度的情况。返回的值以数组形式表示,按时间先后排序,详见示例2
    decimalInteger
    返回数值小数点后位数,取值范围0~9

    示例1

    请求示例1

    GET方法:http://127.0.0.1:8000/api/hisdata?startTime=2022-02-22T15:22:34&endTime=2022-02-22T15:22:37&interval=1000&names=A1.PV,A2.DESC

    返回示例1

    这种方式在时间点很多时,会返回大量的时间字符串,导致响应体体积过大,响应时间变慢。当时间点很多,且有性能要求时,应采用示例2的方式请求

    示例2(valueonly)

    请求示例2

    GET方法:http://127.0.0.1:8000/api/hisdata?startTime=2022-02-22T15:22:34&endTime=2022-02-22T15:22:37&interval=1000&names=A1.PV,A2.DESC&valueonly=1

    返回示例2

    数组内值的顺序与时间顺序一致,即A1.PV的值50对应时间2022-02-22T15:22:34

    由于开始/结束时间及时间间隔已经确定,数组内值对应的时间可计算得到

    这种方式的返回值体积小,传输效率高,适合对性能有极高要求的场景

     

    13. 设置历史数据【POST】

    URL: /api/hisdata

    描述:利用POST方法+请求体的方式设置历史数据。请将需要设置的数据以JSON格式写在请求体(request body)中。

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token

    示例

    请求示例

    POST方法:http://127.0.0.1/api/hisdata?token=12345678

    请求体:

    返回示例

    code为0表示设置成功,此时message为空,code不为0表示失败,此时message提示错误信息

     

    14. SQL查询【POST】

    URL: /api/SQL

    描述:利用POST方法+请求体的方式传入一个带有SQL语句的JSON,并得到类似表结构的返回值。

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token

    示例

    请求示例

    POST方法:http://127.0.0.1/api/SQL?token=12345678

    请求体:

    返回示例

    每个节点相当于表中一列,节点名相当于列名。

     

    15. 获取报警【GET】

    URL: /api/alarmdata

    描述:带有startTime和endTime两个查询参数时为获取历史报警,否则为获取实时报警,还可以根据点名(tags),报警优先级(level)等多个参数进行筛选。

    查询参数

    参数必须说明
    token否(开启安全管理后必要)string
    登录时得到的token
    realalmcountInteger
    最多取得的条数
    orgstring
    指定要查询的点所在目录
    unitInteger
    指定要查询的点所在单元
    levelInteger
    报警优先级,获取不小于该级别的报警
    tagsstring
    点名列表,多个点逗号隔开,如A1,A2,A3
    groupbytagInteger
    是否按点名分组,为1时分组,为0时不分组
    startTime否(携带后表示取历史报警)string
    格式:yyyy-MM-ddThh:mm:ss.zzz(日期与时间用T隔开,zzz毫秒可不带)
    如:2022-01-03T14:25:56.333
    endTime否(携带后表示取历史报警)string
    格式:yyyy-MM-ddThh:mm:ss.zzz(日期与时间用T隔开,zzz毫秒可不带)
    如:2022-01-03T14:25:56.333

    示例

    请求示例

    GET方法:http://127.0.0.1/api/alarmdata?token=12345678

    返回示例

    各字段说明在返回值示例下方

    ack 确认状态枚举值,0未确认,1确认,2恢复,3禁止(禁止说明该点的报警被禁止掉了,但会保存一条记录)

    cat 类别,对应报警配置中的ID,模拟点默认情况下,36低低报,37低报,38高报,39高高报,多数情况下使用默认配置即可

    desc 说明

    eu 单位

    group 层级,本例中点B2在groupB节点下,所以字段值为"root.groupB"

    level 报警级别枚举值,0低级,1高级,2紧急,在点的报警界面配置。

    limit 限值,分为低低限,下限,上限,高高限,在点的报警界面配置。本例中分别为10,20,80,90

    name 点名,如A1,A2,B2

    oper 确认者

    parno 类型ID,模拟点默认情况下此字段与cat字段相同

    prio 优先级,对于模拟点和数字点,此字段等同于level

    time 报警时间

    unit 点所在的单元,默认为0,可在点设置中配置

    val 点值

    16. 获取数据库点数