跨平台实时数据库Rest API

0. 综述

0.1 开启Rest

Rest API需授权并手动开启。

Rest API默认对外暴露所有点的读写权限，如需对点的读写权限进行限制，需要在【数据点组态】中设置读写权限，并启用安全管理：
设置读写权限：IDE左上角【数据库】→左侧导航树→数据点组态→右侧点列表中双击打开点属性设置→【安全】选项卡→开启访问限制并配置用户组
启用安全管理：IDE左上角【画面】→左侧导航树→【公共】文件夹→安全设置→【安全设置】选项卡→启用安全管理
Rest API需要开启REST服务，配置方式：左上角【数据库】→左侧导航树→对外发布（文件夹）→REST服务→勾选启用REST服务（默认端口号8000，可配置）

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

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

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

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

0.2 常见问题

获取对外发布数据项某节点下的所有点的实时数据（API文档第六项）时，返回的数据为空是什么原因？

请检查请求URL中路径拼写
请检查对外发布数据项中是否有此节点。可能节点结构复杂，遗漏或误删了某节点。
请检查点的访问权限

获取或插入大量数据时，系统提示数据量过大，如何解决？

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

1. 用户登录【GET】

URL: /api/userlogin

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

查询参数

参数	必须	说明
user	是	string 用户名
pass	是	string 密码

示例

请求示例

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

返回示例


{
    "code": 0,
    "token": "MPzrIAj06iEx9dspMfMgMjdk"
}

2. 用户登出【GET】

URL: /api/userlogout

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

查询参数

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

示例

请求示例

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

返回示例

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


xxxxxxxxxx
{
    "code": 0,
    "message": ""
}

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

URL：/api/realdata

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

查询参数

参数	必须	说明
token	否（开启安全管理后必要）	string 登录时得到的token
tags	是	string 点名不带属性，多个值逗号隔开，如：A1,A2,A3
pars	是	string 属性名，多个值逗号隔开，如：PV,PVTIME,DESC
decimal	否	Integer 返回数值小数点后位数，取值范围0~9
valueonly	否	Integer 是否只返回值，取值范围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


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "tag": "A1",
            "PV": 100,
            "PVTIME": "2023-04-25T09:28:25.800",
            "DESC": "第一个点"
        },
        {
            "tag": "A2",
            "PV": 98,
            "PVTIME": "2023-04-25T09:28:26.800",
            "DESC": "第二个点"
        },
        {
            "tag": "A3",
            "PV": 50,
            "PVTIME": "2023-04-25T09:28:27.800",
            "DESC": "第三个点"
        }
    ]
}

示例2（valueonly模式）

请求示例2

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

返回示例2


xxxxxxxxxx
{
    "code": 0,
    "PV": [
        51.0,
        52.0,
        53.0
    ],
    "PVTIME":[
        "2023-04-25T09:28:25.800",
        "2023-04-25T09:28:26.800",
        "2023-04-25T09:28:27.800"
    ],
    "DESC": [
        "第一个点的描述",
        "第二个点的描述",
        "第三个点的描述"
    ]
}

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

URL: /api/realdata

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

查询参数

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

示例1

请求示例1

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

返回示例1


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "name": "A1.PV",
            "val": 100.00
        },
        {
            "name": "A1.DESC",
            "val": "第一个点"
        },
        {
            "name": "A2.PV",
            "val": 50.00
        }
    ]
}

示例2（valueonly模式）

请求示例2

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

返回示例2


xxxxxxxxxx
{
    "code": 0,
    "items": [100.00,"第一个点",50.00]
}

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

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

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

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

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

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

路径参数

参数	说明
subnode1	string 节点名，如：group1

查询参数

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

示例1

请求示例1

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

返回示例1

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


xxxxxxxxxx
{
    "items": [
        {
            "desc": "The Root",
            "items": [
                {
                    "desc": "",
                    "items": [
                        {
                            "desc": "",
                            "name": "level2"
                        }
                    ],
                    "name": "group1"
                },
                {
                    "desc": "",
                    "name": "group2"
                }
            ],
            "name": "root"
        }
    ]
}

示例2

请求示例2

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

返回示例2


xxxxxxxxxx
{
    "items": [
        {
            "desc": "",
            "name": "level2"
        }
    ]
}

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

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

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

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

路径参数

参数	说明
nodeName1	string 节点名，如：group1
nodeName2	string 子节点名，如：level2

查询参数

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

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


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "name": "g1.PV",
            "val": 40
        }
    ]
}

示例2（递归）

请求示例2

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

返回示例2

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


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "name": "g2.PV",
            "val": 50
        },
        {
            "name": "g1.PV",
            "val": 40
        }
    ]
}

示例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，则返回如下


xxxxxxxxxx
{
    "code": 0,
    "items": [
        60,
        30
    ]
}

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

URL: /api/realdata

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

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

查询参数

参数	必须	说明
token	是	string 登录时得到的token，无论是否开启安全管理，注册点名前必须使用一个用户登录并获取token。
regname	是	string 注册的名字，相当于给一组点起一个特殊的名字
names	是	string 点名加属性，多个逗号隔开，例如：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

返回示例


xxxxxxxxxx
{
    "code": 0
}

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

URL: /api/realdata

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

查询参数

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

示例

请求示例

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

返回示例


xxxxxxxxxx
{
    "code": 0,
    "items": [
        10.52,
        8.65,
        89.10
    ]
}

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为要设置的值


xxxxxxxxxx
{
    "items": [
        {
            "name": "A1.PV",
            "val": 40
        },
        {
            "name": "A2.PV",
            "val": 60
        },
        {
            "name": "A3.DESC",
            "val": "第三个点"
        }
    ]
}

返回示例

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


xxxxxxxxxx
{
    "code": 1,
    "message": "error message xxxxxxxxxxx"
}

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为要设置的值的数组，要求二者顺序一致


xxxxxxxxxx
{
    "names": [
        "A1.PV",
        "A2.PV"
    ],
    "vals": [
        6334,
        26500
    ]
}

返回示例


xxxxxxxxxx
{
    "code": 0
}

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

URL: /api/hisdata

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

请求参数

参数	必须	说明
token	否（开启安全管理后必要）	string 登录时得到的token
times	是	string 格式：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
decimal	否	Integer 返回数值小数点后位数，取值范围0~9
valueonly	否	Integer 是否只返回值，取值范围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

返回示例


x
{
    "code": 0,
    "items": [
        {
            "name": "A1.PV",
            "vals": [
                {
                    "time": "2022-02-22T14:22:33.444",
                    "val": 50
                },
                {
                    "time": "2022-02-22T15:22:34.555",
                    "val": 60
                }
            ]
        },
        {
            "name": "A2.DESC",
            "vals": [
                {
                    "time": "2022-02-22T14:22:33.444",
                    "val": "第二个点"

                },
                {
                    "time": "2022-02-22T15:22:34.555",
                    "val": "第二个点"
                }
            ]
        }
    ]
}

示例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


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "name": "A1.PV",
            "vals": [
                50,
                60
            ]
        },
        {
            "name": "A2.DESC",
            "vals": [
                "第二个点",
                "第二个点"
            ]
        }
    ]
}

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

URL: /api/hisdata

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

查询参数

参数	必须	说明
token	否（开启安全管理后必要）	string 登录时得到的token
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:58.333
interval	是	integer 间隔时间毫秒值，2500代表2.5秒
names	是	点名带属性，多个值逗号隔开，如：A1.PV,A2.DESC
valueonly	否	Integer 是否只返回值，取值范围0或1，数字1代表开启"只返回值"模式，这种模式下，响应体中的数据会十分精简，适合获取的数据量很大，追求极快返回速度的情况。返回的值以数组形式表示，按时间先后排序，详见示例2
decimal	否	Integer 返回数值小数点后位数，取值范围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的方式请求


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "name": "A1.PV",
            "vals": [
                {
                    "time": "2022-02-22T15:22:34",
                    "val": 50
                },
                {
                    "time": "2022-02-22T15:22:35",
                    "val": 51
                },
                {
                    "time": "2022-02-22T15:22:36",
                    "val": 52
                }
            ]
        },
        {
            "name": "A2.DESC",
            "vals": [
                {
                    "time": "2022-02-22T15:22:34",
                    "val": "第二个点"
                },
                {
                    "time": "2022-02-22T15:22:35",
                    "val": "第二个点"
                },
                {
                    "time": "2022-02-22T15:22:36",
                    "val": "第二个点xxxx"
                }
            ]
        }
    ]
}

示例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


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "name": "A1.PV",
            "vals": [50,51,52]
        },
        {
            "name": "A2.DESC",
            "vals": ["第二个点","第二个点","第二个点xxxx"]
        }
    ]
}

数组内值的顺序与时间顺序一致，即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

请求体：


xxxxxxxxxx
{
    "items": [
        {
            "name": "A1.PV",
            "vals": [
                {
                    "time": "2022-02-22T15:22:34.555",
                    "val": 50
                },
                {
                    "time": "2022-02-22T15:22:35.555",
                    "val": 51
                }
            ]
        },
        {
            "name": "A2.DESC",
            "vals": [
                {
                    "time": "2022-02-22T15:22:34.555",
                    "val": "第二个点"
                },
                {
                    "time": "2022-02-22T15:22:35.555",
                    "val": "第二个点"
                }
            ]
        }
    ]
}

返回示例

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


xxxxxxxxxx
{
    "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

请求体：


xxxxxxxxxx
{
    "query": "select name, pv, euhi from realdata where kind<250"
}

返回示例

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


xxxxxxxxxx
{
    "code": 0,
    "euhi": [
        100,
        100,
        100,
        100,
        100,
        100,
        100
    ],
    "name": [
        "a1",
        "a2",
        "a3",
        "a4",
        "a5",
        "a6",
        "a7"
    ],
    "pv": [
        -9999,
        -9999,
        -9999,
        -9999,
        -9999,
        -9999,
        -9999
    ]
}

15. 获取报警【GET】

URL: /api/alarmdata

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

查询参数

参数	必须	说明
token	否（开启安全管理后必要）	string 登录时得到的token
realalmcount	否	Integer 最多取得的条数
org	否	string 指定要查询的点所在目录
unit	否	Integer 指定要查询的点所在单元
level	否	Integer 报警优先级，获取不小于该级别的报警
tags	否	string 点名列表，多个点逗号隔开，如A1,A2,A3
groupbytag	否	Integer 是否按点名分组，为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

返回示例

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


xxxxxxxxxx
{
    "code": 0,
    "items": [
        {
            "ack": 2,
            "cat": 38,
            "desc": "",
            "eu": "",
            "group": "root.groupB",
            "level": 1,
            "limit": 80,
            "name": "B2",
            "oper": "",
            "parno": 38,
            "prio": 1,
            "time": "2022-03-23T13:32:37",
            "unit": 0,
            "val": 89.400000000000006
        },
        {
            "ack": 2,
            "cat": 36,
            "desc": "",
            "eu": "",
            "group": "root.groupA",
            "level": 2,
            "limit": 10,
            "name": "A1",
            "oper": "",
            "parno": 36,
            "prio": 2,
            "time": "2022-03-23T13:32:37",
            "unit": 0,
            "val": 3.5
        }
    ]
}

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 点值