ThingJS-X项目对外标准接口规范(V3.0~3.5)

18801187951(338465)发表于:2022年04月17日 22:33:23更新于:2022年06月20日 09:40:25

1 概述

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

2 资产数据接口

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

2.1.1 接口描述

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

2.1.2 接口调用方法

  • 接口请求方式:POST

  • 认证方式:无认证

  • 请求url地址:http://{IP}:{PORT}/thing/dix/saveOrUpdateCiBatch

  • 请求参数说明



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


  • 请求示例

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



参数名类型说明
codeinteger(int32)请求结果状态码-1表示成功,500表示失败
dataobject本次推送结果详情
successboolean请求结果是否成功


  • 返回示例

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

  • 请求参数说明



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


  • 请求示例

[
    [
        "门禁4"
    ],
    [
        "门禁5"
    ]
]
  • 返回参数



参数名类型说明
codeinteger(int32)请求结果状态码 -1表示成功,500表示失败
dataobject删除的对象信息
deletestring显示删除的业务主键及数据
successboolean请求结果是否成功


  • 返回示例

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

  • 请求参数说明



参数名类型说明样例数据备注
attrNamestring需要查询的属性名称编号
attrValuestring需要查询的属性名称对应的值门禁01
classNamestring需要查询的指定分类的名称门禁设备


图片1.png

  • 请求示例

   {
     "attrName": "编号",
     "attrValue": "门禁01",
     "className": "门禁设备"
   }
  • 返回参数



参数名类型说明
codeinteger(int32)请求结果状态码 -1表示成功,500表示失败
dataObject删除的对象信息
successboolean请求结果是否成功
classIdinteger(int64)孪生体分类DI
ciCodestring孪生体cicode
objectObject其中包含所有孪生体属性信息


  • 返回示例

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

  • 请求参数说明



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


  • 请求示例

{
  "className": "门禁设备",
  "pageNum": 1,
  "pageSize": 10
}
  • 返回参数



参数名类型说明
codeinteger(int32)请求结果状态码 -1表示成功,500表示失败
dataList返回的所有CI信息
dataObject每个CI一个对象
successboolean请求结果是否成功
classIdinteger孪生体分类DI
ciCodestring孪生体cicode
objectObject其中包含所有孪生体属性信息
totalPagesinteger(int64)查询总页数
pageNuminteger(int64)第几页
pageSizeinteger(int64)每页数量
totalRowsinteger(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/cinameString勾选业务主键属性对应的value值/系统自动生成的CICode主键ID温湿度传感器01/7009614792851623两个参数二选一即可
kpi_nameString指标名称湿度
valString指标值60
unitString指标单位


  • cikey与ciname描述如下

image.png

image.png

  • 请求示例

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



参数名类型说明
codeinteger(int32)请求结果状态码-1表示成功,500表示失败
databoolean本次推送结果true/false
successboolean请求结果是否成功


  • 返回示例

{
    "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/cinameString勾选业务主键属性对应的value值/系统自动生成的CICode主键ID服务器01/7009614792851623两个参数二选一即可
severityString告警等级1
statusString告警状态11开启/2关闭
kpinameString指标名称CPU
summaryString告警信息CPU使用率超过90%,已连续发生超过3次
othersString拓展字段,自定义内容

lasttimeString告警最后一次发生时间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"
    }
]
  • 返回参数



参数名类型说明
codeinteger(int32)请求结果状态码-1表示成功,500表示失败
databoolean本次推送结果true/false
successboolean请求结果是否成功


  • 返回示例

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

5 业务图表数据接口

5.1 通用图表说明

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

5.1.1 接口数据流图

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

5.1.2 图表样式

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

5.1.3 图表样例数据

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

image.png

  • 数据类型:选择静态数据;

  • 静态数据:静态数据中的样例即为httpserver端口需要返回的数据格式;

5.1.4 图表配置方法(httpclient端)

image.png

  • 数据类型:选择API的方式就行数据对接,表示使用http请求外部接口返回的数据;

  • 接口地址:调用外部httpserver端的URL地址;

  • 接口标识:一个接口有多组图表数据时,区分该图表数据的标识;

  • 接口参数:图表需要给httpserver提供的参数,传入参数后,httpserver端可以获取到对应参数信息。利用图表参数传来的信息,可以通过一个DIX接口,根据不同的参数返回多个图表的数据,此处测试填写为”abc”;

  • 更新频率:图表请求接口的频率,单位毫秒,例如1000表示每秒请求一些server端;

5.1.5 接口配置方法(httpserver端)

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

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

[
    22,
    34,
    44
]

在DIX中创建httpserver端口
image.png

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

接口示例
image.png

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中可以判断此参数返回不同层级的统计数据,图表即可以在不同层级显示不同数据。

image.png

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



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


  • 返回示例

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

5.2 告警信息图表说明

5.2.1 接口数据流图

image.png

5.2.2 图表样式

以下为告警信息列表图表

image.png

5.2.3 图表配置方法

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

5.2.3.1 展示指定业务告警设备

image.png

  • 上图”展示业务分类“中填写的信息为孪生体中,属性名称为“业务分类”的对应value值,默认不填信息显示所有设备告警信息;

  • 例如孪生体分类为“照明设备”,在照明设备中增加一个属性字段为“业务分类”的字段,注意必须为这个字段,属性值为自定义,可以理解为,把某一个业务相关的物联网设备使用同一个告警列表展示和这个业务相关的设备告警信息。孪生体分类中设置如下:

image.png

image.png

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

5.2.3.2 告警处理与关闭

image.png

  • 显示”处理按钮”:在告警图表中配饰是否显示处理告警按钮;

  • “处理”按钮执行事件,此处需要填写调用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的参数;


    您需要登录后才可以回复