1 概述

本文主要介绍ThingJS-X产品目前提供几大内置接口的标准规范，在数据接入时，可以直接按照字段要求推送至系统中。主要包括资产数据、性能数据、告警数据、图表数据的接入格式、方法等内容，详细内容见以下章节。

2 资产数据接口

2.1 批量更新或保存资产数据

2.1.1 接口描述

资产数据的接入可以调用批量更新或保存CI信息接口，按照格式传值，可以将资产信息保存至ThingJS-X系统中。

2.1.2 接口调用方法

接口请求方式：POST
认证方式：无认证
请求url地址：http://{IP}:{PORT}/thing/dix/saveOrUpdateCiBatch
请求参数说明

参数名	类型	说明	样例数据	备注
cilist	array	要保存的CI详细信息List	参考请求示例中cilist的样例	分类中勾选的必填项在cilist中必须包含，否则会入库失败，默认必填项有编号、名称、所属、设备型号
className	String	要保存的CI分类信息	门禁设备
returnSucessPks	boolean	保存成功后是否返回业务主键

请求示例

{
    "cilist": [
        {
            "编号": "门禁6",
            "名称": "门禁6",
            "所属":"智慧产业园_PARK",
            "设备型号":"RF-AX-50-TN",
            "厂商": "立方"
        },
        {
            "编号": "门禁7",
            "名称": "门禁7",
            "所属":"智慧产业园_PARK",
            "设备型号":"RF-AX-50-TN",
            "厂商": "立方"
        }
    ],
    "className": "设备",
    "returnSucessPks": false
}

返回参数

参数名	类型	说明
code	integer(int32)	请求结果状态码-1表示成功，500表示失败
data	object	本次推送结果详情
success	boolean	请求结果是否成功

返回示例

{
    "code": -1,
    "data": "本次保存分类【设备】下CI数据,总数【2】；成功【2】,失败【0】，忽略【0】；新增【2】，更新【0】。",
    "success": true
}

2.2 通过业务主键批量删除对象

2.2.1 接口描述

资产设备的下架和删除，可以通过调用通过传业务主键的方式删除设备，每次可以传多个值，按照格式传值，可以将ThingJS-X系统中的设备整条信息删除。

2.2.2 接口调用方法

接口请求方式：POST
认证方式：无认证
请求url地址：http://{IP}:{PORT}/thing/dix/deleteCis
请求参数说明

参数名	类型	说明	样例数据	备注
无，直接传list	array	需要删除的设备业务主键，业务主键为ThingJS-X中勾选项	[[“业务主键”]]

请求示例

[
    [
        "门禁4"
    ],
    [
        "门禁5"
    ]
]

返回参数

参数名	类型	说明
code	integer(int32)	请求结果状态码 -1表示成功，500表示失败
data	object	删除的对象信息
delete	string	显示删除的业务主键及数据
success	boolean	请求结果是否成功

返回示例

{
    "code": -1,
    "data": {
        "delete": [
            [
                "门禁7"
            ],
            [
                "门禁6"
            ]
        ]
    },
    "success": true
}

2.3 通过单个属性信息查询CI

2.3.1 接口描述

在资产更新时，通常需要查询系统中某个孪生体分类中某个孪生体详细的信息，此时可以使用如下接口指定查询分类和查询名称及查询值，准确查询到想要的数据。

2.3.2 接口调用方法

接口请求方式：POST
认证方式：无认证
请求url地址：http://{IP}:{PORT}/thing/dix/getByAttr
请求参数说明

参数名	类型	说明	样例数据
attrName	string	需要查询的属性名称	编号
attrValue	string	需要查询的属性名称对应的值	门禁01
className	string	需要查询的指定分类的名称	门禁设备

图片1.png

请求示例

   {
     "attrName": "编号",
     "attrValue": "门禁01",
     "className": "门禁设备"
   }

返回参数

参数名	类型	说明
code	integer(int32)	请求结果状态码 -1表示成功，500表示失败
data	Object	删除的对象信息
success	boolean	请求结果是否成功
classId	integer(int64)	孪生体分类DI
ciCode	string	孪生体cicode
object	Object	其中包含所有孪生体属性信息

返回示例

{
    "code": -1,
    "data": {
        "classId": 8734830748950277,
        "ciCode": "8717362404510748",
        "hashCode": 1247965298,
        "ciPrimaryKey": "[\"门禁01\"]",
        "time": 20220222115540,
        "id": 8717362404517738,
        "object": {
            "_TYPE_": "STANDALONEDEVICE",
            "_DATASOURCES_": "WEBEDIT",
            "名称": "侧门门禁",
            "设备型号": "海康_人脸识别门禁1",
            "_ANGLE_": "0",
            "编号": "门禁01",
            "_SIZE_": "[]",
            "_MODELTYPE_": "Thing",
            "所属": "B23A_PARK",
            "_UUID_": "0F8009FC-7289-4ADE-AAAA-8D775618CA82",
            "_SCALE_": "[0.957,0.979,1.143]",
            "标签": "反向控制",
            "_OFFSET_": "[-1.572,1.65,2.806]",
            "_DATAFROM_": "WEBEDIT",
            "_MODELID_": "3222e24ae67c4a5399b4af5578e796e3",
            "_VERSION_": "0"
        }
    },
    "success": true
}

2.4 根据孪生体分类名称分页查询所有孪生体信息

2.3.1 接口描述

在资产更新时，除了每个孪生体属性信息单独查询，还可以根据孪生体分类名称分页查询孪生体数据。

2.3.2 接口调用方法

接口请求方式：POST
认证方式：无认证
请求url地址：http://{IP}:{PORT}/thing/dix/getCiPageByClassName
请求参数说明

参数名	类型	说明	样例数据	备注
className	string	需要查询的孪生体分类名称	门禁管理
pageNum	integer(int32)	页码	1	查询的第1页
pageSize	integer(int32)	每页数量	10	每页返回10条数据

请求示例

{
  "className": "门禁设备",
  "pageNum": 1,
  "pageSize": 10
}

返回参数

参数名	类型	说明
code	integer(int32)	请求结果状态码 -1表示成功，500表示失败
data	List	返回的所有CI信息
data	Object	每个CI一个对象
success	boolean	请求结果是否成功
classId	integer	孪生体分类DI
ciCode	string	孪生体cicode
object	Object	其中包含所有孪生体属性信息
totalPages	integer(int64)	查询总页数
pageNum	integer(int64)	第几页
pageSize	integer(int64)	每页数量
totalRows	integer(int64)	一共查询得到的条数

返回示例

{
    "code": -1,
    "data": {
        "data": [
            {
                "classId": 8734830748950277,
                "ciCode": "8692061475752172",
                "hashCode": 1247995089,
                "ciPrimaryKey": "[\"门禁02\"]",
                "time": 20220216150751,
                "id": 8717362404517739,
                "object": {
                    "_TYPE_": "STANDALONEDEVICE",
                    "_DATASOURCES_": "WEBEDIT",
                    "名称": "正门门禁",
                    "设备型号": "B23A_正门人脸识别",
                    "_ANGLE_": "-41",
                    "编号": "门禁02",
                    "_SIZE_": "[]",
                    "_MODELTYPE_": "Thing",
                    "所属": "地面",
                    "_UUID_": "370843DA-0C89-4412-B721-CA33E0C83251",
                    "_SCALE_": "[1.022,1.002,1.022]",
                    "标签": "",
                    "_OFFSET_": "[-17.02329492733433,-6.699590854739312E-4,-1.8092446899672594]",
                    "_DATAFROM_": "WEBEDIT",
                    "_MODELID_": "d8c97184ff694b1a82b63ddcb8dd3418",
                    "_VERSION_": "0"
                }
            }
        ],
        "totalPages": 1,
        "pageSize": 10,
        "totalRows": 1,
        "pageNum": 1
    },
    "success": true
}

3 性能数据接口

3.1 接口描述

性能数据推送可以调用系统中内置的restAPI接口，可以通过接口程序直接将处理好的设备性能数据(如温湿度、门禁状态、电梯运行状态)推送至ThingJS-X系统中，推送格式需要符合接口约定的字段规范。

3.2 接口调用方法

接口请求方式：POST
认证方式：无认证
请求url地址：http://{IP}:{PORT}/thing/dix/monitor/performance
请求参数说明

参数名	类型	说明	样例数据	备注
cikey/ciname	String	勾选业务主键属性对应的value值/系统自动生成的CICode主键ID	温湿度传感器01/7009614792851623	两个参数二选一即可
kpi_name	String	指标名称	湿度
val	String	指标值	60
unit	String	指标单位	℃

cikey与ciname描述如下

请求示例

[
    {
        "cikey": "温湿度传感器01",
        "kpi_name": "湿度",
        "val": "60",
        "unit":"℃"
    }
]

返回参数

参数名	类型	说明
code	integer(int32)	请求结果状态码-1表示成功，500表示失败
data	boolean	本次推送结果true/false
success	boolean	请求结果是否成功

返回示例

{
    "code": -1,
    "data": true,
    "success": true
}

4 告警数据接口

4.1 接口描述

告警数据推送可以调用系统中内置的restAPI接口，可以通过接口程序直接将处理好的设备告警数据(如CPU、门磁告警等)推送至ThingJS-X系统中，推送格式需要符合接口约定的字段规范。

4.2 接口调用方法

接口请求方式：POST
认证方式：无认证
请求url地址：http://{IP}:{PORT}/thing/dix/monitor/alarm
请求参数说明

参数名	类型	说明	样例数据	备注
cikey/ciname	String	勾选业务主键属性对应的value值/系统自动生成的CICode主键ID	服务器01/7009614792851623	两个参数二选一即可
severity	String	告警等级	1
status	String	告警状态	1	1开启/2关闭
kpiname	String	指标名称	CPU
summary	String	告警信息	CPU使用率超过90%，已连续发生超过3次
others	String	拓展字段,自定义内容
lasttime	String	告警最后一次发生时间	2020-07-29 09:33:06

请求示例

[
    {
        "cikey": "服务器01",
        "severity": 1,
        "status": 1,
        "kpiname": "CPU",
        "summary": "CPU使用率超过90%，已连续发生超过3次",
        "others": "这是一段自定义文本",
        "lasttime": "2020-07-29 09:33:06"
    }
]

返回参数

参数名	类型	说明
code	integer(int32)	请求结果状态码-1表示成功，500表示失败
data	boolean	本次推送结果true/false
success	boolean	请求结果是否成功

返回示例

{
    "code": -1,
    "data": true,
    "success": true
}

5 业务图表数据接口

5.1 通用图表说明

ThingJS-X系统中大多数图表配置方式类似，包括如下几大部分：标题名称及是否显示标题设置、显示图例及坐标轴设置、图表样式设置、图表数据对接、传参设置等，图表的基本信息及样式可参考图表配置说明，以下主要介绍通用图表的数据对接方式。

5.1.1 接口数据流图

实施工艺流程图-通用图表接口数据流图.png

5.1.2 图表样式

以下使用一个图表进行举例

5.1.3 图表样例数据

主要查询图表要求的样例数据，方便后续封装httpserver时使用

数据类型：选择静态数据；
静态数据：静态数据中的样例即为httpserver端口需要返回的数据格式；

5.1.4 图表配置方法（httpclient端）

数据类型：选择API的方式就行数据对接，表示使用http请求外部接口返回的数据；
接口地址：调用外部httpserver端的URL地址；
接口标识：一个接口有多组图表数据时，区分该图表数据的标识；
接口参数：图表需要给httpserver提供的参数，传入参数后，httpserver端可以获取到对应参数信息。利用图表参数传来的信息，可以通过一个DIX接口，根据不同的参数返回多个图表的数据，此处测试填写为”abc”；
更新频率：图表请求接口的频率，单位毫秒，例如1000表示每秒请求一些server端；

5.1.5 接口配置方法（httpserver端）

httpserver服务主要通过DIX或其他接口程序提供。本文档主要使用DIX工具创建一个httpserver端进行举例；

在6.1.3中了解到图表要求传入的数据格式如下

在DIX中创建httpserver端口

填写名称及必要的参数信息

接口示例

function run(args){
    //客户端发送的请求参数为args,若需要有返回值在代码末尾添加return"字符类型数据"
    logger.info("获取的参数为---》》" + args);
    varlist = [
        12,
        32,
        11,
        14,
        90
    ];

    logger.info("====list=======" + JSON.stringify(list));
    return list;
}

DIX接口中返回的日志，可以看到参数abc，为key,value形式，levelId为默认返回，表示ThingJS-X当前所属层级，图表在不同层级可以返回不同的levelId，DIX中可以判断此参数返回不同层级的统计数据，图表即可以在不同层级显示不同数据。

接口单独使用postman调用返回的参数，包含data层，实际Proxiam会直接获取data里的内容

参数名	类型	说明
code	integer(int32)	请求结果状态码-1表示成功，500表示失败
data	对象或数组转换后的字符串	图表中需要用到的数据
success	boolean	请求结果是否成功

返回示例

{
    "code": 200,
    "data": "[22,34,44]",
    "status": "success"
}

5.2 告警信息图表说明

5.2.1 接口数据流图

5.2.2 图表样式

以下为告警信息列表图表

5.2.3 图表配置方法

告警信息列表图表不需要单独使用接口推送数据，数据来源于推送的告警数据，只需要配置相关参数，以下主要介绍重点参数配置方法，其他参数根据理解填写即可；

5.2.3.1 展示指定业务告警设备

上图”展示业务分类“中填写的信息为孪生体中，属性名称为“业务分类”的对应value值，默认不填信息显示所有设备告警信息；
例如孪生体分类为“照明设备”，在照明设备中增加一个属性字段为“业务分类”的字段，注意必须为这个字段，属性值为自定义，可以理解为，把某一个业务相关的物联网设备使用同一个告警列表展示和这个业务相关的设备告警信息。孪生体分类中设置如下：

上图的属性值为“智慧照明”，对应图表中的“展示业务分类”填写为“智慧照明”；

5.2.3.2 告警处理与关闭

显示”处理按钮”：在告警图表中配饰是否显示处理告警按钮；
“处理”按钮执行事件，此处需要填写调用httpserver的地址和脚本方法，点击调用后，httpserver会收到设备或者ID传入的参数信息，再根据需要增加处理告警逻辑，httpserver可以使用DIX进行封装，此处页面配置调用代码如下：

function(obj){
    console.log(obj)
    const url = 'http://192.168.21.204:10012/http/rest/alarm/close?'+'param1='+obj.ALARMLIST[0]+'&param2=处理';
    fetch(url, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json;charset=UTF-8'
        }
    })
}

注：http://192.168.21.204:10012/http/rest/alarm/close部分需要填写实际需要调用的httpserver的地址，httpserver需要设置GET请求；
ALARMLIST为返回给httpserver的参数；

下一篇什么是数据对接?