当客户问我“你们组态软件有没有Rest API时”

13.1Rest服务

REST服务是基于REST规范，能够对外提供包括实时数据、历史数据以及报警数据等实时数据库数据的接口服务。

在IDE中切换至“数据库”选项卡，展开“对外服务”，点击“REST服务”，显示REST服务的配置画面：

图{ STYLEREF 1 \s |39}‑{ SEQ Figure \* ARABIC \s 1 |158} Rest服务配置

启用REST服务：是否启用REST服务，勾选后在运行时会启动REST服务程序Rest Service。

实时数据库在远程：REST服务程序可以与实时数据库分离部署。勾选后此项后，REST服务即可连接远程实时数据库。

IP地址：远程实时数据库的IP地址。

IP端口：远程实时数据库的服务端口。

启用缓存：是否启用REST缓存。勾选此项时需要在数据库下的对外发布数据项-REST中配置对外发布的变量。启用此项后，REST服务程序会缓存发布项中配置的数据库变量的实时值，当客户端取实时数据时会直接访问缓存中的数据，减小实时数据库的数据吞吐量，提高REST的实时数据访问速度。

注意：使用此种方式访问实时数据时，不受数据库点的安全限制。

图{ STYLEREF 1 \s |39}‑{ SEQ Figure \* ARABIC \s 1 |159} Rest服务-对外发布数据项配置

数据更新周期：REST缓存数据的周期。

服务端口：REST服务程序的服务端口，客户端需使用此端口连接REST服务程序。

报文加密方式：是否启用报文加密，支持不加密、BASE64以及BASE64（URL）三种方式。

处理线程数量：REST服务与实时数据库通讯时使用多少线程，此项要结合实时数据库的最大线程数、实时数据库和REST服务所在的机器的CPU的线程数量进行合理设置。

任务处理方式：REST服务的任务处理方式：

自动：根据REST服务的负载情况动态调整任务处理策略。

并行处理：始终并行处理REST任务。

串行处理：始终串行处理REST任务。

Token超过用户锁屏时限后失效：是否启用用户登录后Token的有效期。启用后，用户的Token有效期与用户的锁屏时限相同。

显示访问信息：在REST服务程序中是否显示REST客户端的访问信息。

13.2监控组态软件Rest API

13.2.1综述

13.2.1.1开启Rest

Rest API需授权并手动开启：

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

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

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

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

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

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

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

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

13.2.1.2常见问题

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

l请检查请求URL中路径拼写。

l请检查对外发布数据项中是否有此节点。可能节点结构复杂，遗漏或误删了某节点。

l请检查点的访问权限。

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

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

13.2.2用户登录【GET】

URL: /api/userlogin

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

13.2.2.1查询参数

13.2.2.2示例

13.2.2.2.1请求示例

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

13.2.2.2.2返回示例

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

13.2.3用户登出【GET】

URL: /api/userlogout

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

13.2.3.1查询参数

13.2.3.2示例

13.2.3.2.1请求示例

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

13.2.3.2.2返回示例

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

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

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

URL：/api/realdata

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

13.2.4.1查询参数

13.2.4.2示例1

13.2.4.2.1请求示例1

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

13.2.4.2.2返回示例1

{"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":"第三个点"}]}

13.2.4.3示例2（valueonly模式）

13.2.4.3.1请求示例2

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

13.2.4.3.2返回示例2

{"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":["第一个点的描述",                  "第二个点的描述",                  "第三个点的描述"]}

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

URL: /api/realdata

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

13.2.5.1查询参数

13.2.5.2示例1

13.2.5.2.1请求示例1

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

13.2.5.2.2返回示例1

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

13.2.5.3示例2（valueonly模式）

13.2.5.3.1请求示例2

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

13.2.5.3.2返回示例2

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

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

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

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

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

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

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

13.2.6.1路径参数

13.2.6.2查询参数

13.2.6.3示例1

13.2.6.3.1请求示例1

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

13.2.6.3.2返回示例1

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

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

13.2.6.4示例2

13.2.6.4.1请求示例2

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

13.2.6.4.2返回示例2

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

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

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

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

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

13.2.7.1路径参数

13.2.7.2查询参数

13.2.7.3示例1

13.2.7.3.1请求示例1

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

13.2.7.3.2返回示例1

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

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

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

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

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

13.2.7.4示例2（递归）

13.2.7.4.1请求示例2

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

13.2.7.4.2返回示例2

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

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

13.2.7.5示例3（valueonly）

13.2.7.5.1请求示例3

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

13.2.7.5.2返回示例3

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

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

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

URL: /api/realdata

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

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

13.2.8.1查询参数

13.2.8.2示例

13.2.8.2.1请求示例

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

13.2.8.2.2返回示例

{"code":0}

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

URL: /api/realdata

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

13.2.9.1查询参数

13.2.9.2示例

13.2.9.2.1请求示例

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

13.2.9.2.2返回示例

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

13.2.10设置实时数据【POST】

URL: /api/realdata

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

13.2.10.1查询参数

13.2.10.2示例

13.2.10.2.1请求示例

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

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

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

13.2.10.2.2返回示例

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

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

13.2.11设置实时数据（数组方式）【POST】

URL: /api/realdata

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

13.2.11.1查询参数

13.2.11.2示例

13.2.11.2.1请求示例

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

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

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

13.2.11.2.2返回示例

{"code":0}

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

URL: /api/hisdata

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

13.2.12.1请求参数

13.2.12.2示例1

13.2.12.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

13.2.12.2.2返回示例

{"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":"第二个点"}]}]}

13.2.12.3示例2（valueonly）

13.2.12.3.1请求示例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

13.2.12.3.2返回示例2

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

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

URL: /api/hisdata

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

13.2.13.1查询参数

13.2.13.2示例1

13.2.13.2.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

13.2.13.2.2返回示例1

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

{"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"}]}]}

13.2.13.3示例2（valueonly）

13.2.13.3.1请求示例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

13.2.13.3.2返回示例2

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