1.系统账户集成
系统集成，通常是指将各个分离的设备(如个人电脑)、系统、功能和信息等集成到相互关联的、统一和协调的系统之中，使资源达到充分共享，实现集中、高效、便利的管理。系统集成实现的关键在于解决系统之间的互连和互操作性问题，是一个多厂商、多协议和面向各种应用的体系结构。
观远数据提供一套简便的验证机制，来供私有化部署用户进行外部系统和账户对接集成，实现集中、高效、便利的管理。本文将为您详细介绍账户集成的操作与 Public API。
1.1 操作步骤
（1）点击右上角九宫格中的“管理员设置”，进入“系统集成”-“统一账户集成”。
（2）获取账号同步令牌（Token）。账号同步令牌（Token）是调用统一账户集成相关API时的唯一身份凭证。系统管理员可从管理员设置页面获得该令牌。安全起见，进行账户集成开发时，需妥善保管该令牌。
（3）统一账户集成接口。观远数据提供一整套用户、用户组管理接口供企业IT部门来实现统一账户管理的集成。提供的接口包括：
| 序号 | 类别 | 接口描述 | Path |
| 1 | 用户 | 批量创建用户 | POST /public-api/users/add |
| 2 | 用户 | 批量删除用户 | POST /public-api/users/delete |
| 3 | 用户 | 批量修改用户属性 | POST /public-api/users/modify |
| 4 | 用户 | 批量查询用户是否存在 | POST /public-api/users/get |
| 5 | 用户组 | 批量创建用户组 | POST /public-api/user-groups/add |
| 6 | 用户组 | 批量修改用户组 | POST /public-api/user-groups/modify |
| 7 | 用户组 | 删除指定用户组 | POST /public-api/user-group/:ugId/delete |
| 8 | 用户&用户组 | 将用户添加到用户组 | POST /public-api/user/add-to-groups |
| 9 | 用户&用户组 | 将用户从用户组移除 | POST /public-api/user/remove-from-groups |
| 10 | 用户 | 获取用户列表 | POST /public-api/user/list |
| 11 | 用户组 | 获取用户组列表 | POST /public-api/user-group/list |
| 12 | 用户&用户组 | 获取指定用户组下直接挂载的用户列表 | POST /public-api/user-group/:ugId/users |
| 13 | 用户&用户组 | 获取指定用户直接所属的用户组列表 | POST /public-api/user/:uId/groups |
| 14 | 页面 | 获取页面列表 | POST /public-api/page/list |
| 15 | 页面权限 | 获取指定页面有读权限的用户列表 | POST /public-api/page/:pgId/get-readable-owners |
| 16 | 数据集 | 获取数据集列表 | POST /public-api/data-source/list |
| 17 | 数据集权限 | 获取指定数据集有使用权限的用户列表 | POST /public-api/data-source/:dsId/get-readable-owners |
| 18 | 资源迁移 | 将指定用户组下辖的所有资源迁移至其他用户组或用户 | POST /public-api/user-group/:ugId/transfer-resources |
| 19 | 资源迁移 | 将指定用户下辖的所有资源迁移至其他用户组或用户 | POST /public-api/user/:uId/transfer-resources |
| 20 | 用户 | 获取指定用户能访问的页面列表 | POST /public-api/user/:uId/get-authorized-pages |
| 21 | 用户 | 获取指定用户能访问的数据集列表 | POST /public-api/user/:uId/get-authorized-datasets |
| 22 | 用户 | 修改指定用户与各个页面的访问及归属关系 | POST /public-api/user/:uId/modify-authorized-pages |
| 23 | 用户 | 修改指定用户与各个数据集的访问及归属关系 | POST /public-api/user/:uId/modify-authorized-datasets |
| 24 | 用户组 | 获取指定用户组能访问的页面列表 | POST /public-api/user-group/:ugId/get-authorized-pages |
| 25 | 用户组 | 获取指定用户组能访问的数据集列表 | POST /public-api/user-group/:ugId/get-authorized-datasets |
| 26 | 用户组 | 修改指定用户组与各个页面的访问及归属关系 | POST /public-api/user-group/:ugId/modify-authorized-pages |
| 27 | 用户组 | 修改指定用户组与各个数据集的访问及归属关系 | POST /public-api/user-group/:ugId/modify-authorized-datasets |
| 28 | 数据集 | 搜索数据集 | POST /public-api/data-source/search?q=xx&&offset=0&&limit=10 |
| 29 | 页面 | 搜索页面 | POST /public-api/page/search?q=xx&&offset=0&&limit=10 |
| 30 | 用户 | 通过指定的用户的loginid查询对应的uid | POST /public-api/user/info |
| 31 | 数据集 | 通过指定数据集的id查询该数据集结构 | POST /public-api/data-source/:dsId/columns |
| 32 | 用户 | 将BI平台用户进行登出 | GET /public-api/sso/sign-out |
2.账户集成说明
2.1 批量创建用户
请求方式：POST
请求地址：/public-api/users/add
参数说明
Name | Location | 类型 | 含义 | 是否必填 | 备注 |
token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
userPropertyType | Body | Integer | 用户属性类型 | 否 | 1：使用名称。 |
users | Body | Json Object List | 需要创建的用户列表 | 是 | 用户列表，包含用户各个属性字段，具体详见示例。 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"userPropertyType":1,
"users": [
{
"name": "nameA", // 必填，用户登录后显示名称
"loginId": "Id1", // 必填 用以在用户界面登录以及通过api管理用户属性的id
"password": "", //SSO登录可不提供该字段信息，密码必须BASE64加密
"role": "admin", //用户角色，目前可支持admin，editor，participant三类
"email": "sample1@qq.email.com",
"mobile": "13200000000",
"enable": true,
"userGroupIds": ["gId1", "gId2"...], //External group ID
"userDefinedProperties": {
"企业微信账号": "value2",
"钉钉账号": "value2",
"企业微信公司名称": "value2",
"userMobile": "value2",
"飞书账号": "value2",
"关联数据集属性": "value2"
} //观远平台内已经添加的用户属性名称
},
{
"name": "nameB",
"loginId": "Id2", // 必填 用户界面登录以及通过api管理用户属性的id
"password": "",
"role": "editor",
"enable": false,
"email": "sample2@qq.email.com",
"mobile": "13200000001",
"userGroupIds": ["gId3", "gId4"...],
"userDefinedProperties": {
"企业微信账号": "value2",
"钉钉账号": "value2",
"企业微信公司名称": "value2",
"userMobile": "value2",
"飞书账号": "value2",
"关联数据集属性": "value2"
} //观远平台内已经添加的用户属性名称
}
...
]
}注意：
若您想要在添加用户时绑定用户的企业微信、钉钉或者云之家账号，请在"userDefinedProperties"内添加对应的账号信息。对应的账号信息可以在“管理员设置”-“用户基础属性管理”-“基础属性”中查看对应的属性名称。
2.2 批量删除用户
请求方式： POST
请求地址：/public-api/users/delete
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| users | Body | String List | 需要删除的用户列表 | 是 | 内容为需要删除的用户ID列表 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"users": ["loginId1","loginId2",...]
}这里需要注意的是，若要删除的用户还有资源未转移，则该用户不能被删除，需要在response中告知用户哪些用户没有被成功删除。
Response:
{
"response": "uId1, uId2 deleted successfully. uId3 can not be deleted due to some resource rely on."
}2.3 批量修改用户属性
请求方式： POST
请求地址：/public-api/users/modify
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| userPropertyType | Body | Integer | 用户属性类型 | 否 | 1：使用名称。 |
| users | Body | Json Object List | 需要修改属性的用户列表，且包含需要修改的属性信息 | 是 | 用户列表，包含需要修改的用户属性字段，及其属性值。具体详见示例。 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"userPropertyType": 1,
"users": [
{
"name": "nameA",
"loginId": "Id1", // 必填，用以在用户界面登录的信息以及通过api管理用户属性的id，如邮箱、工号、手机号等。如果使用邮箱登录，则此处填写邮箱，和下述email字段并不冲突。
"password": "", //SSO登录可不提供该字段信息，密码必须BASE64加密
"role": "admin", //用户角色，目前可支持admin，editor，participant三类
"email": "sample1@qq.email.com",
"mobile": "13200000000",
"enabled":true//用户状态，非必填。布尔值，只能填true和false。true对应“启用”，false对应“禁用”。
"userDefinedProperties": {
"企业微信账号": "value2",
"钉钉账号": "value2",
"企业微信公司名称": "value2",
"userMobile": "value2",
"飞书账号": "value2",
"关联数据集属性": "value2"
} //观远平台内已经添加的用户属性名称
},
{
"name": "nameB",
"loginId": "Id2", // 必填 用户界面登录以及通过api管理用户属性的id
"password": "",
"role": "editor",
"email": "sample2@qq.email.com",
"mobile": "13200000001",
"userDefinedProperties": {
"企业微信账号": "value2",
"钉钉账号": "value2",
"企业微信公司名称": "value2",
"userMobile": "value2",
"飞书账号": "value2",
"关联数据集属性": "value2"
} //观远平台内已经添加的用户属性名称
}
...
]
}Response:
{
"response": "Property changed!"
}与2.1类似，若您想要在修改用户的企业微信、钉钉或者云之家账号，请在"userDefinedProperties"内添加对应的账号信息。对应的账号信息可以在“管理员设置”-“用户基础属性管理”-“基础属性”中查看对应的属性名称。
2.4 批量查询用户是否存在
请求方式： POST
请求地址：/public-api/users/get
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| users | Body | String List | 需要查询的用户列表 | 是 | 内容为需要查询的用户ID列表 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"users": ["loginId1", "loginId2", ...]
}Response:
{
"userExist": ["loginId1", ...],
"userNotExist": ["loginId2", ...]
}2.5 批量创建用户组
请求方式： POST
请求地址：/public-api/user-groups/add
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| userGroups | Body | Json Object List | 需要创建的用户组列表，包含用户组ID（外部系统的唯一ID），显示名称及上级用户组ID | 是 | name：用户组名；externalGroupId：用户组id; externalParentGroupId：上级用户组ID，可缺省 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"userGroups": [
{
"name": "groupA",
"externalGroupId": "gId1"
},
{
"name": "groupB",
"externalGroupId": "gId2",
"externalParentGroupId":"gId1"
}
]
}若请求中有用户组的externalParentGroupId在当前用户组以及请求userGroups中都不存在，或者用户组父子关系逻辑成环，都将导致本次用户组创建失败（全部都不创建）。
2.6 批量修改用户组
请求方式： POST
请求地址：/public-api/user-groups/modify
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| userGroups | Body | Json Object List | 需要创建的用户组列表，包含用户组ID（外部系统的唯一ID），显示名称及上级用户组ID | 是 | name：用户组名；externalGroupId：用户组id; externalParentGroupId：上级用户组ID，可缺省 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"userGroups": [
{
"name": "groupA",
"externalGroupId": "gId1",
"externalParentGroupId":"parent_gId1"
},
{
"name": "groupB",
"externalGroupId": "gId2",
"externalparentGroupId":"parent_gId2"
}
]
}
2.7 删除指定用户组
请求方式： POST
请求地址：/public-api/user-group/:ugId/delete
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
}Response: 返回最新用户列表
{
"result": "ok",
"response": [
{
"ugId": "f2c4fcc38d9c8490581e9510",
"domId": "demo",
"parentId": "", //父用户组ID
"name": "Test Group 1111",
"externalGroupId": "", //外部系统关联用户组ID
"externalParentGroupId": "" //外部系统关联父用户组ID
},
……
]
}2.8 将用户添加至用户组
请求方式： POST
请求地址：/public-api/user/add-to-groups
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| loginId | Body | String | 用户ID（外部系统内的ID） | 是 | 必填，用户界面登录以及通过api管理用户属性的id |
| ugIds | Body | String List | 要添加的用户组id列表 | 是 | isExternal为true时视为外部用户组Id列表，否则为内部用户组Id列表 |
| isExternal | Body | Boolean | 是否是外部用户组的Id列表 | 否 | 默认为true |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"loginId": "Id1", // 必填 用户界面登录以及通过api管理用户属性的id
"ugIds": ["ugId1", "ugId2"...],
"isExternal": true
}2.9 将用户从用户组删除
请求方式： POST
请求地址：/public-api/user/remove-from-groups
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| loginId | Body | String | 用户ID（外部系统内的ID） | 是 | 必填，用户界面登录以及通过api管理用户属性的id |
| ugIds | Body | String List | 要移除的外部用户组id列表 | 是 | isExternal为true时视为外部用户组Id列表，否则为内部用户组Id列表。若用户不在某用户组内，接直接跳过。 |
| isExternal | Body | Boolean | 是否是外部用户组的Id列表 | 否 | 默认为true |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"loginId": "uId1",
"ugIds": ["ugId1", "ugId2"...],
"isExternal": true
}2.10 获取用户列表
请求方式： POST
请求地址：POST /public-api/user/list
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| userPropertyType | Body | Integer | 用户属性类型 | 否 | 1：使用名称。 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"userPropertyType": 1
} Response:
{
"result": "ok",
"response": [
{
"id": 1,
"uId": "d9f1ec1b629946b2b00f1d60",
"name": "张三",
"mobile": "13345678920",
"email": "zhangsan@guandata.com",
"loginId": "10001",
"domId": "demo",
"role": [
"admin"
],
"config": {
"userProperties": {
"企业微信账号": "value2",
"钉钉账号": "value2",
"企业微信公司名称": "value2",
"userMobile": "value2",
"飞书账号": "value2",
"关联数据集属性": "value2"
}
}
},
……
]
}2.11 获取用户组列表
请求方式： POST
请求地址：POST /public-api/user-group/list
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"
}Response:
{
"result": "ok",
"response": [
{
"ugId": "f2c4fcc38d9c8490581e9510",
"domId": "demo",
"parentId": "", //父用户组ID
"name": "Test Group 1111",
"externalGroupId": "", //外部系统关联用户组ID
"externalParentGroupId": "" //外部系统关联父用户组ID
},
……
]
}2.12 获取指定用户组下直接挂载的用户列表
请求方式： POST
请求地址：POST /public-api/user-group/:ugId/users
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| userPropertyType | Body | Integer | 用户属性类型 | 否 | 1：使用名称。 |
| ugId | url | String | 指定用户组的ugId | 是 | - |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"，
"userPropertyType": 1
}Response格式同2.10
2.13 获取指定用户直接所属的用户组列表
请求方式： POST
请求地址：POST /public-api/user/:uId/groups
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| uId | url | String | 指定用户的uId | 是 | - |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"
}Response:
{
"result": "ok",
"response": [
{
"ugId": "f2c4fcc38d9c8490581e9510",
"domId": "demo",
"parentId": "", //父用户组ID
"name": "Test Group 1111",
"externalGroupId": "", //外部系统关联用户组ID
"externalParentGroupId": "" //外部系统关联父用户组ID
},
……
]
} Response格式同2.10.
2.14 获取页面列表
请求方式： POST
请求地址：POST /public-api/page/list
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"
}Response:
{
"result": "ok",
"response": [
{
"pgId": "0ac483ab81b54ce184157100",
"domId": "demo",
"name": "集团总览",
"uId": "d9f1ec1b629946b2b00f1d60", // 页面创建者
"pgType": "PAGE", //页面类型："OVERVIEW"（概览）、"PAGE"（普通页面）、 "LARGE_SCREEN"(数据大屏)
"parentDirId": "rc135f11b39a842d8b5475d4" //页面所属文件夹ID
},
……
]
}2.15 获取指定页面有读权限的用户列表
请求方式： POST
请求地址：POST /public-api/page/:pgId/get-readable-owners
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| pgId | url | String | 指定页面的pgId | 是 | - |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"
}Response:
{
"result": "ok",
"response": {
"ownerUsers": [
{
"name": "zhangsan",
"id": "h9aaad4c93bc1496891321e7",
"email": "zhangsan@guandata.com",
"loginId": "zhangsan"
},
……
],
"ownerGroups": [
{
"name": "zln34",
"id": "m62d41e027dfb4e10a4b4a80"
},
……
],
"readableUsers": [
……
],
"readableGroups": [
……
]
}
}2.16 获取数据集列表
请求方式： POST
请求地址：POST /public-api/data-source/list
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"
}Response:
{
"result": "ok",
"response": [
{
"dsId": "fe43fdcb1b0094b65b5492dd",
"name": "dataset_name",
"displayType": "MYSQL", //数据集类型
"storageId": "mfba91c30d7c9455a99df3cd",
"domId": "demo",
"uId": "l9c85be354b674ec4a1081cc", //创建者
"parentDirId": "i5865e734b8374489abe2fc4", //所属文件夹
"cnId": "mysql", //数据连接类型
"rowCount": 1000000000, //行数
"colCount": 5, //列数
"status": "FINISHED", //更新状态
"ctime": "2018-07-11 13:50:36+0800", //创建时间
"utime": "2018-07-13 11:49:53+0800", //更新时间
"cardCount": 0 //卡片数量
},
……
]
}2.17 获取指定数据集有使用权限的用户列表
请求方式： POST
请求地址：POST /public-api/data-source/:dsId/get-readable-owners
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| dsId | url | String | 指定数据集的dsId | 是 | - |
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"
}Response同2.14.
2.18 将指定用户组下有所有者权限的资源迁移至其他用户组或用户
请求方式： POST
请求地址：POST /public-api/user-group/:ugId/transfer-resources
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| ugId | url | String | 当前资源所属用户组的ugId | 是 | - |
| inheritorUIds | Body | String List | 获得权限的用户uId列表 | 否 | |
| inheritorUgIds | Body | String List | 获得权限的用户组ugId列表 | 否 | - |
inheritorUIds与inheritorUgIds中至少包含一个参数。
POST Body Sample:
{
"token":"m2a369b32444b48caa873411",
"inheritorUIds":[],
"inheritorUgIds":["w54fdc9a7877a4c7ba387a36"]
}Response:
{
"result": "ok",
"response": "UserGroup resources transfered"
}2.19 将指定用户下辖有所有者权限的资源迁移至其他用户组或用户
请求方式： POST
请求地址：POST /public-api/user/:uId/transfer-resources
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String | 账户同步令牌 | 是 | 在观远平台中获得 |
| inheritorUIds | Body | String List | 获得权限的用户uId列表 | 否 | - |
| inheritorUgIds | Body | String List | 获得权限的用户组ugId列表 | 否 | - |
inheritorUIds与inheritorUgIds中至少包含一个参数。
可根据通过指定的用户的loginid查询对应的uid接口再用uid调用2.19接口做迁移。
POST Body Sample:
{
"token":"m2a369b32444b48caa873411",
"inheritorUIds":["w54fdc9fa877a4c7ba387a36"],
"inheritorUgIds":[]
}Response:
{
"result": "ok",
"response": "UserGroup resources transfered"
}2.20 获取指定用户能访问的页面列表
请求方式： POST
请求地址：POST /public-api/user/:uId/get-authorized-pages
参数说明：
| Name | Location | 类型 | 含义 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| token | Body | String |