让决策更智能
新一代智能数据分析平台

统一账户集成(上)

观远产品部发表于:2021年03月21日 21:27:44更新于:2021年03月28日 22:14:21

    (此功能为付费增值模块,如需试用请联系商务)

    观远数据提供一套简便的验证机制,来供私有化部署用户做外部系统账户对接。

1. 获取账号同步令牌(Token)

    账号同步令牌(Token)是调用统一账户集成相关API时的唯一身份凭证。系统管理员可从管理员设置页面获得该令牌。安全起见,进行账户集成开发时,需妥善保管该令牌。

image.png

2. 统一账户集成接口

    观远数据提供一整套用户、用户组管理接口供企业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查询对应的uidPOST /public-api/user/info


2.1 批量创建用户

    请求方式: POST

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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
usersBodyJson Object List需要创建的用户列表用户列表,包含用户各个属性字段,具体详见示例。

    POST Body Sample:

{
 "token":"sdjfghfodjgjshgfiw23ehrt43",
 "users": [
  {
   "name": "nameA",    // 必填,用户登录后显示名称
   "loginId": "Id1",   // 必填,用以在用户界面登录的信息以及通过api管理用户属性的id,如邮箱、工号、手机号等。如果使用邮箱登录,则此处填写邮箱,和下述email字段并不冲突。
   "password": "", //SSO登录可不提供该字段信息,密码必须BASE64加密
   "role": "admin",  //用户角色,目前可支持admin,editor,participant三类
   "email": "sample1@qq.email.com",
   "mobile": "13200000000",
   "userGroupIds": ["gId1", "gId2"...],   //External group ID
   "userDefinedProperties": {
      "wechatwork": "wechatworkID1", //企业微信、钉钉、云之家账号等信息添加在这个位置
      "key1": "value1",
      "key2": "vaule2"
    }   //观远平台内已经添加的用户属性字段
  },
  {
   "name": "nameB",
   "loginId": "Id2",  // 必填 用户界面登录以及通过api管理用户属性的id
   "password": "",
   "role": "editor",
   "email": "sample2@qq.email.com",
   "mobile": "13200000001",
   "userGroupIds": ["gId3", "gId4"...],
   "userDefinedProperties": {
      "wechatwork": "wechatworkID2",
      "key1": "value1",
      "key2": "vaule2"
    }   //观远平台内已经添加的用户属性字段
  }
  ...
 ]
}

    注意:

    所有用户属性,必须以字符串形式传入,不能使用用数值、数组、json等其他类型。

    若您想要在添加用户时绑定用户的企业微信、钉钉或者云之家账号,请在"userDefinedProperties"内添加对应的账号信息。企业微信、钉钉和云之家对应的key分别为:"wechatwork","dingtalk","yunzhijia"。

2.2 批量删除用户

    请求方式: POST

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

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
usersBodyString 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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
usersBodyJson Object List需要修改属性的用户列表,且包含需要修改的属性信息用户列表,包含需要修改的用户属性字段,及其属性值。具体详见示例

    POST Body Sample:

{
   "token":"sdjfghfodjgjshgfiw23ehrt43",
   "users": [
   {
    "name": "nameA",
    "loginId": "Id1",   // 必填,用以在用户界面登录的信息以及通过api管理用户属性的id,如邮箱、工号、手机号等。如果使用邮箱登录,则此处填写邮箱,和下述email字段并不冲突。
    "password": "", //SSO登录可不提供该字段信息,密码必须BASE64加密
    "role": "admin",  //用户角色,目前可支持admin,editor,readonly三类
    "email": "sample1@qq.email.com",
    "mobile": "13200000000",
    "userDefinedProperties": {
      "wechatwork": "wechatworkID1", //企业微信、钉钉、云之家账号等信息添加在这个位置
      "key1": "value1",
      "key2": "vaule2"
     }   //观远平台内已经添加的用户属性字段
   },
   {
    "name": "nameB",
    "loginId": "Id2",  // 必填 用户界面登录以及通过api管理用户属性的id
    "password": "",
    "role": "editor",
    "email": "sample2@qq.email.com",
    "mobile": "13200000001",
    "userDefinedProperties": {
      "wechatwork": "wechatworkID2",
      "key1": "value1",
      "key2": "vaule2"
     }   //观远平台内已经添加的用户属性字段
   }
  ...
 ]
}

    Response:

{
    "response": "Property changed!"
}

    与2.1类似,若您想要在修改用户的企业微信、钉钉或者云之家账号,请在"userDefinedProperties"内添加对应的账号信息。企业微信、钉钉和云之家对应的key分别为:"wechatwork","dingtalk","yunzhijia"。

2.4 批量查询用户是否存在

  请求方式: POST

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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
usersBodyString List需要查询的用户列表内容为需要查询的用户ID列表

    POST Body Sample:

{
   "token":"sdjfghfodjgjshgfiw23ehrt43",
   "users": ["loginId1", "loginId2", ...]
}

    Response:

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

  2.5 批量创建用户组  

    请求方式: POST

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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
userGroupsBodyJson Object List需要创建的用户组列表,包含用户组ID(外部系统的唯一ID),显示名称及上级用户组IDname:用户组名;externalGroupId:用户组id; externalParentGroupId:上级用户组ID,可缺省

    POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43",
    "userGroups": [
        {
            "name": "groupA",
            "externalGroupId": "gId1",
            "externalParentGroupId":""
        },
        {
            "name": "groupB",
            "externalGroupId": "gId2",
            "externalParentGroupId":"gId1"
        }
    ]
}

    若请求中有用户组的externalParentGroupId在当前用户组以及请求userGroups中都不存在,或者用户组父子关系逻辑成环,都将导致本次用户组创建失败(全部都不创建)。

2.6 批量修改用户组

    请求方式: POST

    请求地址:/public-api/user-groups/modify

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
userGroupsBodyJson Object List需要创建的用户组列表,包含用户组ID(外部系统的唯一ID),显示名称及上级用户组IDname:用户组名;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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得

    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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
loginIdBodyString用户ID(外部系统内的ID)必填,用户界面登录以及通过api管理用户属性的id
ugIdsBodyString List要添加的用户组id列表isExternal为true时视为外部用户组Id列表,否则为内部用户组Id列表
isExternalBodyBoolean是否是外部用户组的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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
loginIdBodyString用户ID(外部系统内的ID)必填,用户界面登录以及通过api管理用户属性的id
ugIdsBodyString List要移除的外部用户组id列表isExternal为true时视为外部用户组Id列表,否则为内部用户组Id列表。若用户不在某用户组内,接直接跳过。
isExternalBodyBoolean是否是外部用户组的Id列表默认为true

    POST Body Sample:

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

2.10 获取用户列表

    请求方式: POST

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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得

    POST Body Sample:

{
    "token":"sdjfghfodjgjshgfiw23ehrt43"
}

    Response:

{
    "result": "ok",
    "response": [
        {
            "id": 1,
            "uId": "d9f1ec1b629946b2b00f1d60",
            "name": "张三",
            "mobile": "13345678920",
            "email": "zhangsan@guandata.com",
            "loginId": "10001",
            "domId": "demo",
            "role": [
                "admin"
            ],
            "config": {
                "userProperties": {      //钉钉、企业微信等第三方登录信息以及自定义的扩展用户属性
                    "location": "",
                    "住址": "",
                    "等级": "3",
                    "dingtalk": "qqq46664345345657524553463h",
                    "部门": "12135",
                    "wechatwork": "1235",
                    "yunzhijia": "1232234121212",
                    "扩展属性1": "",
                    "扩展属性2": "",
                    "扩展属性3": ""
                }
            }
        },
        ……
    ]
}

   2.11 获取用户组列表

    请求方式: POST

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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得

    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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
ugIdurlString指定用户组的ugId-

    POST Body Sample:

{
     "token":"sdjfghfodjgjshgfiw23ehrt43" 
}

    Response格式同2.9.

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

    请求方式: POST

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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
uIdurlString指定用户的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

    参数说明:


NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得

    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

参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
pgIdurlString指定页面的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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得

    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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
dsIdurlString指定数据集的dsId-

    POST Body Sample:

{
     "token":"sdjfghfodjgjshgfiw23ehrt43" 
}

    Response同2.14.

2.18 将指定用户组下有所有者权限的资源迁移至其他用户组或用户

    请求方式: POST

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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
ugIdurlString当前资源所属用户组的ugId-
inheritorUIdsBodyString List获得权限的用户uId列表
inheritorUgIdsBodyString 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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
inheritorUIdsBodyString List获得权限的用户uId列表-
inheritorUgIdsBodyString 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

    参数说明:

NameLocation类型含义是否必填备注
tokenBodyString账户同步令牌在观远平台中获得
uIdurlString指定用户的Id-
pgTypeurlString指定LARGE_SCREEN则会返回大屏的权限信息,不指定则返回普通页面权限-

    POST Body Sample:

{
     "token":"sdjfghfodjgjshgfiw23ehrt43" 
}

    Response:

{
"result": "ok",
    "response": [
        {
            "sources": [
                {
                    "isSelf": true,
                    "id": "u969b654d7cd14610b0b246f",
                    "name": null
                }
            ],
            "isOwner": true,
            "name": "地图卡片",
            "id": "o4f72c9ea74544b52a87931c",
            "isInherit": false
        },
        {
            "sources": [
                {
                    "isSelf": true,
                    "id": "u969b654d7cd14610b0b246f",
                    "name": null
                }
            ],
            "isOwner": false,
            "name": "【T】bug复现",
            "id": "ia8f878c8bc0d4f86b9e676c"
        },
        ……
    ]
}

    Response返回的是个json object,其中result表示执行结果,response是返回的内容。response是个json array,每个单项的json对象里面,id是指资源的id(页面或者数据集),name是这个资源的名称,isOwner是个bool值,true表示是此资源的所有者。isInherit是指此资源是否是从用户组那里继承来的,如果是true,则sources里面会记录是从哪个用户组那里继承而来。如果是false,sources里面记录的是自己的用户信息。sources里面id是用户或者用户组的id,name是名字,isSelf是指是否是自己这个用户或者用户组。后面2.21--2.27的response返回值的含义,均可参考此处。

    您需要登录后才可以回复