### 术语说明:

#### 对象
基于数据字典类型和信息点定于创建的实例

```
数据字典默认每个类型都有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", 
            "infoVaue": "8000-123", 
            "data": 25.6,
            "time": "20200512172435"
        },
        { 
            "objectId": "Eqxxxxx", 
            "infoCode": "Tdb", 
            "infoVaue": "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可能是不连续的

```

#### 基础接口: 发送控制指令/设定动态参数
请求地址
```
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", 
            "value": 24,
            "status": "sended"
        },
        { 
            "objectId": "Eqxxxxx", 
            "infoCode": "InValveSwitchSet", 
            "value": "a",
            "status": "skip",
            "error": "值错误"
        },
        { 
            "objectId": "Eqxxxxx", 
            "infoCode": "InValveSwitchSet", 
            "value": "a",
            "status": "send-timeout",
            "error": "异常信息"
        }
    ]
}
```
返回内容说明
```
    status: 指令发送状态
    skip: 信息点未配置或值错误等会取消发送,
    sended: 指令发送成功, 注意:指令发送和设备执行是异步的,指令发送成功并不表示设备会马上执行该指令,甚至不能确定设备将来会执行该指令
    send-timeout: 连接采集程序超时
    status的状态码后续会修订,文档中的值并不是最终版本
```