User API

概述

User API是用于管理 Fess 用户账户的REST API。 您可以创建、获取、更新、删除用户，以及分配角色和组。

这是一个管理用API，使用时需要通过管理员访问令牌进行认证。 有关认证方式和公共规格，请参阅 Admin API 概述。

所有响应均包装在 response 对象中，并包含以下公共字段：

  • version ：Fess 产品版本字符串。

  • status ：处理结果状态码（0 =成功，1 =请求错误，2 =系统错误，3 =未授权，9 =失败）。

基础URL

/api/admin/user

端点列表

方法 路径 说明
GET /settings 获取用户列表
GET /setting/{id} 获取用户
POST /setting 创建用户
PUT /setting 更新用户
DELETE /setting/{id} 删除用户

获取用户列表

请求

GET /api/admin/user/settings

参数

参数 类型 必需 说明
size Integer 否 每页记录数。默认值为配置项 paging.page.size 的值（默认：25）。
page Integer 否 页码（从1开始）。默认值为1。

Note

在当前实现中，获取用户列表端点不应用 size 和 page 参数。 始终返回第一页，记录数由服务器设置 paging.page.size 决定（默认：25），并按用户名（name）升序排序。 匹配用户的总数可通过 response.total 获取。

响应

{
  "response": {
    "version": "15.9",
    "status": 0,
    "settings": [
      {
        "id": "YWRtaW4=",
        "name": "admin",
        "attributes": {
          "surname": "Administrator",
          "givenName": "System",
          "mail": "admin@example.com"
        },
        "roles": ["YWRtaW4=", "Z3Vlc3Q="],
        "groups": [],
        "version_no": 1
      }
    ],
    "total": 10
  }
}

  • settings ：当前页包含的用户数组。

  • total ：匹配条件的用户总数。

获取用户

请求

GET /api/admin/user/setting/{id}

在 {id} 中指定目标用户的文档ID。

响应

{
  "response": {
    "version": "15.9",
    "status": 0,
    "setting": {
      "id": "YWRtaW4=",
      "name": "admin",
      "attributes": {
        "surname": "Administrator",
        "givenName": "System",
        "mail": "admin@example.com",
        "telephoneNumber": "",
        "uidNumber": "",
        "gidNumber": "",
        "homeDirectory": ""
      },
      "roles": ["YWRtaW4=", "Z3Vlc3Q="],
      "groups": [],
      "version_no": 1
    }
  }
}

Note

attributes 包含用户存储的所有属性，但不包含 name、password、roles 和 groups。 password 不包含在响应中。

创建用户

请求

POST /api/admin/user/setting
Content-Type: application/json

请求体

{
  "name": "testuser",
  "password": "securepassword",
  "confirm_password": "securepassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User",
    "mail": "testuser@example.com"
  },
  "roles": ["Z3Vlc3Q="],
  "groups": ["group_id_1"]
}

字段说明

字段 必需 说明
name 是 用户名（登录ID）
password 是 密码
confirm_password 否 确认密码
attributes 否 属性映射（见下文）
roles 否 角色ID数组
groups 否 组ID数组

Note

roles 和 groups 中请指定 ID，而不是名称。不存在的 ID（包括角色名、组名）会被以 400 拒绝。ID 可通过 GET /api/admin/role/settings 和 GET /api/admin/group/settings 返回的 id 确认。在管理界面或通过 API 创建的角色、组的 ID，是将名称进行 Base64 URL 编码后的值（例如默认存在的角色 admin 为 YWRtaW4= ， guest 为 Z3Vlc3Q= ）。

Note

密码会进行与管理界面相同的验证。创建时省略 password、指定了与 password 不一致的 confirm_password （ confirm_password 可以省略），或密码违反密码策略（ fess_config.properties 中的 password.min.length （默认值 8 ）、 password.max.length 、 password.require.* 、 password.invalid.admin.passwords ）时，都会被以 400 拒绝。

attributes 的键为用户实体的属性名（源自LDAP的模式项目名）。 常用的键如下：

  • surname、givenName、displayName、mail

  • telephoneNumber、mobile、homePhone

  • employeeNumber、title、description、homeDirectory

  • uidNumber、gidNumber

uidNumber 和 gidNumber 必须为数值（在更新时会进行类型验证）。 此外，还可以指定许多其他LDAP属性键。

Note

创建时，用户ID（文档ID）会自动生成为用户名的Base64 URL编码值 （例如，用户名 admin 对应 YWRtaW4=）。

响应

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "new_user_id",
    "created": true
  }
}

  • id ：创建的用户的文档ID。

  • created ：创建成功时为 true。

更新用户

请求

PUT /api/admin/user/setting
Content-Type: application/json

请求体

{
  "id": "existing_user_id",
  "name": "testuser",
  "password": "newpassword",
  "confirm_password": "newpassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User Updated",
    "mail": "testuser.updated@example.com"
  },
  "roles": ["Z3Vlc3Q=", "YWRtaW4="],
  "groups": ["group_id_1", "group_id_2"],
  "version_no": 1
}

字段说明

字段 必需 说明
id 是 要更新的用户的文档ID。
name 是 用户名（登录ID）
version_no 是 版本号（用于乐观锁）
password 否 新密码（仅在指定时更新）
confirm_password 否 确认密码
attributes 否 属性映射（参见”创建用户”）
roles 否 角色ID数组
groups 否 组ID数组

Note

更新时，id、name 和 version_no 为必填项。 version_no 是获取目标用户（GET）时返回的值，对应OpenSearch文档的版本号。 如果与当前版本不匹配，请求将被视为冲突并拒绝更新。

响应

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "existing_user_id",
    "created": false
  }
}

  • created ：更新时为 false。

删除用户

请求

DELETE /api/admin/user/setting/{id}

在 {id} 中指定要删除的用户的文档ID。

Note

无法删除当前已登录的用户。

响应

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "deleted_user_id",
    "created": false
  }
}

  • id ：已删除用户的文档ID。

使用示例

创建新用户

curl -X POST "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "john.doe",
       "password": "SecureP@ss123",
       "confirm_password": "SecureP@ss123",
       "attributes": {
         "surname": "Doe",
         "givenName": "John",
         "mail": "john.doe@example.com"
       },
       "roles": ["Z3Vlc3Q="],
       "groups": []
     }'

更改用户角色

curl -X PUT "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "user_id_123",
       "name": "john.doe",
       "roles": ["Z3Vlc3Q=", "YWRtaW4="],
       "version_no": 1
     }'

参考信息