用户相关API

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查询对应的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	用户统一登出	POST/public-api/user/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	是	在观远平台中获得
loginIds	用户ID（外部系统内的ID）列表	Body	String List	是	用户界面登录以及通过api管理用户属性的id ，数组大小不能超过100
ugIds	要添加的用户组id列表	Body	String List	是	isExternal为true时视为外部用户组Id列表，否则为内部用户组Id列表
isExternal	是否是外部用户组的Id列表	Body	Boolean	否	默认为true

3.8.3 请求与响应示例

POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "loginIds": ["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	是	在观远平台中获得
loginIds	用户ID（外部系统内的ID）列表	Body	String List	是	用户界面登录以及通过api管理用户属性的id，数组大小不能超过100
ugIds	要添加的用户组id列表	Body	String List	是	isExternal为true时视为外部用户组Id列表，否则为内部用户组Id列表
isExternal	是否是外部用户组的Id列表	Body	Boolean	否	默认为true

3.9.3 请求与响应示例

POST Body Sample:

{

    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "loginIds": ["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 接口简介

请求方式： POST

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

3.12.2 参数说明

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

3.12.3 请求与响应示例

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."
}