songchunqiao/ControlProxy
1
0
Fork 0
forked from iod/ControlProxy
Code Pull Requests Activity
4599f31b49
ControlProxy/control-proxy-backend/yjs/ControlProxy接口.md

1049 lines
20 KiB
Markdown
Raw Normal View History

intial commit
2022-04-19 01:26:59 +00:00
# ControlProxy接口
> **基本要求：**
>
> 1.返回结果的result 不应该是jsonstr格式，当它可以是json对象时，需要以json对象返回。
> 2.异常处理，约定异常格式。提供工具类返回异常格式的消息。
>
> 3.输入参数都以json格式，如参数为doId：
>
> ```json
> {
> "doId":"xx.yy/zz"
> }
> ```
>
> 4.正常返回：(只返回状态的接口)
>
> ```json
> {
> "msg":"success",
> "code":0,
> }
> ```
>
> 5.正常返回：(返回一共数组)
>
> ```json
> {
> "msg":"success",
> "code":0,
> "data":{}//要返回的数据
> }
> ```
>
> 6.异常返回：
>
> ```json
> {
> "msg":"missing argument",
> "code":1
> }
>
> {
> "msg":"request to much",
> "code":2
> }
> ...
> ```
>
> 7.若返回一个列表的部分的接口，需要给定总数字段：（这样的接口参数需要提供count和offset）
>
> ```json
> //搜索接口返回
> //这个例子表示符合条件的一共有9999条数据，只返回count和offset限定的3条数据
> {
> "data":[
> {},
> {},
> {}
> ],
> "total":9999
> }
> ```
>
>
>
> ## Repo元数据
>
> | 字段 | 值 | 说明 | 示例 |
> | ----------- | ------ | --------------------------- | ---------------------------- |
> | doId | string | Repo的Id | "bdware.txte/Repo" |
> | name | string | Repo名称 | "xx数字对象仓库" |
> | owner | string | 所有者 | "xx局" |
> | contractID | string | 合约名称或者合约ID | "DBRepo" |
> | type | string | Repo类型(待扩展) | "Table"/"Http" |
> | description | string | 说明 | "这是一段关于该repo的说明" |
> | enableIndex | bool | 是否索引 | true |
> | createTime | long | 创建时间 | 1641364002477 |
> | status | string | 状态（在线/离线） | "online"或者"offline" |
> | check | string | 审核情况（提交/通过/不通过) | "submit"或"success"或"faild" |
> | operator | string | 操作员 | "张三" |
> | manager | array | 管理员 | ["xx局","yy局","zz部门"] |
>
> ### DO元数据
>
> | 字段 | 值 | 说明 | 示例 |
> | ----------- | ------ | ------------------ | -------------------------------------- |
> | doId | string | do的Id | "bdware.txte/Repo/do.dbname.tablename" |
> | name | string | do的名称 | "xx表格" |
> | type | string | Repo类型(待扩展) | "SQL"或者"CSV" |
> | description | string | 说明 | "这是一段关于该DO的说明" |
> | schema | string | 数据格式描述(DOd?) | "" |
> | createTime | long | 创建时间 | 1641364002477 |
>
> ### Repo元数据示例
>
> ```json
> {
> "doId":"bdware.txte/Repo",
> "name":"xx部门数据仓库",
> "type":"？",
> "description":"这是一个repo",
>
> "owner":"xx省yy市zz部门",
> "contractID":"DBRepo",
> "enableIndex":true,
> "createTime":1641364002477,
> "status":"online",
> "check":"submit",
> "operator":"张三",
> "manager":["xx局","yy局","zz部门"]
> }
> ```
>
>
>
> ## 示例说明：getDoCount
>
> - 说明：调用搜索引擎的统计接口，返回对应repo的doId当中含有输入参数的repo的do数量
>
> - 参数：一个字符串，用于doId的模糊匹配
>
> ```json
> {
> "key":"bdware.txte/Repo"
> }
> ```
>
> - 正常返回：result的值是json对象而不是字符串
>
> ```json
> //空：
> {
> "data":[]
> }
> //非空：
> {
> "data":[
> {"doId":"bdware.txte/Repo1","count":10},
> {"doId":"bdware.txte/Repo2","count":12}
> ],
> "total":9999
> }
> //调用返回的全部内容，是正常还是异常看status字段
> {"needSeq":false,"seq":0,"status":"Success","result":{"data":[{"doId":"bdware.txte/Repo1","count":10},{"doId":"bdware.txte/Repo2","count":12}]},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085355104_1279","action":"onExecuteResult","executeTime":"9"}
>
> ```
>
> - 异常返回：抛出异常，result的内容是个字符串表示异常内容或者异常的信息
>
> ```json
> //异常返回方式
> YancloudUtil.exceptionReturn({"msg":"missing arguments repoId ","code":1});
>
> //结果
> {"needSeq":false,"seq":0,"status":"Exception","result":{"msg":"xxx","code":1},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085126815_8926","action":"onExecuteResult","executeTime":"17"}
> ```
>
## 一、ControlProxy.yjs @李智
### 1.addRepo
- 说明：调用Gateway的addLocalRepo，由GateWay检查参数等，正确返回代码为0，错误返回提供具体错误代码及原因
- 参数
```json
{
"doId":"bdware.txte/Repo",
"name":"xx部门数据仓库",
"type":"？",
"description":"这是一个repo",
"owner":"xx省yy市zz部门",
"contractID":"DBRepo",
"enableIndex":true,
"createTime":1641364002477,
"status":"online",
"check":"submit",
"operator":"张三",
"manager":["xx局","yy局","zz部门"]
}
```
- 正常返回
```json
{
"msg":"success",
"rrt":"110ms",
"code":0
}
```
- 异常返回：msg：错误信息，code：错误代码
```json
{
"msg":"missing arguments repoId ",
"code":1
}
```
### 2.pingRepo
- 说明
- 参数
```json
{
"doId":"bdware.ss/Repox"
}
```
- 正常返回
```json
{
"msg":"success",
"rrt":"110ms",
"code":0,
"repoInfo":
{
"doId":"bdware.txte/Repo",
"name":"xx部门数据仓库",
"type":"？",
"description":"这是一个repo",
"owner":"xx省yy市zz部门",
"contractID":"DBRepo",
"enableIndex":true,
"createTime":1641364002477,
"status":"online",
"check":"submit",
"operator":"张三",
"manager"：["xx局","yy局","zz部门"]
}//repo元数据
}
```
- 异常返回
```json
{
"msg":"repo is unconnected",
"code":1
}
```
### 3.getRepoList
- 说明
- 参数：无
- 正常返回
```json
{
"data":[
{},//repo元数据
{},//repo元数据
{}//repo元数据
],
"total":9999
}
```
- 异常返回
```json
{
"msg":"repo is unconnected",
"code":1
}
```
### 4.deleteRepo
- 说明
- 参数
```json
{
"doId":"bdware.ss/Repox"
}
```
- 正常返回
```json
{
"msg":"success",
"code":0
}
```
- 异常返回：msg：错误信息，code：错误代码
```json
{
"msg":"can not found repo",
"code":1
}
```
### 5.deleteRepoList（4和5是同一个）
- 说明
- 参数
```json
[
{"doId":"bdware.ss/Repox"},
{"doId":"bdware.ss/Repoy"}
]
```
- 正常返回
```json
{
[{
"msg":"success",
"code":0
},
{
"msg":"success",
"code":0
},
{
"msg":"success",
"code":0
}]
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 6.updateRepo
- 说明
- 参数：全部元数据
```json
{
"doId":"bdware.txte/Repo",
"name":"xx部门数据仓库",
"type":"？",
"description":"这是一个repo",
"owner":"xx省yy市zz部门",
"contractID":"DBRepo",
"enableIndex":true,
"createTime":1641364002477,
"status":"online",
"check":"submit",
"operator":"张三",
"manager"：["xx局","yy局","zz部门"]
}
```
- 正常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
## 二、networking.yjs @范博
### 1.getRouterInfo
- 说明
- 参数：无
- 正常返回
```json
{
"date": 1642467459759,
"name": "next路由器",
"doId": "bdwaretest.loccall.next1",
"version": "2.1",
"address": "127.0.0.1:2222",
"status": "已审核",
"protocol": "IRP",
"pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
}
```
- 异常返回
```json {
{
"msg":"can not found repo",
"code":1
}
```
### 2.listLRS
- 说明
- 参数:无
- 说明：该接口暂时不会有太多数据，因此没有提供total字段和count，offset方式
- 正常返回
```json
{
//"result":"success",
"data":[
{
"protocol":"DO-IRP协议","name":"ee","pubKey":"046c31d1e4f0056325c352a6c9934c1d15a51ef4b5bc552387a1c43188b2317a1863a9072cf612c2c15e5353083cf47e2024b49e416e8f6f8d4b0db496b67336f5","version":"2.0","address":"1.1.1.1:333","doId":"bdtest5.r1.121111111444","date":1643340044943
},
{"protocol":"DO-IRP协议","name":"aaa","pubKey":"04bb83950bf8f0b02cc9c95eb25a30950958e2c271c423c28a3612f5bc199a94c55c637d15876e442c265e1b3f970fb167ba59a489157f279955d69a12359501df","version":"2.0","address":"1.1.1.1:44","doId":"bdtest5.r1.ss","date":1645510310038},{"protocol":"DO-IRP协议","name":"test2","pubKey":"04bb83950bf8f0b02cc9c95eb25a30950958e2c271c423c28a3612f5bc199a94c55c637d15876e442c265e1b3f970fb167ba59a489157f279955d69a12359501df","version":"2.0","address":"1.1.1.1:44","doId":"bdtest5.r1.test2","date":1645510310038},
{"protocol":"DO-IRP协议","name":"test","pubKey":"04982fc8507302c57a0389de1f6fc8a72c70577dff15fb0f23d3898742ac7684ace75c3b12dec94b8866ffcea9ef4795c09074327e4f1822b546cc6f783931da94","version":"2.0","address":"1.1.1.1:55","doId":"bdtest5.r1.tttTest","date":1643338165008
}
],
"count":4
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 3.updateLRS
- 说明
- 参数
```json
{
"date": 1642467459759,
"oldName": "路由器",
"oldDoId": "bdwaretest.loccall.next0",
"name": "next路由器",
"doId": "bdwaretest.loccall.next1",
"version": "2.1",
"address": "127.0.0.1:2222",
"status": "已审核",
"protocol": "IRP",
"pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
}
```
- 正常返回:新的doid
```json
{
"data":"xxx.xx/aa";
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 4.createLRS（除了oldname和olddoid，其他和undate一样）
- 说明
- 参数
```json
{
"date": 1642467459759,
"name": "next路由器",
"doId": "bdwaretest.loccall.next1",
"version": "2.1",
"address": "127.0.0.1:2222",
"status": "已审核",
"protocol": "IRP",
"pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
}
```
- 正常返回
```json
{
"data":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 5.deleteLRS
- 说明
- 参数
```json
{
"name": "Repo1",
"doId": "bdwaretest.loccall/Repo1",
"pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
}
```
- 正常返回
```json
{
"data":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 6.listRepo（同listLRS）
- 说明
- 参数
```json
{
"doId":"...",
"address":"...",
"owner":"...",
"...":"..."
}
```
- 正常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
### 7.updateRepo（同updateLRS）
- 说明
- 参数
```json
{
"doId":"...",
"address":"...",
"owner":"...",
"...":"..."
}
```
- 正常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
### 8.createRepo(同createLRS)
- 说明
- 参数
```json
{
"date": 1642467459759,
"name": "Repo1",
"doId": "bdwaretest.loccall/Repo1",
"version": "2.1",
"address": "tcp://127.0.0.1:21042",
"status": "已审核",
"protocol": "DOIP",
"pubKey": "04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
}
```
- 正常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
### 9.deleteRepo（同deleteLRS）
- 说明
- 参数
```json
{
"name": "next路由器",
"doId": "bdwaretest.loccall.next1",
"pubKey": "04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
}
```
- 正常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"doId":"bdware.ss/Repox"
}
```
### 10.setRootRouterInfo(和Create一样)
- 说明
- 参数
```json
{
"date": 1642467459759,
"name": "Repo1",
"doId": "bdwaretest.loccall/Repo1",
"version": "2.1",
"address": "tcp://127.0.0.1:21042",
"status": "已审核",
"protocol": "DOIP",
"pubKey": "04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
}
```
- 正常返回
```json
{
"data":"bdware.ss/Repox"
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 11.reInit
- 说明
- 参数：无
- 正常返回
```json
{
"data":"verify and start server success"
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
## 三、repodetail.yjs
### 1.getDoList @张宏伟
- 说明：如果指定repo，那么就是指定repo的dolist，否则是全部的
- 参数
```json
{"doId":"xxx"}
//或者
{}
```
- 正常返回
```json
{
"data":[{},{},{}],
"total":9999
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 2.getRepoTopology
- 说明
- 参数
```json
{
"doId":"..."
}
```
- 正常返回
```json
{
"data":[
{"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]},
{"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]},
{"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]},
{"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]}
],
"total":9999
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 3.getStaticIndex(先不管)
- 说明
-
### 4.fakeList（略
- 说明
-
## 四、search.yjs
### 1.getDoCount @张宏伟
- 说明：调用搜索引擎的统计接口，返回对应repo的doId当中含有输入参数的repo的do数量
- 参数：一个字符串，用于doId的模糊匹配
```json
bdware.txte/Repo
```
- 正常返回：result的值是json对象而不是字符串
```json
//空：
{
"data":[],
"total":0
}
//非空：
{
"data":[
{"doId":"bdware.txte/Repo1","count":10},
{"doId":"bdware.txte/Repo2","count":12}
],
"total":2
}
//调用返回的全部内容，是正常还是异常看status字段
{"needSeq":false,"seq":0,"status":"Success","result":{"data":[{"doId":"bdware.txte/Repo1","count":10},{"doId":"bdware.txte/Repo2","count":12}]},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085355104_1279","action":"onExecuteResult","executeTime":"9"}
```
- 异常返回：抛出异常，result的内容是个字符串表示异常内容
```json
{"needSeq":false,"seq":0,"status":"Exception","result":{"msg":"xxx","code":1},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085126815_8926","action":"onExecuteResult","executeTime":"17"}
```
### 2.countRecordByDate @董瑞
- 说明：
> //=====全域监管：数字对象溯源 针对单个DO的，通过SQL查询来实现。
> //根据 doId --> 找到“数字对象世系”
> //86.500.1/Repo.1/Doab
> //根据 doId+时间范围+interval+protocol --> 不同operation的统计数据 （AuditProxy)
> //countDORecordByDate()
> //{"doId":xxxx,"startTime","endTime","interval","eventPrefix":["doip_create","doip_update"]}
> //{"eventxxx":[1,2,3],"event2":[1,2,3]}
>
> //根据 doId +查找条件（时间范围 protocol operation user?) +offset/count -->总数+指定条数的数组（AuditProxy)
> // queryDoRecordByDate
> //{"doId":xxxx,"startTime","endTime","eventPrefix":["doip_create","doip_update"]}
> //{"count":xx, "data":[{doip_request的某一行。},]}
> // queryDoRecordByOffset
> //{"doId":xxxx,"offset","count","eventPrefix":["doip_create","doip_update"]}
> //{"total":xx,"count":xx, "data":[{doip_request的某一行。},]}
> //==============
- 参数：下面的内容表示owner字段当中包含"xxx"且doid当中包含"aibd"的结果
```json
{
"startTime":1641454745128,
"endTime":1641494745128,
"interval":5000,
"eventPrefix":["abc"]
}
```
- 正常返回：repo元数据的数组，每一个{}表示一个元数据
```json
{
"doip_search":[1,2,3,4],
"doip_create":[5,6,7,8]
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 3.getDoFilter @张宏伟
- 说明：按照某一字段值的范围查询
- 参数：下面是按照字段createTime的时间来查询，count和offset可缺省
```json
{
"type":"creatTime",
"count":10,
"offset":0,
"from":"1141363811328",
"to":"1941363811328"
}
```
- 正常返回：repo元数据的数组，每一个{}表示一个元数据
```json
{
"data":[
{},{},{}
],
"total":3
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
### 4.search
- 说明：支持多个字段的搜索
- 参数：下面的内容表示owner字段当中包含"xxx"且doid当中包含"aibd"的结果
```json
{
"params":[
{"type":"owner","keyword":"xxx"},
{"type":"doid","keyword":"aibd"}
],
"count":10,
"offset":0
}
```
- 正常返回：repo元数据的数组，每一个{}表示一个元数据
```json
{
"data":[
{},{},{}
],
"total":3
}
```
- 异常返回
```json
{
"msg":"can not found repo",
"code":1
}
```
Copy Permalink