用户

用户说明

用户的定义

HENGSHI 系统内的用户及 SSO 认证后自动创建用户，主要信息由登录名、邮箱、姓名、手机号码、用户属性等组成。如果在系统中通过api创建了用户，再使用 SSO 认证是可以自动关联用户的。如：通过api创建了用户loginName=demoTest，当通过 SSO 认证时的loginName也是demoTest，那么不会再自动创建用户，而是将以demoTest的身份进行登录。关联的优先级是loginName，email，mobile。

用户结构说明

字段	类型	是否必须	描述
id	LONG	否	id
loginName	STRING	loginName,email不能同时为空	登录名，企业内不能重复。
email	STRING	loginName,email不能同时为空	邮箱，企业内不能重复。
password	STRING	重置密码时使用，填写当前登录用户的密码	公钥加密密码，用base64格式进行编码。重置密码时验证当前用户身份的验证字段。
newPassword	STRING	不使用密码登录时可以不设置	公钥加密密码，用base64格式进行编码。填写需保存的用户密码。
uuid	STRING	公钥对应的uuid	解密使用。
mobile	STRING	否	手机，企业内不能重复。
name	STRING	否	显示名称(昵称)
userType	STRING	否	默认为internal，可选值：internal,ldap,cas,oauth2,saml2,dingtalk,wechat-work,ctr,yunzhijia,jwt-param,lark
description	STRING	否	用户备注
avatar	STRING	否	用户头像
roles	JSON 数组	否	角色
roles[].id	LONG	否	角色id
organizations	JSON 数组	否	用户组
organizations[].id	LONG	否	用户组id
orgs	JSON 数组	否	用户组织架构
orgs[].id	LONG	否	用户组织架构id
platformConfig	JSON	否	用户通过sso方式登陆同步的全局属性
config	JSON	否	用户属性，其内容为自定义的用户属性，如：{"school":"a","grade":3}
resetPassword	BOOLEAN	否	用户登录以后是否需要重置密码。管理员重置用户密码时，不支持 API 更新该字段

config字段说明：

用户可以在页面创建用户属性并赋值。

用户可以通过api调用传递用户属性，需要以用户结构说明中的config，如：

{
   "loginName":"demoUser001",
   "config":{
       "text":"a",
       "number":1,
       "array":[
           "test1"
       ]
   }
}

oauth，jwt认证方式登录时会将除登录名，用户名，邮箱，手机，角色以外的json字段自动封装成用户属性，如下json，会将school、grade封装成用户属性，保存到用户的config字段。

json

{
    "loginName":"loginName",//登录名映射
    "email":"email",//邮箱映射
    "mobile":"mobile",//手机映射
    "name":"name",//用户名映射
    "school":"a",//用户属性
    "grade":3 //用户属性
}

钉钉，企业微信，云之家，飞书认证方式登录时会将除登录名，用户名，邮箱，手机，角色以外的json自动封装成用户属性。具体的用户信息由钉钉，企业微信，云之家，飞书接口返回，请参考官方文档。

角色结构说明

字段	类型	是否必须	描述
id	LONG	是	id
name	STRING	是	角色名称
description	STRING	是	角色描述

角色是系统内置数据,不可更新, 系统内角色有:

name	角色
system admin	系统管理
data admin	数据管理
data analyst	数据分析
data viewer	数据查看
api admin	API 管理员

用户组结构说明

字段	类型	是否必须	描述
id	LONG	否	id
name	STRING	是	名称
email	STRING	否	邮箱
description	STRING	否	用户组备注
users	JSON 数组	否	用户
users[].id	LONG	否	角色id

接口说明

获取角色列表

获取角色列表。

请求URL

http

GET /api/users/roles HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request body 参数

无

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见角色结构说明

接口示例1: 获取角色列表

RequestResponse

http

GET /api/users/roles HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
   "version": "version@9a5e106#6730f0d",
   "code":0,
   "msg":"success",
   "data":[
      {
         "id":1,
         "name":"system admin",
         "description":"system admin"
      },
      {
         "id":2,
         "name":"data admin",
         "description":"data admin"
      },
      {
         "id":3,
         "name":"data analyst",
         "description":"data analyst"
      },
      {
         "id":4,
         "name":"data viewer",
         "description":"data viewer"
      },
      {
         "id":5,
         "name":"api admin",
         "description":"api admin"
      }
   ]
}

创建用户

创建用户。

请求URL

http

POST /api/users HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request body 参数

用户结构说明密码加密

说明

用户属性需要放在config字段中传递

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data.id	LONG	用户的 id

用户默认头像

avatar

接口示例1: 创建用户（完整信息）

包含基本完整的用户信息，创建成功以后，用户可以根据登录名和密码登录。使用场景多为预先创建，配置用户，使用用户名/密码方式登录使用系统。

RequestResponse

http

POST /api/users HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "loginName":"demoUser001",
  "name":"demoUser001",
  "email":"anonymous@hengshi.com",
  "newPassword":"duk5ZIVdikKtU9txy0aMZlLPJ8hntpINLx2hBWiJw8sYfSxSQ/pkSBRv85s/ROQb45J4R8MsCrN7VQkhONMoGQ==",
  "description":"desc",
  "uuid":"488b4801-1f50-4694-b0e1-7bd8fea4869f",
  "roles":[
      {
          "id":3
      },
      {
          "id":4
      },
      {
          "id":2
      }
  ],
  "config":{
    "text":"a",
    "number":1,
    "array":["test1"]
  },
  "organizations":[
      {
          "id":25
      }
  ],
  "orgs":[
    {
        "id":25
    }
  ],
  "avatar":"..."
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success",
    "data":{
        "id":800
    }
}

接口示例2: 创建用户（必要信息）

只包含必要的用户信息，使用场景多为预先创建，根据需要配置用户角色(roles)，用户属性(config)等，之后使用其他的认证方式(如单点登录，jwt等)登录使用系统。

RequestResponse

http

POST /api/users HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
   "loginName": "13333333333",
   "roles": [
      {
         "id": 1
      }
   ]
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success",
    "data":{
        "id":800
    }
}

管理员修改用户

管理员修改用户。

请求URL

http

PUT /api/users/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
userId	LONG	是	修改用户的 id

request body 参数

用户结构说明密码加密

说明

用户属性需要放在config字段中传递

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值

修改用户属性说明

若在更新用户时通过config修改用户属性,则需要传被修改用户的全量属性,该修改为直接覆盖,没有传的属性都会被置空

重制密码说明

4.1版本以后该接口不再支持修改密码功能，可调用管理员重置用户密码 4.3版本以后该接口不再支持启用/禁用用户，可调用管理员启用/停用用户

接口示例1: 修改用户

RequestResponse

http

PUT /api/users/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "enable":true,
  "description":"desc",
  "roles":[
      {
          "id":2
      },
      {
          "id":3
      },
      {
          "id":4
      }
  ],
  "config":{
      "text":"a",
      "number":1,
      "array":["test1"]
  },
  "organizations":[
      {
          "id":25
      }
  ],
  "orgs":[
    {
        "id":25
    }
  ]
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success"
}

接口示例2: 修改用户(用户属性)

RequestResponse

http

PUT /api/users/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "description": "",
  "uuid": "ab999a4c-3c79-4de2-9e96-d26a814c3d70",
  "config": {
    "a1": "测试",
    "a2": [
      "测试1","测试2"
    ],
    "t": "2020-07-23 16:11:00",
    "n": 1
  },
  "roles": [
    {
      "id": 1
    },
    {
      "id": 2
    },
    {
      "id": 3
    },
    {
      "id": 4
    }
  ],
  "organizations": [
    {
      "id": 2
    }
  ]
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

管理员重置用户密码

管理员重置用户密码。

请求URL

http

PUT /api/users/{userId}/reset-password HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
userId	LONG	是	修改用户的 id

request body 参数

用户结构说明密码加密

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值

接口示例1: 管理员重置密码

RequestResponse

http

PUT /api/users/{userId}/reset-password HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "password": "UEDK5yrm3xswER2JgWvMELLR3aETo76qKBOg5PW/4pDsP9270a+mYE5kkWXFfHYUqiZtPsC4Apumis3BG3oUlw==",
  "newPassword": "asxasdfweswER2JgWvMELLR3aETo76qKBOg5PW/4pDsP9270a+mYE5kkWXFfHYUqiZtff234141aaaaa====",
  "uuid": "68a5d0c6-5a33-45d6-833a-9b70c961a77a"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success"
}

管理员启用/停用用户

管理员启用/停用用户。

请求URL

http

PUT /api/users/batch-enable HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

request body 参数

字段	类型	是否必须	说明
enable	BOOLEAN	是	启用：true，停用：false
users	JSON数组	是	用户数组
users[].id	LONG	是	用户id

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值

接口示例1: 管理员启用、停用用户

RequestResponse

http

PUT /api/users/batch-enable HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
   "users":[
      {
         "id":26
      }
   ],
   "enable":false
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success"
}

用户自行修改帐号信息

请求URL

http

PUT /api/users/account/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
userId	LONG	是	修改用户的 id

request body 参数

用户结构说明密码加密

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值

用户可修改的信息

通过该接口用户可修改用户的名称,头像,密码,使用语言

修改密码说明

若调用该接口修改用户密码,与管理员修改接口不同的时,该密码就直接作为用户登陆密码使用,无需再次被强制要求修改

不可同时更改多项信息

名称,头像,密码,使用语言一次调用只能修改其中一项,若四个参数都传,则按照密码>头像>名称>使用语言的顺序修改其中一项

接口示例1: 修改用户名称

RequestResponse

http

PUT /api/users/account/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "name": "test1"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

接口示例2: 修改密码

RequestResponse

http

PUT /api/users/account/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "uuid": "7a292f10-9db4-4d7a-b8cb-f29fdfb86e58",
  "password": "QziD1WxdWSJjAdsx0YrRnOxItgPVoZNNAQVsz0X4/rzNehqtPxtcaWU7UQD2N4dIvDkfhxv/0EUjLL3BssoRtw==",
  "newPassword": "P5vmmFYGYRsasXx0/v3LauKN041OipE19xAPP+AKGDrNwkITzDlw5q0GFoy5jwH7tld8a3GJbvAZg9fqz1Pb+w=="
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

接口示例3: 修改头像

RequestResponse

http

PUT /api/users/account/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

接口示例4: 修改使用语言

RequestResponse

http

PUT /api/users/account/{userId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "options": {
    "language": "en-US"
  }
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

用户是否持有可用资源

说明

用户是否持有可用资源

请求URL

http

GET /api/users/{userId}/available-resources HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL Path 参数

字段	类型	是否必须	说明
userId	LONG	是	修改用户的 id

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	BOOLEAN	用户是否持有可用资源

接口示例1: 用户是否持有可用资源

RequestResponse

http

GET /api/users/{userId}/available-resources HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
   "data": true,
  "msg": "success"
}

删除用户

说明

若用户拥有任意未删除或转移给其他用户的资源(应用、链接、数据集成、数据科学),则不可删除用户

请求URL

http

DELETE /api/users/{userId} HTTP/1.1

请求参数

URL 参数

字段	类型	是否必须	说明
userId	LONG	是	修改用户的 id

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例1: 删除用户

RequestResponse

http

DELETE /api/users/{userId} HTTP/1.1

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

通过id查询用户

请求URL

http

GET /api/users/details/{userId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL Path 参数

字段	类型	是否必须	说明
id	Long	是	用户的 id

request body 参数

无

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例:

RequestResponse

http

GET /api/users/details/{userId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 2,
    "name": "helloa",
    "email": "helloa@163.com",
    "description": "",
    "avatar": "",
    "enable": true,
    "createdAt": "2019-11-15 15:18:36",
    "lastLoginAt": "2020-09-16 11:49:38",
    "userType": "internal",
    "isDelete": false,
    "loginName": "hello"
  }
}

通过loginName查询用户

请求URL

http

POST /api/users/get-by-loginname HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request body 参数

字段	类型	是否必须	说明
loginName	STRING	是	用户的 loginName

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例:

RequestResponse

http

POST /api/users/get-by-loginname HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "loginName": "helloa"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 2,
    "name": "helloa",
    "email": "helloa@163.com",
    "description": "",
    "avatar": "",
    "enable": true,
    "createdAt": "2019-11-15 15:18:36",
    "lastLoginAt": "2020-09-16 11:49:38",
    "userType": "internal",
    "isDelete": false,
    "loginName": "hello"
  }
}

通过email查询用户

请求URL

http

POST /api/users/get-by-email HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request body 参数

字段	类型	是否必须	说明
email	STRING	是	用户的 email

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例:

RequestResponse

http

POST /api/users/get-by-email HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "email": "helloa@163.com"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 2,
    "name": "helloa",
    "email": "helloa@163.com",
    "description": "",
    "avatar": "",
    "enable": true,
    "createdAt": "2019-11-15 15:18:36",
    "lastLoginAt": "2020-09-16 11:49:38",
    "userType": "internal",
    "isDelete": false,
    "loginName": "hello"
  }
}

通过mobile查询用户

请求URL

http

POST /api/users/get-by-mobile HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request body 参数

字段	类型	是否必须	说明
mobile	STRING	是	用户的 email

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例:

RequestResponse

http

POST /api/users/get-by-mobile HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "mobile": "13012344321"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 2,
    "name": "helloa",
    "email": "helloa@163.com",
    "description": "",
    "avatar": "",
    "mobile": "13012344321",
    "enable": true,
    "createdAt": "2019-11-15 15:18:36",
    "lastLoginAt": "2020-09-16 11:49:38",
    "userType": "internal",
    "isDelete": false,
    "loginName": "hello"
  }
}

通过用户id获取用户组和组织机构

请求URL

http

GET /api/users/orgs-organizations?userId={userId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request Query 参数

字段	类型	是否必须	说明
userId	LONG	是	用户的 id

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	包含用户组和树形组织架构
data.organizations	JSONOBJECT ARRAY	见用户组结构说明
data.orgTree	JSONOBJECT	见组织结构说明
data.orgTree.children	JSONOBJECT	下级组织，见组织结构说明

接口示例:通过用户id获取用户组和组织机构

RequestResponse

http

GET /api/users/orgs-organizations?userId={userId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
   "version": "version@9a5e106#6730f0d",
   "code":0,
   "msg":"success",
   "data":{
      "organizations":[
         {
            "id":6431,
            "name":"API用户组",
            "description":"API用户组",
            "category":"NORMAL"
         }
      ],
      "orgTree":[
         {
            "id":1,
            "name":"衡石QA测试",
            "description":"",
            "createdBy":11630,
            "createdAt":"2023-07-12 15:23:48",
            "updatedBy":11630,
            "updatedAt":"2023-07-12 15:23:48",
            "source":"dingtalk",
            "code":"1",
            "orderNo":1,
            "children":[
               {
                  "id":25,
                  "name":"测试部",
                  "description":"",
                  "createdBy":11630,
                  "createdAt":"2023-07-12 15:23:48",
                  "updatedBy":11630,
                  "updatedAt":"2023-07-12 15:23:48",
                  "parentId":1,
                  "source":"dingtalk",
                  "code":"490184122",
                  "parentCode":"1",
                  "orderNo":3,
                  "delete":false
               }
            ],
            "delete":false
         }
      ]
   }
}

通过 loginName 或者 email 查询用户(不推荐使用)，4.5之后的版本将不再支持

请参考通过loginName查询用户通过email查询用户通过mobile查询用户

请求URL

http

GET /api/users/by-unique-key/{loginName or email} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
loginName or email	STRING	是	用户的 loginName 或者 email

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例: 通过 loginName 或者 email 查询用户（不推荐使用）

http

GET /api/users/by-unique-key/{loginName or email} HTTP/1.1
Accept: application/json

// Response:
{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 2,
    "name": "helloa",
    "email": "helloa@163.com",
    "description": "",
    "avatar": "",
    "enable": true,
    "createdAt": "2019-11-15 15:18:36",
    "lastLoginAt": "2020-09-16 11:49:38",
    "userType": "internal",
    "isDelete": false,
    "loginName": "hello"
  }
}

获取用户列表

请求URL

http

GET /api/users HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

Query 参数

字段	类型	是否必须	说明
returnAvatar	BOOLEAN	否	是否返回用户头像，默认为true
returnAttr	BOOLEAN	否	是否返回用户头像，默认为false
q	STRING	否	用户显示名或登录名（like查询）
organizations	LONG	否	用户组id
roles	LONG	否	用户角色id
offset	INT	否	分页偏移量
limit	INT	否	分页大小

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例1: 获取用户列表

RequestResponse

http

GET /api/users?offset=0&limit=100&q=test&roles=1&roles=2 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 2,
      "name": "test2",
      "email": "anonymous@hengshi.com",
      "description": "",
      "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAADAFBMVEXw8PAmstgA51gGMdj3GfUAAAAASUVORK5CYII=",
      "enable": true,
      "userType": "internal",
      "loginName": "test2",
      "config": {
        "sys.email": {
          "source": "SYSTEM_DEFINED",
          "value": "anonymous@hengshi.com",
          "type": "string"
        },
        "sys.login_name": {
          "source": "SYSTEM_DEFINED",
          "value": "test2",
          "type": "string"
        },
        "sys.mobile": {
          "source": "SYSTEM_DEFINED",
          "type": "string"
        },
        "sys.id": {
          "source": "SYSTEM_DEFINED",
          "value": 2,
          "type": "number"
        },
        "sys.loginName": {
          "source": "SYSTEM_DEFINED",
          "value": "test2",
          "type": "string"
        },
        "m_names": {
          "source": "USER_DEFINED",
          "value": [
            "盗梦空间",
            "搏击俱乐部"
          ],
          "type": "any"
        },
        "sys.name": {
          "source": "SYSTEM_DEFINED",
          "value": "test2",
          "type": "string"
        },
        "n_name": {
          "source": "USER_DEFINED",
          "value": "饮食男女",
          "type": "any",
          "defaultValue": "搏击俱乐部"
        }
      },
      "options": {},
      "roles": [
        {
          "id": 1,
          "name": "system admin",
          "description": "system admin"
        },
        {
          "id": 2,
          "name": "data admin",
          "description": "data admin"
        },
        {
          "id": 3,
          "name": "data analyst",
          "description": "data analyst"
        },
        {
          "id": 4,
          "name": "data viewer",
          "description": "data viewer"
        }
      ],
      "organizations": []
    },
    {
      "id": 9,
      "name": "test4",
      "email": "anonymous@hengshi.com",
      "description": "",
      "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAADAFBMVEXw8PAm2JAAm7YIceE7dPMAAAAASUVORK5CYII=",
      "enable": true,
      "userType": "internal",
      "loginName": "test4",
      "config": {
        "sys.email": {
          "source": "SYSTEM_DEFINED",
          "value": "anonymous@hengshi.com",
          "type": "string"
        },
        "sys.login_name": {
          "source": "SYSTEM_DEFINED",
          "value": "test4",
          "type": "string"
        },
        "sys.mobile": {
          "source": "SYSTEM_DEFINED",
          "type": "string"
        },
        "sys.id": {
          "source": "SYSTEM_DEFINED",
          "value": 9,
          "type": "number"
        },
        "sys.loginName": {
          "source": "SYSTEM_DEFINED",
          "value": "test4",
          "type": "string"
        },
        "sys.name": {
          "source": "SYSTEM_DEFINED",
          "value": "test4",
          "type": "string"
        }
      },
      "options": {},
      "roles": [
        {
          "id": 1,
          "name": "system admin",
          "description": "system admin"
        },
        {
          "id": 2,
          "name": "data admin",
          "description": "data admin"
        },
        {
          "id": 3,
          "name": "data analyst",
          "description": "data analyst"
        },
        {
          "id": 4,
          "name": "data viewer",
          "description": "data viewer"
        }
      ],
      "organizations": []
    }
  ]
}

获取用户简单信息列表

请求URL

http

GET /api/users/simplify HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

无

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例1: 获取用户简单信息列表

RequestResponse

http

GET /api/users/simplify HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 2,
      "name": "test2",
      "loginName": "test2",
       "email":"anonymous@hengshi.com"
    }
  ]
}

获得可被授权的用户列表

请求URL

http

GET /api/users/grantors HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL Query 参数

字段	类型	是否必须	说明
act	STRING	是	授权类型,可选值:collaborate(协作),publish(发布)
resource	STRING	是	资源类型,可选值:app(应用),connection(链接)

说明

资源类型为connection时,授权类型不可为publish
当条件为app&collaborate时,返回的时系统中拥有数据分析角色的用户
当条件为app&publish时,返回的时系统中拥有数据查看角色的用户
当条件为connection&collaborate时,返回的时系统中拥有数据分析或数据管理角色的用户

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见用户结构说明。

接口示例1: 获得可被授权的用户列表

RequestResponse

http

GET /api/users/grantors?act=collaborate&resource=app HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 41,
      "name": "test",
      "email": "anonymous@hengshi.com",
      "description": "",
      "enable": true,
      "loginName": "test",
      "config": {},
            "options": {}
        },
        {
            "id": 2,
            "name": "test2",
            "email": "anonymous@hengshi.com",
            "description": "",
            "enable": true,
            "loginName": "test2",
            "config": {
                "m_names": "[\"盗梦空间\",\"搏击俱乐部\"]",
                "n_name": "饮食男女"
            },
            "options": {}
        },
        {
            "id": 9,
            "name": "test4",
            "email": "anonymous@hengshi.com",
            "description": "",
            "enable": true,
            "loginName": "test4",
            "config": {},
            "options": {}
        }
    ]
}

新增用户组

新增用户组。

请求URL

http

POST /api/organizations HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request body 参数

用户组结构说明

返回对象的格式说明

用户组结构说明

接口示例1: 新增用户组

RequestResponse

http

POST /api/organizations HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
    "name":"zjj_group",
    "email":"anonymous@hengshi.com",
    "description":"desc",
    "users":[
        {
            "id":800
        }
    ]
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success",
    "data":{
        "id":36,
        "name":"zjj_group",
        "email":"anonymous@hengshi.com",
        "description":"desc",
        "createdBy":1,
        "createdAt":"2019-12-18 20:44:47",
        "updatedBy":1,
        "updatedAt":"2019-12-18 20:44:47",
        "users":[
            {
                "id":800,
                "userAttributes":{
                    "sys.id":800
                }
            }
        ]
    }
}

获取用户组列表

请求URL

http

GET /api/organizations HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

无

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	参数的共同结构见用户组结构说明。

接口示例1: 获取用户组列表

RequestResponse

http

GET /api/organizations HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "ALL_USERS",
      "description": "System organization for all users",
      "category": "ALL_USERS",
      "userCount": 0,
      "users": []
    },
    {
      "id": 3,
      "name": "o4",
      "description": "",
      "category": "NORMAL",
      "userCount": 0,
      "users": []
    },
    {
      "id": 4,
      "name": "o42",
      "description": "",
      "category": "NORMAL",
      "userCount": 0,
      "users": []
    },
    {
      "id": 2,
      "name": "o1",
      "description": "",
      "category": "NORMAL",
      "userCount": 0,
      "users": []
    }
  ]
}

根据ID获取用户组

请求URL

http

GET /api/organizations/{organizationId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

无

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	参数的共同结构见用户组结构说明。

接口示例1: 根据ID获取用户组

RequestResponse

http

GET /api/organizations/2 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 2,
    "name": "o1",
    "description": "",
    "category": "NORMAL",
    "userCount": 2,
    "users": [
      {
        "id": 2,
                "name": "test2",
                "email": "anonymous@hengshi.com",
                "description": ""
            },
            {
                "id": 9,
                "name": "test4",
                "email": "anonymous@hengshi.com",
                "description": ""
            }
        ]
    }
}

修改用户组

修改用户组。

请求URL

http

PUT /api/organizations/{organizationId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
organizationId	LONG	是	修改用户组的 id

request body 参数

用户组结构说明

返回对象的格式说明

用户组结构说明

接口示例1: 修改用户组

RequestResponse

http

PUT /api/organizations/${organizationId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
    "name":"zjj_group",
    "email":"anonymous@hengshi.com",
    "description":"desc",
    "users":[
        {
            "id":800
        }
    ]
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success",
    "data":{
        "id":36,
        "name":"zjj_group",
        "email":"anonymous@hengshi.com",
        "description":"desc",
        "updatedBy":1,
        "updatedAt":"2019-12-18 20:46:51",
        "users":[
            {
                "id":800,
                "userAttributes":{
                    "$user.config.id":800,
                    "$user.id":800
                }
            }
        ]
    }
}

删除用户组

删除用户组。

请求URL

http

DELETE /api/organizations/{organizationId} HTTP/1.1

请求参数

URL 参数

字段	类型	是否必须	说明
organizationId	LONG	是	修改用户组的 id

request body 参数

无

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值

接口示例1: 删除用户组

RequestResponse

http

DELETE /api/organizations/${organizationId} HTTP/1.1

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code":0,
    "msg":"success"
}

用户 ​

用户说明 ​

用户的定义 ​

用户结构说明 ​

角色结构说明 ​

用户组结构说明 ​

接口说明 ​

获取角色列表 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 参数 ​

返回对象的格式说明 ​

接口示例1: 获取角色列表 ​

创建用户 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 参数 ​

说明 ​

返回对象的格式说明 ​

用户默认头像 ​

接口示例1: 创建用户（完整信息） ​

接口示例2: 创建用户（必要信息） ​

管理员修改用户 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 参数 ​

说明 ​

返回对象的格式说明 ​

修改用户属性说明 ​

重制密码说明 ​

接口示例1: 修改用户 ​

接口示例2: 修改用户(用户属性) ​

管理员重置用户密码 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 参数 ​

返回对象的格式说明 ​

接口示例1: 管理员重置密码 ​

管理员启用/停用用户 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 参数 ​

返回对象的格式说明 ​

接口示例1: 管理员启用、停用用户 ​

用户自行修改帐号信息 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 参数 ​

返回对象的格式说明 ​

用户可修改的信息 ​

修改密码说明 ​

不可同时更改多项信息 ​

接口示例1: 修改用户名称 ​

接口示例2: 修改密码 ​

接口示例3: 修改头像 ​

接口示例4: 修改使用语言 ​

用户是否持有可用资源 ​

说明 ​

请求URL ​

请求参数 ​

URL Path 参数 ​

返回对象的格式说明 ​

接口示例1: 用户是否持有可用资源 ​

删除用户 ​

说明 ​

请求URL ​

请求参数 ​

URL 参数 ​

返回对象的格式说明 ​

接口示例1: 删除用户 ​

通过id查询用户 ​

请求URL ​

请求参数 ​

URL Path 参数 ​

用户

用户说明

用户的定义

用户结构说明

角色结构说明

用户组结构说明

接口说明

获取角色列表

请求URL

请求参数

URL 参数

request body 参数

返回对象的格式说明

接口示例1: 获取角色列表

创建用户

请求URL

请求参数

URL 参数

request body 参数

说明

返回对象的格式说明

用户默认头像

接口示例1: 创建用户（完整信息）

接口示例2: 创建用户（必要信息）

管理员修改用户

请求URL

请求参数

URL 参数

request body 参数

说明

返回对象的格式说明

修改用户属性说明

重制密码说明

接口示例1: 修改用户

接口示例2: 修改用户(用户属性)

管理员重置用户密码

请求URL

请求参数

URL 参数

request body 参数

返回对象的格式说明

接口示例1: 管理员重置密码

管理员启用/停用用户

请求URL

请求参数

URL 参数

request body 参数

返回对象的格式说明

接口示例1: 管理员启用、停用用户

用户自行修改帐号信息

请求URL

请求参数

URL 参数

request body 参数

返回对象的格式说明

用户可修改的信息

修改密码说明

不可同时更改多项信息

接口示例1: 修改用户名称

接口示例2: 修改密码

接口示例3: 修改头像

接口示例4: 修改使用语言

用户是否持有可用资源

说明

请求URL

请求参数

URL Path 参数

返回对象的格式说明

接口示例1: 用户是否持有可用资源

删除用户

说明

请求URL

请求参数

URL 参数

返回对象的格式说明

接口示例1: 删除用户

通过id查询用户

请求URL

请求参数

URL Path 参数