观远 BI

用户相关API

创建于 2022-10-25 / 最近更新于 2024-07-25 / 11703
字体: [默认] [大] [更大]

1. 用户相关API 概述

Public API,是指观远数据为系统集成提供的标准化开放接口。系统集成,通常是指将各个分离的设备(如个人电脑)、系统、功能和信息等集成到相互关联的、统一和协调的系统之中,使资源达到充分共享,实现集中、高效、便利的管理。系统集成实现的关键在于解决系统之间的互连和互操作性问题,是一个多厂商、多协议和面向各种应用的体系结构。

观远数据提供一套简便的验证机制,来供私有化部署用户进行外部系统和账户对接集成,实现集中、高效、便利的管理。本文将为您详细介绍观远数据为您提供的与用户相关的 Public API。

2. 用户相关API 列表速览

目前,与用户相关的 Public API 共包含12个,列表如下:

序号接口描述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查询对应的uidPOST /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用户统一登出POST/public-api/user/sign-out

3. 用户相关API 具体说明

3.1 批量创建用户

3.1.1 接口简介

请求方式: POST

请求地址:/public-api/users/add

3.1.2 参数说明

参数名参数值说明Location类型是否必填备注
token应用TokenBodyString在观远平台中获得
userPropertyType用户属性类型BodyInteger0:使用key;1:使用名称。默认为0。
users需要创建的用户列表BodyJson Object List用户列表,包含用户各个属性字段,具体详见示例。

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 批量删除用户

请求方式: POST

请求地址:/public-api/users/delete

3.2.2 参数说明

参数名参数值说明Location类型是否必填备注
token应用TokenBodyString在观远平台中获得
users需要删除的用户列表BodyString List内容为需要删除的用户ID列表,注意是登录ID,不是观远系统内生成的24位字符串。

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 批量修改用户属性

请求方式: POST

请求地址:/public-api/users/modify

3.3.2 参数说明

参数名参数值说明Location类型是否必填备注
token应用TokenBodyString在观远平台中获得
userPropertyType用户属性类型BodyInteger0:使用key;1:使用名称。默认为0。
users需要修改属性的用户列表,且包含需要修改的属性信息BodyJson 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 Sample:

{
   "response": "Property changed!"
}

与创建用户API类似,若您想要在修改用户的企业微信、钉钉或者云之家账号,请在"userDefinedProperties"内添加对应的账号信息。对应的账号信息可以在“管理中心”-“用户基础属性管理”-“基础属性”中查看对应的属性名称。

3.4 批量查询用户是否存在

请求方式: POST

请求地址:/public-api/users/get

3.4.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得
users需要查询的用户列表BodyString List内容为需要查询的用户ID列表

POST Body Sample:

{

  "token":"sdjfghfodjgjshgfiw23ehrt43",

  "users": ["loginId1", "loginId2", ...]

}

Response Sample:

{
 "userExist": ["loginId1", ...],
 "userNotExist": ["loginId2", ...]
}

3.5 获取用户列表

请求方式: POST

请求地址:POST /public-api/user/list

3.5.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得
userPropertyType用户属性类型BodyInteger0:使用key;1:使用名称。默认为0。

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 修改指定用户状态

请求方式: POST

请求地址:/public-api/user/enable

3.6.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得
uId需要修改的用户idBodyString--
enabled开启或禁用BodyBoolean--

POST Body Sample:

{
 "token":"xxxx",
 "uId":"xxxxx",
 "enabled":true
}

3.7 通过指定的用户的loginid查询对应的uid

请求方式: POST

请求地址:POST /public-api/user/info

3.7.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得
loginId用户界面登录以及通过api管理用户属性的idBodyString--

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 将用户添加至用户组

请求方式: POST

请求地址:/public-api/user/add-to-groups

3.8.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得

loginIds

用户ID(外部系统内的ID)列表

Body

String List

用户界面登录以及通过api管理用户属性的id ,数组大小不能超过100

ugIds要添加的用户组id列表BodyString ListisExternal为true时视为外部用户组Id列表,否则为内部用户组Id列表
isExternal是否是外部用户组的Id列表BodyBoolean默认为true


POST Body Sample:

{
   "token":"sdjfghfodjgjshgfiw23ehrt43",
   "loginIds": ["Id1"], // 必填 用户界面登录以及通过api管理用户属性的id
   "ugIds": ["ugId1", "ugId2"...],
   "isExternal": true
}

3.9 将用户从用户组删除

请求方式: POST

请求地址:/public-api/user/remove-from-groups

3.9.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得

loginIds

用户ID(外部系统内的ID)列表

Body

String List

用户界面登录以及通过api管理用户属性的id,数组大小不能超过100

ugIds要添加的用户组id列表BodyString ListisExternal为true时视为外部用户组Id列表,否则为内部用户组Id列表
isExternal是否是外部用户组的Id列表BodyBoolean默认为true

POST Body Sample:

{

   "token":"sdjfghfodjgjshgfiw23ehrt43",
   "loginIds": ["uId1"],
   "ugIds": ["ugId1", "ugId2"...],
   "isExternal": true
}

3.10 获取指定用户组下直接挂载的用户列表

请求方式: POST

请求地址:POST /public-api/user-group/:ugId/users

3.10.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得
userPropertyType用户属性类型IntegerInteger0:使用key;1:使用名称。默认为0。
ugId指定用户组的ugIdurlString--

POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "userPropertyType": 1
}

Response 结构与「返回用户列表」接口一致。

3.11 获取指定用户直接所属的用户组列表

请求方式: POST

请求地址:POST /public-api/user/:uId/groups

3.11.2 参数说明

参数名参数值说明Location类型是否必填备注
token账户同步令牌BodyString在观远平台中获得
uId需要修改的用户idBodyString--

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 用户统一登出

请求方式: POST

请求地址:POST/public-api/user/sign-out

3.12.2 参数说明

参数名参数值说明Location类型是否必填备注
token应用TokenBodyString账户同步令牌,在观远平台中获得
provider登录模式说明BodyString登陆provider。各类登陆的provider由下面的列表提供。如果provider为空,则根据BI系统账号进行退出。
externalUserId外部用户ID或者账号BodyString如果provider不为空,此值为接入方用户账号,也即单点登录时的用户账号;如果provider为空,此值为BI系统账号。

POST Body Sample:

{
  "token": "your_auth_token",
  "provider": "standardoauth2",
  "externalUserId": "user@example.com"
}

Response Sample:

{
  "result": "ok",
  "message": "All login sessions for the user have been logged out."
}
    1 人点赞过