### 术语说明: #### 对象 基于数据字典类型和信息点定于创建的实例 ``` 数据字典默认每个类型都有id、name、localId、localName，需要项目和应用在数据字典服务中订阅 id、name、localId、localName对应原来的（如设备）EquipID、EquipName、EquipLocalID、EquipLocalName，值也相同，修改一方会同时修改另一方（无论是否订阅另一方） 长期计划来讲数据字典和物理世界将取消（如设备）EquipID、EquipName、EquipLocalID、EquipLocalName这类信息点，对象统一使用id、name、localId、localName ``` #### 关系 ``` 对象之间的关系,一般由4个字段组成:graphId, rel, from, to ``` ### 字段约定 | 字段 | 说明 | 备注 | | -------- | ----------------------------- | ---- | | objectId | 对象id | | | classCode | 类型编码 | | | graphId | 关系数据字段,图实例id | | | rel | 关系数据字段,边类型 | | ### 数据结构 对象 object | 字段 | 数据类型 | 说明 | | ---------- | -------- | --------------------------------------------------------- | | id | String | id，全局唯一 | | projectId | String | 项目id，不可为空 | | classCode | String | 类型code，不可为空 | | 其他信息点编码 | 根据信息点定义 | | | | | | 关系 relation | 字段 | 数据类型 | 说明 | | ---------- | -------- | --------------------------------------------------------- | | graphId | String | 图实例id | | rel | String | 边类型 | | from | String | 对象id | | to | String | 对象id | | infos | Object | 关系附加信息 | | ### 接口 #### 通用参数 传参方式: 拼接在url后 | 参数名 | 数据类型 | 说明 | | ---------- | -------- | ------------------------- | | projectId | String | 项目id,不可为空 | | appId | String | 应用id,不可为空 | | | | | #### 基础接口: 创建对象 接口说明 ``` 根据projectId 和 appId 从数据字典查询出已订阅的信息点清单list, 并根据信息点清单list对入参数据进行合法性校验 不在信息点清单list中的参数将被忽略 该接口为批量创建接口，只有全部对象创建成功才会返回成功，不存在部分成功部分失败的情况 ``` 请求地址 ``` POST: /object/create ``` 请求参数 ``` [ { "classCode": "类型编码,不可为空", "信息点编码": "值" } ] ``` 返回内容 ``` { "result": "success", "message": "错误信息,如果接口发生错误会返回该字段" } ``` #### 基础接口: 更新对象 接口说明 ``` 根据projectId 和 appId 从数据字典查询出已订阅的信息点清单list, 信息点编码即为入参字段名，并根据信息点清单list对入参数据进行合法性校验 不在信息点清单list中的入参字段将被忽略 两组(id和（classCode，EquipID))参数必须传一组(本例中EquipID对应设备ID,其他如ProjID对应项目ID等) ``` 请求地址 ``` POST: /object/update ``` 请求参数 ``` [ { "id": "对象id", "classCode": "类型编码,不可为空", "信息点编码": "值" } ] ``` 返回内容 ``` { "result": "success", "message": "错误信息,如果接口发生错误会返回该字段" } ``` #### 基础接口: 删除对象 接口说明 ``` 删除id对应的对象 id不存在时将被忽略 ``` 请求地址 ``` POST: /object/delete ``` 请求参数 ``` [ "id1", "id2", "id3"] ``` 返回内容 ``` { "result": "success", "message": "错误信息,如果接口发生错误会返回该字段" } ``` #### 基础接口: 查询对象 接口说明 ``` 参考通用查询接口 查询字段和排序字段必须是项目和应用订阅了的信息点对应的字段 返回的字段为项目和应用已订阅的信息点字段 ``` 请求地址 ``` POST: /object/query ``` 请求参数 ``` { "criteria": { "classCode": "ACCCOT" }, "orders": [ { "column": "createTime", "asc": true } ], "page": 1, "size": 10 } ``` 返回内容 ``` { "result": "success", "count": 12, "data": [ { "信息点编码": "值" } ] "message": "错误信息,如果接口发生错误会返回该字段" } ``` #### 基础接口: 查询图实例 接口说明 ``` 目前图实例是内置数据,仅提供查询 ``` 请求地址 ``` POST /graph/query ``` 请求参数 ``` { "criteria": { "graphType": "ArchSubset" } } ``` 返回内容 ``` { "result" : "success", "data" : [ { "id" : "GtArchSubset001", "projectId" : "Pj3203020001", "graphType" : "ArchSubset", "sequenceId" : "001", "valid" : true, "createTime" : "20200519140942" } ] } ``` #### 基础接口: 创建关系 接口说明 ``` 该接口是批量创建接口 调用时需确保每一项的数据正确,如果有任意一个或多于一个元素存在错误则返回报错,同时参数正确的数据也不会保存 同样的参数可以调用多次,如果参数对应的关系已存在则覆盖更新 需要确保使用的graphId和rel是最新版字典定义的数据,接口会对graphId和rel进行校验(目前未校验) ``` 请求地址 ``` POST: /relation/save ``` 请求参数 ``` [ { "graphId" : "ddd", "rel" : "atob", "from" : "Sp320302000147eab664592c4a818bc5aebf8ad88f91", "to" : "Si3203020001e86cab26efdc11e9872a55fddb5ea8bb" }, { "graphId" : "ddd", "rel" : "atob", "from" : "Sp320302000147eab664592c4a818bc5aebf8ad88f91", "to" : "Si32030200016f0b820a1a8c11eaac5ab725fa2ffefc" } ] ``` 返回内容 ``` { "result" : "fail", "message" : "参数错误", "data" : [ { "result" : "success", "target" : { "graphId" : "ddd", "rel" : "atob", "from" : "Sp320302000147eab664592c4a818bc5aebf8ad88f91", "to" : "Si3203020001e86cab26efdc11e9872a55fddb5ea8bb" } }, { "result" : "error", "target" : { "graphId" : "ddd", "rel" : "atob", "from" : "Sp320302000147eab664592c4a818bc5aebf8ad88f91", "to" : "abc" }, "error" : "to对象Id[abc]不存在;" } ] } ``` #### 基础接口: 删除关系 接口说明 ``` 该接口是批量删除接口 调用时需确保每一项的数据正确,如果有任意一个或多于一个元素存在错误则返回报错,同时参数正确的数据也不会处理 根据入参删除一个或多个关系实例 请务必明确入参逻辑 ``` 请求地址 ``` POST /relation/delete ``` 请求参数 ``` [ { "graphId" : "ddd", "rel" : "atob", "from" : "Sp320302000147eab664592c4a818bc5aebf8ad88f91" }, { "graphId" : "ddd", "rel" : "atob", "to" : "Si32030200016f0b820a1a8c11eaac5ab725fa2ffefc" } ] ``` 返回内容 ``` { "result" : "success", "data" : [ { "result" : "success", "target" : { "graphId" : "ddd", "rel" : "atob", "from" : "Sp320302000147eab664592c4a818bc5aebf8ad88f91" }, "deletedCount" : 2 }, { "result" : "success", "target" : { "graphId" : "ddd", "rel" : "atob", "to" : "Si32030200016f0b820a1a8c11eaac5ab725fa2ffefc" }, "deletedCount" : 0 } ], "totalDeletedCount" : 2 } ``` 返回内容说明 | 字段名 | 数据类型 | 说明 | | ---------- | -------- | ------------------------- | | data.deletedCount | Integer | 单个参数对应删除的关系的数量 | | totalDeletedCount | Integer | 所有参数对应删除的关系的数量 | | | | | #### 基础接口: 查询关系 接口说明 ``` 不支持分页! from和to必须且只能传一个 withColumns:infos, infos是关系附件的数据, 如果不传则不返回infos ``` 请求地址 ``` POST: /relation/query ``` 请求参数 ``` { "criteria": { "graphId": "GtElementSpNeighborhood001", "rel": "10", "from": "Eq3203020001e945bebd9b1447b9859638810e7d6147", "to": { "$in":[ "Sp320302000151a095a44c1d4fd7930d2f87d38cdf77", "Sp32030200010b1d106c4a6d45698c781bf7356df8ba ] } }, "withColumns": ["infos"] } ``` 返回内容 ``` { "result": "success", "data": [ { "graphId": "GtElementSpNeighborhood001", "rel": "10", "from": "Eq3203020001e945bebd9b1447b9859638810e7d6147", "to": "Sp320302000151a095a44c1d4fd7930d2f87d38cdf77" }, { "graphId": "GtElementSpNeighborhood001", "rel": "10", "from": "Eq3203020001e945bebd9b1447b9859638810e7d6147", "to": "Sp32030200010b1d106c4a6d45698c781bf7356df8ba" } ] "message": "错误信息,如果接口发生错误会返回该字段" } ``` #### 基础接口: 查询关系对象 接口说明 ``` 根据关系查询对象 不支持分页! from和to必须且只能传一个, 如果传from同时可以传toClassCode, 如果传to同时可以传fromClassCode 如果不传withColumns则查询到的对象默认只返回id, name, localId, localName, classCode ``` 请求地址 ``` POST: /relation/object/query ``` 请求参数 ``` { "criteria": { "graphId": "GtElementSpNeighborhood001", "rel": "10", "from": "Eq3203020001e945bebd9b1447b9859638810e7d6147", "fromClassCode": "ACCCOT", "to": { "$in":[ "Sp320302000151a095a44c1d4fd7930d2f87d38cdf77", "Sp32030200010b1d106c4a6d45698c781bf7356df8ba ] }, "toClassCode": "space", }, "withColumns": [ "id", "name", "localId", "localName", "classCode" ] } ``` 返回内容 ``` { "result": "success", "data": [ { "id": "Sp320302000151a095a44c1d4fd7930d2f87d38cdf77", "name": "对象名称", "localId": "对象本地编码", "localName": "对象本地名称", "classCode": "space" } ] "message": "错误信息,如果接口发生错误会返回该字段" } ``` #### 基础接口: 查询实时数据 接口说明 ``` 查询对象绑点信息点的实时数据 ``` 请求地址 ``` POST: /object/data/current ``` 请求参数 ``` [ { "objectId": "Eqxxxxx", "infoCode": "Tdb" }, { "objectId": "Eqxxxxx", "infoCode": "CO2" }, { "objectId": "Eqxxxxx", "infoCode": "Hcho" } ] ``` 返回内容 ``` { "result": "success", "data": [ { "objectId": "Eqxxxxx", "infoCode": "Tdb", "infoValue": "8000-123", "data": 25.6, "time": "20200512172435" }, { "objectId": "Eqxxxxx", "infoCode": "Tdb", "infoValue": "8000-123", "data": 25.6, "time": "20200512172435" }, { "objectId": "Eqxxxxx", "infoCode": "Tdb", "error": "错误信息:信息点不存在,表号功能号配置错误,断数等" } ] } ``` 返回内容说明 ``` infoValue: 信息点配置的内容即绑定的表号功能号 time: 实时数据的采集时间 data: 实时数据的值 ``` #### 基础接口: 查询历史数据/分精度数据(废弃) 接口说明 ``` 查询对象绑点信息点的历史数据 ``` 请求地址 ``` POST: /object/data/history ``` 请求参数 ``` { "criteria": { "objectId": "", "infoCode": "", "period": 300, "time": { "$gte": "20200415120000", "$lt": "20200501120000" }, "asc": true } } ``` 参数说明 ``` objectId: 必填,对象id infoCode: 必填,信息点ID period: 必填,间隔, 单位为秒, 如300表示5分钟 time: 必填,历史数据的开始结束时间 asc: 对结果按时间排序, true表示升序, false表示降序, 默认为false ``` 返回内容 ``` { "result": "success", "data": [ { "time": "20200415120000" "data": 25.6, }, { "time": "20200415120500" "data": 25.6, }, { "time": "20200415121000" "data": 25.6, } ] } ``` 返回内容说明 ``` 返回数据的time可能是不连续的 ``` #### 基础接口: 查询历史数据/分精度数据 接口说明 ``` 查询对象绑点信息点的历史数据 1. 多点位个数最多支持50个 2. 分钟级数据，单点位支持最大7天数据查询，多点位支持最大1天数据查询； 3. 小时级数据，单点支持最大30天数据查询，多点位支持最大3天数据查询； 4. 日级数据，单点支持最大1年数据查询，多点位支持最大30天数据查询； ``` 请求地址 ``` POST: /object/data/history ``` 请求参数 ``` { "startTime": "20200415120000", "endTime": "20200501120000", "period": "分精度类型，支持 1min、5min、15min、1h、1d", "params": [ { "objectId": "对象id", "infoCode": "信息点编码", }, { "objectId": "对象id", "infoCode": "信息点编码", } ] } ``` 参数说明 ``` startTime: period: 必填,间隔 objectId: 必填,对象id infoCode: 必填,信息点ID ``` 返回内容 ``` { "result": "success", "data": [ { "objectId": "对象id", "infoCode": "信息点编码", "data": [ { "time": "20200415120000" "data": 25.6, }, { "time": "20200415120500" "data": 25.6, } ] }, { "objectId": "对象id", "infoCode": "信息点编码", "data": [ { "time": "20200415120000" "data": 25.6, }, { "time": "20200415120500" "data": 25.6, } ] } ] } ``` 返回内容说明 ``` 返回数据的time可能是不连续的 ``` #### 基础接口: 发送控制指令/设定动态参数 接口说明 ``` 该接口为异步方式 ``` 请求地址 ``` POST: /object/funcid/setting ``` 请求参数 ``` [ { "objectId": "Eqxxxxx", "infoCode": "FanFreqSet", value: 24 }, { "objectId": "Eqxxxxx", "infoCode": "InValveSwitchSet", value: "a" }, { "objectId": "Eqxxxxx", "infoCode": "WaterInOutDetaTempSet", value: 10 } ] ``` 请求参数说明 ``` value要严格匹配信息点定义的数据类型 ``` 返回内容 ``` { "result": "success", "data": [ { "objectId": "Eqxxxxx", "infoCode": "FanFreqSet", "exeCode":"sfge131v4t2vs3423rbsb3" }, { "objectId": "Eqxxxxx", "infoCode": "InValveSwitchSet", "exeCode":"sfge131v4t2vs3423rbsb3" }, { "objectId": "Eqxxxxx", "infoCode": "InValveSwitchSet", "exeCode":"sfge131v4t2vs3423rbsb3" } ] } ``` 返回内容说明 ``` exeCode: 指令查询码,用于查询指令执行结果 ``` #### 基础接口: 查询指令执行结果 请求地址 ``` POST: /object/funcid/settingQuery ``` 请求参数 ``` [ "sfge131v4t2vs3423rbqb3", "e1ge131v4t2vs3423rbsb3", "eaqge131v4t2vs3423rger" ] ``` 返回内容 ``` { "result": "success", "data": [ { "exeCode": "sfge131v4t2vs3423rbqb3", "exeResult": "timeout", }, { "exeCode": "e1ge131v4t2vs3423rbsb3", "exeResult": "running", }, { "exeCode": "eaqge131v4t2vs3423rger", "exeResult": "failed", } ] } ``` 返回内容说明 ``` 控制指令执行结果为一个字符串，其可能值有以下几种： - timeout，表示控制指令已下发但超过了合理响应时间(默认1minute,系统可配置)至今一直为得到反馈 - running，表示控制指令已下发在合理响应时间内还未得到反馈 - failed，指令未下发出去 - success-offline，指令已下发出去，并得到了反馈，'success-'后面的字符为反馈的信息 ```