用户相关API
1. 用户相关API 概述
Public API，是指观远数据为系统集成提供的标准化开放接口。系统集成，通常是指将各个分离的设备(如个人电脑)、系统、功能和信息等集成到相互关联的、统一和协调的系统之中，使资源达到充分共享，实现集中、高效、便利的管理。系统集成实现的关键在于解决系统之间的互连和互操作性问题，是一个多厂商、多协议和面向各种应用的体系结构。
观远数据提供一套简便的验证机制，来供私有化部署用户进行外部系统和账户对接集成，实现集中、高效、便利的管理。本文将为您详细介绍观远数据为您提供的与用户相关的 Public API。
2. 用户相关API 列表速览
目前，与用户相关的 Public API 共包含11个，列表如下：
| 序号 | 接口描述 | 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/list |
| 6 | 修改指定用户状态 | POST /public-api/user/enable |
| 7 | 通过指定的用户的loginid查询对应的uid | POST /public-api/user/info |
| 8 | 将用户添加到用户组 | POST /public-api/user/add-to-groups |
| 9 | 将用户从用户组移除 | POST /public-api/user/remove-from-groups |
| 10 | 获取指定用户组下直接挂载的用户列表 | POST /public-api/user-group/:ugId/users |
| 11 | 获取指定用户直接所属的用户组列表 | POST /public-api/user/:uId/groups |
| 12 | 用户统一登出 | GET /public-api/sso/sign-out |
3. 用户相关API 具体说明
3.1 批量创建用户
3.1.1 接口简介
请求方式： POST
请求地址：/public-api/users/add
3.1.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 应用Token | Body | String | 是 | 在观远平台中获得 |
| userPropertyType | 用户属性类型 | Body | Integer | 否 | 0:使用key；1:使用名称。默认为0。 |
| users | 需要创建的用户列表 | Body | Json Object List | 是 | 用户列表，包含用户各个属性字段，具体详见示例。 |
3.1.3 请求与响应示例
POST Body Sample:
{
"token":"xxx",
"userPropertyType": 1,
"users": [
{
"name": "nameA", // 必填，用户登录后显示名称
"loginId": "Id1", // 必填，用以在用户界面登录的信息以及通过api管理用户属性的id，如邮箱、工号、手机号等。如果使用邮箱登录，则此处填写邮箱，和下述email字段并不冲突。
"password": "", //账号登录密码，必须BASE64加密。SSO等非账密登录场景下可不提供该字段信息，不传或者传空时，会使用随机密码。
"role": "admin", //用户角色，目前可支持admin，editor，participant三类
"email": "sample1@qq.email.com",
"mobile": "13200000000",
"enabled":true,//用户状态，非必填。布尔值，只能填true和false。true对应“启用”，false对应“禁用”。
"userGroupIds": ["gId1", "gId2"...], //External group ID
"userDefinedProperties": {
"企业微信账号": "value2",
"钉钉账号": "value2",
"企业微信公司名称": "value2",
"userMobile": "value2",
"飞书账号": "value2",
"关联数据集属性": "value2"
} //观远平台内已经添加的用户属性名称
},
{
"name": "nameB",
"loginId": "Id2", // 必填 用户界面登录以及通过api管理用户属性的id
"password": "",
"role": "editor",
"email": "sample2@qq.email.com",
"mobile": "13200000001",
"userGroupIds": ["gId3", "gId4"...],
"userDefinedProperties": {
"企业微信账号": "value2",
"钉钉账号": "value2",
"企业微信公司名称": "value2",
"userMobile": "value2",
"飞书账号": "value2",
"关联数据集属性": "value2"
} //观远平台内已经添加的用户属性名称
}
]
}
注意：
若您想要在添加用户时绑定用户的企业微信、钉钉或者云之家账号，请在"userDefinedProperties"内添加对应的账号信息。对应的账号信息可以在“管理员设置”-“用户基础属性管理”-“基础属性”中查看对应的属性名称。
3.2 批量删除用户
3.2.1 接口简介
请求方式： POST
请求地址：/public-api/users/delete
3.2.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 应用Token | Body | String | 是 | 在观远平台中获得 |
| users | 需要删除的用户列表 | Body | String List | 是 | 内容为需要删除的用户ID列表，注意是登录ID，不是观远系统内生成的24位字符串。 |
3.2.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"users": ["loginId1","loginId2",...]
}
这里需要注意的是，若要删除的用户还有资源未转移，则该用户不能被删除，在response中会返回哪些用户没有被成功删除。
{
"response": "uId1, uId2 deleted successfully. uId3 can not be deleted due to some resource rely on."
}
3.3 批量修改用户属性
3.3.1 接口简介
请求方式： POST
请求地址：/public-api/users/modify
3.3.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 应用Token | Body | String | 是 | 在观远平台中获得 |
| userPropertyType | 用户属性类型 | Body | Integer | 否 | 0:使用key；1:使用名称。默认为0。 |
| users | 需要修改属性的用户列表，且包含需要修改的属性信息 | Body | Json Object List | 是 | 用户列表，包含需要修改的用户属性字段，及其属性值。具体详见示例。 |
3.3.3 请求与响应示例
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 Sample:
{
"response": "Property changed!"
}
与创建用户API类似，若您想要在修改用户的企业微信、钉钉或者云之家账号，请在"userDefinedProperties"内添加对应的账号信息。对应的账号信息可以在“管理员设置”-“用户基础属性管理”-“基础属性”中查看对应的属性名称。
3.4 批量查询用户是否存在
3.4.1 接口简介
请求方式： POST
请求地址：/public-api/users/get
3.4.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| users | 需要查询的用户列表 | Body | String List | 是 | 内容为需要查询的用户ID列表 |
3.4.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"users": ["loginId1", "loginId2", ...]
}
Response Sample:
{
"userExist": ["loginId1", ...],
"userNotExist": ["loginId2", ...]
}
3.5 获取用户列表
3.5.1 接口简介
请求方式： POST
请求地址：POST /public-api/user/list
3.5.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| userPropertyType | 用户属性类型 | Body | Integer | 否 | 0:使用key；1:使用名称。默认为0。 |
3.5.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"userPropertyType": 1
}
Response Sample:
{
"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"
}
}
},
……
]
}
3.6 修改指定用户状态
3.6.1 接口简介
请求方式： POST
请求地址：/public-api/user/enable
3.6.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| uId | 需要修改的用户id | Body | String | 是 | -- |
| enabled | 开启或禁用 | Body | Boolean | 是 | -- |
3.6.3 请求与响应示例
POST Body Sample:
{
"token":"xxxx",
"uId":"xxxxx",
"enabled":true
}
3.7 通过指定的用户的loginid查询对应的uid
3.7.1 接口简介
请求方式： POST
请求地址：POST /public-api/user/info
3.7.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| loginId | 用户界面登录以及通过api管理用户属性的id | Body | String | 是 | -- |
3.7.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"loginId": "Id1"
}
Response Sample:
{
"result": "ok",
"response": {
"uId": "uId1",
"loginId": "Id1",
"role": [
"admin"
],
"name": "张三",
"mobile": "12345678901",
"domId": "demo",
"userProperties": {
"location": "",
"住址": "",
"等级": ""
...
},
"id": 123,
"email": "张三@guandata.com",
"pwdVersion": 0
}
}
3.8 将用户添加至用户组
3.8.1 接口简介
请求方式： POST
请求地址：/public-api/user/add-to-groups
3.8.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| loginId | 用户ID（外部系统内的ID） | Body | String | 是 | 用户界面登录以及通过api管理用户属性的id |
| ugIds | 要添加的用户组id列表 | Body | String List | 是 | isExternal为true时视为外部用户组Id列表，否则为内部用户组Id列表 |
| isExternal | 是否是外部用户组的Id列表 | Body | Boolean | 否 | 默认为true |
3.8.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"loginId": "Id1", // 必填 用户界面登录以及通过api管理用户属性的id
"ugIds": ["ugId1", "ugId2"...],
"isExternal": true
}
3.9 将用户从用户组删除
3.9.1 接口简介
请求方式： POST
请求地址：/public-api/user/remove-from-groups
3.9.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| loginId | 用户ID（外部系统内的ID） | Body | String | 是 | 用户界面登录以及通过api管理用户属性的id |
| ugIds | 要添加的用户组id列表 | Body | String List | 是 | isExternal为true时视为外部用户组Id列表，否则为内部用户组Id列表 |
| isExternal | 是否是外部用户组的Id列表 | Body | Boolean | 否 | 默认为true |
3.9.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"loginId": "uId1",
"ugIds": ["ugId1", "ugId2"...],
"isExternal": true
}
3.10 获取指定用户组下直接挂载的用户列表
3.10.1 接口简介
请求方式： POST
请求地址：POST /public-api/user-group/:ugId/users
3.10.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| userPropertyType | 用户属性类型 | Integer | Integer | 否 | 0:使用key；1:使用名称。默认为0。 |
| ugId | 指定用户组的ugId | url | String | 是 | -- |
3.10.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43",
"userPropertyType": 1
}
Response 结构与「返回用户列表」接口一致。
3.11 获取指定用户直接所属的用户组列表
3.11.1 接口简介
请求方式： POST
请求地址：POST /public-api/user/:uId/groups
3.11.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| token | 账户同步令牌 | Body | String | 是 | 在观远平台中获得 |
| uId | 需要修改的用户id | Body | String | 是 | -- |
3.11.3 请求与响应示例
POST Body Sample:
{
"token":"sdjfghfodjgjshgfiw23ehrt43"
}
Response Sample:
{
"result": "ok",
"response": [
{
"ugId": "f2c4fcc38d9c8490581e9510",
"domId": "demo",
"parentId": "", //父用户组ID
"name": "Test Group 1111",
"externalGroupId": "", //外部系统关联用户组ID
"externalParentGroupId": "" //外部系统关联父用户组ID
},
……
]
}
3.12 用户统一登出
3.12.1 接口简介
请求方式： GET
请求地址：GET /public-api/sso/sign-out
3.12.2 参数说明
| 参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
| provider | 提供者 | Query | String | 是 | 在观远平台中获得 |
| ssoToken | token信息 | Query | String | 是 | 加密后用于登录的信息 |
3.12.3 请求与响应示例
POST Body Sample:
{
"info": {"ssoToken": ""},
"provider":"demo"
}
ssoToken加密前内容示例：
{
"domainId":"abcbi", // 租户ID 必填 （String）
"externalUserId": "userId", // 甲方用户ID 必填 (String)
"timestamp": 1502079219000 // 时间戳 东八区时间 毫(Integer)
}
按照约定的方式加密后即生成ssoToken。
其中，如果用户是调用统一账户集成所述的API创建的，那么当系统的登录方式是 工号登录时， externalUserId 即为 loginId ；当采用email 方式登录时，external user id 即为 email地址。 若有疑问，请联系观远数据解决方案顾问。
Response Sample：
{
"response":"log out success"
}
-
注意:
-
/public-api/sso/sign-out接口需要在单一登录开启时才能生效。
-
关于SSOtoken加解密的说明：观远SSO集成概述