苏州管廊对第三方接口

概述

接口以WebSocket形式提供, 服务地址 wss://服务器IP:50064/API-GRPC/, 请求和返回的数据类型均为JSON字符串. WebSocket的基本原理参考 https://developer.mozilla.org/zh-CN/docs/Web/API/WebSocket , 更多请搜索. 几乎所有的语言都有对应的支持, 比如Java有OkHttp等.

接口协议

请求数据格式为(下方为数据JSON, 接口以JSON字符串形式接收):

{
  "X-Secret-Key": null,
  "X-Token": "Token",
  "protoName": "协议",
  "serviceName": "服务",
  "methodName": "方法",
  "requestJson": "数据JSON"
}

返回数据格式为(下方为数据JSON, 接口以JSON字符串形式返回):

{
  "type": "Next",
  "json": "数据JSON"
}

或:

{
  "type": "Completed"
}

或:

{
  "type": "Error",
  "text": "账户或密码错误"
}

当type为 Next 时, 表示接口返回了一条数据, 可能返回n次(n为0到无限大). 当type为 Completed 时, 表示接口处理完毕. 当type为 Error 时, 表示请求数据有问题,或无法找到数据, text中会给出问题原因.

接口请求和返回数据的格式是固定的, 以下API说明只对请求数据属性作出说明. 返回数据形式完全一样, 只是数据JSON的具体内容不同.

API

所有API调用前必须进行登录验证, 验证通过后拿到Token. 每次调用API时必须将拿到的Token值设置在 X-Token 中. Token每次登录验证时会刷新, 在下次登录前一直有效. 以下API会以登录为例作出详细说明, 其他API仅说明请求数据, 返回数据中type为next时json值的格式. 开始调用API前, 请建立一个WebSocket连接, 然后用此连接发送和接收数据.

{"json":"{\"id\":\"test\",\"department_id\":\"4e7721a5-b2bf-438c-8f40-ab20b278fe87\",\"position_ids\":[],\"role_ids\":[\"admin\"],\"name\":\"测试\",\"pinyin\":\"ceshi\",\"department\":{\"id\":\"4e7721a5-b2bf-438c-8f40-ab20b278fe87\",\"parent_id\":\"cbbef69d-c97c-4bea-9a84-00fc783a1996\",\"name\":\"测三\",\"pinyin\":\"cesan\",\"parent\":{\"id\":\"cbbef69d-c97c-4bea-9a84-00fc783a1996\",\"parent_id\":\"system\",\"name\":\"测试\",\"pinyin\":\"ceshi\",\"parent\":{\"id\":\"system\",\"parent_id\":\"\",\"name\":\"系统\",\"pinyin\":\"xitong\",\"person_count\":\"29\"},\"person_count\":\"28\"},\"person_count\":\"3\"},\"positions\":[],\"roles\":[{\"id\":\"admin\",\"power_ids\":[\"menu-1\",\"menu-1-01\",\"menu-1-01-001\",\"menu-1-01-002\",\"menu-1-01-003\",\"menu-1-01-004\",\"menu-1-01-005\",\"menu-1-01-006\",\"menu-1-01-007\",\"menu-1-01-008\",\"menu-1-02\",\"menu-1-02-001\",\"menu-1-02-002\",\"menu-1-02-003\",\"menu-1-02-004\",\"menu-1-03\",\"menu-1-03-001\",\"menu-1-03-002\",\"menu-1-03-003\",\"menu-1-03-004\",\"menu-1-03-005\",\"menu-1-03-006\",\"menu-1-03-007\",\"menu-1-03-008\",\"menu-2\",\"menu-2-01\",\"menu-2-01-001\",\"menu-2-01-002\",\"menu-2-01-003\",\"menu-2-01-004\",\"menu-2-01-005\",\"menu-2-02\",\"menu-2-02-001\",\"menu-2-02-002\",\"menu-2-02-003\",\"menu-2-03\",\"menu-2-03-001\",\"menu-2-03-002\",\"menu-2-03-003\",\"menu-2-03-004\",\"menu-2-04\",\"menu-2-05\",\"menu-2-05-001\",\"menu-2-05-002\",\"menu-2-05-003\",\"menu-2-05-004\",\"menu-3\",\"menu-3-01\",\"menu-3-03\",\"menu-3-04\",\"menu-3-05\",\"menu-4\",\"menu-4-01\",\"menu-4-01-001\",\"menu-4-01-002\",\"menu-4-01-003\",\"menu-4-01-004\",\"menu-4-02\",\"menu-4-02-001\",\"menu-4-02-002\",\"menu-4-03\",\"menu-4-03-001\",\"menu-4-03-002\",\"menu-4-04\",\"menu-4-05\",\"menu-4-06\",\"menu-4-07\",\"menu-4-07-001\",\"menu-4-07-002\",\"menu-5\"],\"name\":\"系统管理员\",\"description\":\"拥有最高权限\",\"power_view_data\":{}}],\"username\":\"t\",\"status\":\"NORMAL\",\"token\":\"bd4013fe-6e33-4868-8fb1-54b5b287b947\",\"phone\":\"13800138000\",\"sex\":\"男\",\"age\":30,\"email\":\"\",\"identity\":\"\",\"remark\":\"拥有最高权限\",\"photo_file_id\":\"\"}","type":"Next"}

type为Next时,会返回用户数据JSON. 从中提取token属性的值, 比如a23f966a-4e10-4d51-9d08-38041302f09e. 调用其他API时需要用此值设置请求中的属性X-Token, 由于你不会用到其它属性, 故其它属性不作说明.

{"type":"Completed"}

type为Completed时,表示本次请求处理完毕. 除非你收到 {"type":"Error"} , 否则在收到Completed前不应结束对数据的接收.