集成外部服务
功能及平台机制说明
外部系统业务集成提供规范和接口
实现思路步骤
集成外部服务时，按以下步骤进行集成：
第一步：创建集成用户，下发集成用户名、密码和平台地址 平台管理员在平台中创建用户，并给用户分配集成角色。可以所有外部系统共用同一个集成用户，也可以每个外部系统创建一个集成用户。 平台管理员线下将集成用户名、密码和平台地址下发给外部系统维护人员。
第二步：注册外部系统 平台管理员通过服务注册功能，将外部系统注册到平台中。
第三步：平台管理人员维护组织，组织自动同步到外部系统 平台管理员通过组织管理功能修改组织，平台提供两种方式进行组织同步：自动同步（定时）和手工同步（组织管理功能中提供“同步组织”功能）。
第四步：外部系统实现相关接口，在合适的时机调用平台接口 外部系统调用平台接口时，需要使用平台管理人员提供的集成用户名和密码登录后再调用平台接口。
平台与外部系统调用安全性机制：
平台调用外部系统的安全性：通过外部系统提供的apisecret来实现；外部系统调用平台的安全性：通过集成用户登录的方式来实现。
具体操作说明
一. 服务注册
服务注册时，需要提交以下参数：
中文名称：服务中文名；
接入地址：此接入地址下需要支持接口，接收通知(/notice)和服务元信息(/serviceMetaInfo)
外部服务apisecret：平台服务调用外部服务时，会带apisecret参数，外部服务通过apisecret保证调用的安全性。
二. 单点登录
登录 通过门户登录后，在门户菜单中，可以看到注册的外部服务。打开外部服务时，将以浏览器页的方式打开另一个窗口，同时在地址上添加一个参数“token”。
获取用户信息 外部服务通过获取用户信息接口获取当前登录用户的详细信息，接口参考附录。
验证token 外部服务通过验证token接口判断当前是否登录，外部服务需要在自己的后台调用验证token接口，从而保证用户注销后外部服务也不能访问。
注销 用户注销后， 登录产生的token将失效。
三、组织同步
数据库结构说明：
组织操作记录(misc_orgoperaterecord)
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar2(36) | 主键 |
| operatorid | varchar2(128) | 操作用户ID |
| operatorname | varchar2(128) | 操作用户名 |
| operatetime | datetime | 操作时间 |
| description | clob | 描述 |
| isgenhistory | int | 是否生成了组织历史，0未生成，1已生成 |
组织镜像(misc_orgsnapshot)
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar2(36) | 主键 |
| createtime | datetime | 创建时间 |
| content | clob | 组织镜像 |
| digest | varchar2(256) | 组织镜像的md5 |
通知(misc_notice)
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar2(36) | 主键 |
| status | int | 通知状态，0:未通知，1:正在通知，2:通知失败，3:通知成功 |
| content | clob | 通知内容 |
| noticeurl | varchar2(256) | 通知地址 |
| createtime | datetime | 通知创建时间 |
| finishtime | datetime | 通知处理结束时间 |
附录接口说明
一. 平台服务接口
- 服务注册(当前仅在平台内部使用) 说明：此接口调用前必须登录集成用户
url: $platformUrl/entry/ manager/services
method: post
request cookie:
user_session: $user_session //集成用户登录后获取的user_session
request body(application/json)
{
"type": "external", //服务类型，取值范围：外部服务("external")，内部服务("")
"label": "", //服务名称
"address": "", //服务接入地址,
"apisecret": "" //外部服务apisecret，平台调用外部服务时将会使用
}
response status: 200表示成功，其它失败
- 登录 说明：此接口调用前不需要登录集成用户
url: $platformUrl/login
method: post
request body(form)
username: "" //集成用户名
password: "" //集成用户密码
token方式登录
request body(form)
token:""
response cookie
user_session: "" //后续调用平台接口时需要使用
response status: 200成功，其它失败
注意：token的生成获取方式：
第一步，使用集成用户在浏览器中登录门户；
第二步，浏览器中输入$platformUrl//uaa/userinfo?type=token, 返回的类似如下:
{"token":"system@xDuJbx8dYfYBXu6%2B6Knke1YalZvAmvlWPm9uHuFVnkh1nQyYA6A4LcDSUI8Qk4dN","name":""}
- 注销
说明：此接口调用前不需要登录集成用户
url: $platformUrl/logout method: get request cookie: user_session: "" //登录得到的user_session response status: 200成功，其它失败 - 获取用户信息 说明：此接口调用前不需要登录集成用户
url: $platformUrl/entry/uaa/userinfo
method: get
request cookie:
user_session: $token //平台打开外部系统时给的token
response body(application/json)
{
"user_ id":"", //用户标识
" user_name ":"", //登录名
"email":"",
"phone_number":"",
" give_name ":"" //中文名
}
response status: 200成功，其它失败
- 验证token 使用"获取用户信息"模拟，如果能获取到用户信息，表示token有效，否则无效
- 获取组织增量 说明：此接口调用前必须登录集成用户
url: $platformUrl/entry/misc/org/ getOrgSnapshot? orgDigest=$orgDigest
method: get
request cookie:
user_session: $user_session //集成用户登录获取获取的user_session
request field:
orgDigest: 外部服务当前组织镜像的md5; 当orgDigest为空或给定的orgDigest不存在时，将会返回组织最新的全量数据
response body(application/json)
{
"success": true, //状态, 取值范围true, false
"msg": "", //错误消息
"type": "delta" , //数据格式, 取值范围: 增量(delta), 全量(all),
" orgDigest ": "", //当前组织镜像的md5
"data":{
//增量数据修改时，添加一个state表示修改状态，取值范围：new,update,delete， //全量时没有state
"users": [{
//参考数据结构中的“用户”
state: "new"
}],
"orgs": [{
//参考数据结构中的“组织”
state: "new"
}]
}
}
response status: 200表示成功，其它表示失败
- 导入组织
说明：此接口调用前必须登录集成用户
url: $platformUrl/entry/misc/org/ importOrg
method: post
request cookie:
user_session: $user_session //集成用户登录获取获取的user_session
request body(application/json) //与导出的数据格式类似
{
"data": {
"users": [
{
"state": "add", //状态, 取值范围: add/delete/update
"id": "", //主键
"created": null, //创建时间
"userName": "", //登录用户名
"givenName": "", //用户中文名称
"verified": true, //是否
"email": "", //用户的email
"phoneNumber": "", //电话
"address":"", //地址
"position": "", //职位
"description": "", //备注
"hiredate": null //入职时间
}
],
"orgs": [
{
"state": "add", //状态, 取值范围: add/delete/update
"sid": "", //主键
"id": "", //组织id, 如果是人员成员时，id就是人的id
"parentid": "", //父组织id
"name": "", //组织名称
"code": "", //组织编码
"fid": "", //id全路径
"fcode": "", //编码全路径
"fname": "", //名称全路径
"type": "", //组织类型，取值范围: 人员成员(psm),部门(dpt),机构(ogn)
"isleaf": true, //是否是叶子节点
"isMainOrganization": true, //是否是主部门
"sequence": "" //序号
}
]
}
}
response body(application/json)
{
"success": true, //状态, 取值范围true, false
"msg": "" //错误消息
}
response status: 200表示成功，其它表示失败
- 导入简洁模式的组织 说明：此接口调用前必须登录集成用户
url: $platformUrl/entry/misc/org/ importSimpleOrg
method: post
request cookie:
user_session: $user_session //集成用户登录获取获取的user_session
request body(application/json) //简洁模式的组织, 当前要求全量数据
{
"data": {
"type": "all", //取值范围: 增量(delta), 全量(all),默认是all
"users": [
{
"state": "add", //当type=delta时生效, add/delete/update
"id": "", //主键
"orgs":[ "",""], //所属组织的id列表
"mainOrg": "", //主组织的id
"created": null, //创建时间
"userName": "", //登录用户名
"givenName": "", //用户中文名称
"verified": true, //是否
"email": "", //用户的email
"phoneNumber": "", //电话
"address":"", //地址
"position": "", //职位
"description": "", //备注
"hiredate": null, //入职时间
"roles": ["", ""] //拥有的角色id列表;
}
],
"orgs": [
{
"state": "add", //当type=delta时生效, add/delete/update
"id": "", //组织id
"parentid": null, //父组织id
"name": "", //组织名称
"code": "", //组织编码
"type": "", //组织类型:部门(dpt),机构(ogn),岗位(pos)
"sequence": "" //序号
"roles": ["", ""] //拥有的角色id列表;
}
]
}
}
response body(application/json)
{
"success": true, //状态, 取值范围true, false
"msg": "" //错误消息
}
response status: 200表示成功，其它表示失败
二. 外部服务接口
- 接收通知
url: $接入地址/notice?apisecret=$apisecret
method: post
request field:
apisecret: $apisecret //注册外部系统时提供的apisecret
request body(application/json):
{
"type": "", //通知类型, 取值范围: "orgChanged"
"data": {} //通知数据
}
1.1 组织变化通知
{
"type": "orgChanged",
"data": {
"orgDigest": "" //最新组织镜像的md5
}
}
response status: 200表示成功，其它表示失败
- 服务信息
url: $接入地址/serviceMetaInfo? apisecret=$apisecret
method: get
request field:
apisecret: $apisecret //注册外部系统时提供的apisecret
response body(application/json)
参考数据结构中的"服务元信息"
response status: 200表示成功，其它表示失败
三. 数据结构
人员 (users)
{ id: "", //主键 created: null, //创建时间 userName: "", //登录用户名 givenName: "", //用户中文名称 verified: true, //是否 email: "", //用户的email phoneNumber: "", //电话 address:"", //地址 position: "", //职位 description: "", //备注 hiredate: null, //入职时间 }组织 (orgs)
{
sid: "", //主键
id: "", //组织id, 如果是人员成员时，id就是人的id
parentid: "", //父组织id
name: "", //组织名称
code: "", //组织编码
fid: "", //id全路径
fcode: "", //编码全路径
fname: "", //名称全路径
type: "", //组织类型，取值范围: 人员成员(psm),部门(dpt),机构(ogn)
isleaf: true, //是否是叶子节点
isMainOrganization: true, //是否是主部门
sequence: "" //序号
}
- 服务元信息
{
"serviceInfo": {
"name":"servicemanager",
"label":"微服务管理系统"
},
"menu" : {
"title":"微服务管理系统",
"children":[{
"types":["pc",”mobile”,"func",”openPage”],
"color":"#3494F8",
"icon":"dataControldataControl-c",
"title" : "服务管理",
"url" : "http://servicemanager/x5/UI2/main/fuwu_sj.w"
}]
},
"authorize" : {
"permissions" : [{
"id":"sm_permission_001",
"code" : "*:http://servicemanager/x5/UI2/main/fuwu_sj.w:get",
"name" : "服务管理",
"type" : "menu"
}],
"roles" : [{
"id":"admin",
"code" : "admin",
"name" : "管理员",
"permissions" : [ "*:http://servicemanager/x5/UI2/main/fuwu_sj.w:get"]
}]
}
}
serviceMetaInfo包括3个节点：serviceInfo、menu和authorize
serviceInfo节点描述应用的基本信息
name用于应用注册，需保证唯一menu节点用来描述应用的菜单信息 menu里的第一级定义一级菜单名称。通过children定义二级菜单或一级菜单中的菜单项。 types代表菜单项的类型，可由下面的选项组合而成。
- pc和func代表是桌面端菜单，在桌面门户中可见
- mobile和func代表是移动端菜单，在移动门户中可见
- openPage代表会通过window.open打开对应url，url中会添加token参数
- iframe代表会在门户的功能区域，通过iframe打开
authorize节点用来描述应用的权限信息 permissions部分用来描述应用的所有权限列表
注意：
1. 不要丢失菜单权限描述，一个菜单项要对应一个权限，其中code部分中间为权限的url信息，对应菜单项中url的值,roles部分是当前应用的角色列表。roles内的permissions是当前角色的权限集合。
2. 后台api同样可以在权限中描述，后台api描述的时候如果是同域可以进行鉴权.
3. 如果权限中有需要根据url参数区分权限项的情况，请求的时候或者描述菜单项的时候添加参数 $pparms 来声明是权限参数
比如 http://console.newdao.net/order?type=user 这样一个请求的url,鉴权的时候会看是否有 /order的api权限.
http://console.newdao.net/order?type=user&$pparams=type 这样一个请求的url,鉴权的时候会看是否有 /order?type=user的api权限.
在定义角色时，可以使用系统内置的角色。
系统内置2个角色如下：
•authc是注册账户角色，所有注册用户都属于这个角色。
•admin是系统管理员角色。