在 Easysearch 安全系统中创建新角色或更新现有角色的权限配置。
API 格式 #
PUT /_security/role/{name}
API 作用 #
该 API 用于创建或更新安全角色：
- 创建新角色并定义其权限
- 完全更新现有角色的配置
- 定义集群级别和索引级别的权限
API 参数 #
路径参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
{name} | String | 是 | - | 角色名称 |
请求体参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
cluster | String[] | 否 | [] | 集群级别的权限列表 |
indices | Object[] | 否 | [] | 索引级别的权限配置数组 |
description | String | 否 | - | 角色的描述信息 |
reserved | Boolean | 否 | false | 是否为保留角色（仅超级管理员可设置） |
hidden | Boolean | 否 | false | 是否为隐藏角色 |
static | Boolean | 否 | false | 是否为静态角色（不可修改） |
indices 数组元素结构 #
| 字段 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
names | String[] | 是 | 索引模式列表（如 ["*"]、["logs-*"]） |
privileges | String[] | 是 | 索引权限列表（如 ["ALL"]、["READ_UT"]） |
query | String | 否 | 文档级安全查询（过滤文档） |
field_security | String[] | 否 | 可访问的字段列表 |
field_mask | String[] | 否 | 需要隐藏的字段列表 |
请求示例 #
创建管理员角色 #
PUT /_security/role/admin
{
"cluster": ["*"],
"indices": [
{
"names": ["*"],
"privileges": ["*"]
}
],
"description": "拥有所有权限的管理员角色"
}
创建只读角色 #
PUT /_security/role/readonly_user
{
"cluster": ["cluster:monitor/health"],
"indices": [
{
"names": ["logs-*"],
"field_security": ["timestamp", "message", "level"],
"privileges": ["indices:data/read/search"]
}
],
"description": "只读访问日志索引，限制字段访问"
}
创建带文档级安全的角色 #
PUT /_security/role/department_manager
{
"indices": [
{
"names": ["employee-*"],
"query": "{\"term\": {\"department\": \"engineering\"}}",
"privileges": ["READ_UT"]
}
],
"description": "只能查看工程部门的文档"
}
创建数据分析师角色 #
PUT /_security/role/data_analyst
{
"cluster": ["cluster:monitor/health", "cluster:monitor/nodes/info"],
"indices": [
{
"names": ["sales-*", "marketing-*"],
"privileges": ["READ_UT", "indices:data/read/search"],
"field_mask": ["salary", "ssn"]
},
{
"names": ["reports-*"],
"privileges": ["ALL"]
}
],
"description": "数据分析师角色，可访问销售和营销数据"
}
响应示例 #
创建成功（201 Created） #
{
"status": "CREATED",
"message": "'admin' created."
}
更新成功（200 OK） #
{
"status": "OK",
"message": "'data_analyst' updated."
}
错误响应 - 无效参数 #
{
"error": {
"root_causes": [
{
"type": "invalid_parameter_exception",
"reason": "Invalid keys [unknownkey] found"
}
],
"type": "invalid_parameter_exception",
"reason": "Invalid keys [unknownkey] found"
},
"status": 400
}
错误响应 - 权限不足 #
{
"status": "FORBIDDEN",
"message": "No permission to access REST API"
}
常用权限说明 #
集群级别权限 #
| 权限 | 描述 |
|---|---|
"*" 或 "cluster:*" | 所有集群权限 |
"cluster:monitor/health" | 监控集群健康状态 |
"cluster:monitor/nodes/info" | 获取节点信息 |
"cluster:all" | 所有集群监控权限 |
索引级别权限 #
| 权限 | 描述 |
|---|---|
"*" 或 "ALL" | 所有索引权限 |
"READ_UT" | 读取、查看和索引映射 |
"CRUD_UT" | 创建、读取、更新、删除 |
"indices:data/read/search" | 搜索权限 |
"indices:data/write/index" | 索引文档权限 |
"indices:admin/create" | 创建索引权限 |
"indices:admin/refresh" | 刷新索引权限 |
HTTP 状态码 #
| 状态码 | 描述 |
|---|---|
| 200 OK | 角色更新成功 |
| 201 Created | 角色创建成功 |
| 400 Bad Request | 无效的请求体验证错误 |
| 401 Unauthorized | 身份验证失败 |
| 403 Forbidden | 权限不足 |
| 404 Not Found | 安全配置未初始化 |
注意事项 #
- 完全替换：更新角色时需要提供完整的角色定义（部分更新使用 PATCH）
- 角色名称：角色名称在 URL 路径中指定，而非请求体中
- 权限初始化：使用此 API 前必须先初始化安全配置
- 保留角色：只有超级管理员可以设置
reserved=true - 字段掩码：
field_mask中的字段将返回为null值 - 文档级安全：
query参数使用查询 DSL 语法
相关操作 #
- GET /_security/role：查询所有角色
- GET /_security/role/{name}：查询指定角色
- DELETE /_security/role/{name}：删除角色
- PATCH /_security/role/{name}：部分更新角色
实现细节 #
- 处理器：
RolesApiAction.java - 路由：
PUT /_security/role/{name} - 验证：
RolesValidator.java验证请求参数 - 配置存储：角色配置存储在安全配置索引中
- 集群同步：配置更改会传播到所有集群节点
