---
title: "查询安全角色"
date: 2026-02-04
lastmod: 2026-02-04
description: "查询安全角色配置"
tags: ["安全", "角色", "查询"]
summary: "获取 Easysearch 中的安全角色配置信息。
API 格式 #  GET /_security/role GET /_security/role/{name} API 作用 #  该 API 用于检索安全角色的配置信息：
 GET /_security/role：获取所有角色 GET /_security/role/{name}：获取指定角色  API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {name} String 否 - 要查询的角色名称。如未指定，返回所有角色    查询参数 #     参数 类型 是否必填 默认值 描述     name String 否 所有角色 逗号分隔的角色名称列表    请求示例 #  获取所有角色 #  GET /_security/role 获取指定角色 #  GET /_security/role/admin 获取多个角色 #  GET /_security/role?"
---


获取 Easysearch 中的安全角色配置信息。

## API 格式

```
GET /_security/role
GET /_security/role/{name}
```

## API 作用

该 API 用于检索安全角色的配置信息：
- **GET /_security/role**：获取所有角色
- **GET /_security/role/{name}**：获取指定角色

## API 参数

### 路径参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `{name}` | String | 否 | - | 要查询的角色名称。如未指定，返回所有角色 |

### 查询参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `name` | String | 否 | 所有角色 | 逗号分隔的角色名称列表 |

## 请求示例

### 获取所有角色

```
GET /_security/role
```

### 获取指定角色

```
GET /_security/role/admin
```

### 获取多个角色

```
GET /_security/role?name=admin,user,developer
```

## 响应示例

### 获取所有角色响应

```json
{
  "admin": {
    "cluster": ["*"],
    "indices": [
      {
        "names": ["*"],
        "privileges": ["*"],
        "query": null,
        "field_security": [],
        "field_mask": []
      }
    ],
    "description": "管理员角色",
    "reserved": false,
    "hidden": false,
    "static": false
  },
  "data_analyst": {
    "cluster": ["cluster:monitor/health"],
    "indices": [
      {
        "names": ["logs-*", "metrics-*"],
        "privileges": ["READ_UT"],
        "query": null,
        "field_security": ["timestamp", "message", "level"],
        "field_mask": []
      }
    ],
    "description": "数据分析师角色",
    "reserved": false,
    "hidden": false,
    "static": false
  },
  "kibana_user": {
    "cluster": ["cluster:monitor/health"],
    "indices": [
      {
        "names": [".kibana*"],
        "privileges": ["ALL"]
      }
    ],
    "description": "Kibana 用户角色",
    "reserved": false,
    "hidden": false,
    "static": false
  }
}
```

### 获取指定角色响应

```json
{
  "admin": {
    "cluster": ["cluster:monitor*", "cluster:all"],
    "indices": [
      {
        "names": ["sf", "pub"],
        "privileges": ["SECURITY_CRUD"],
        "query": null,
        "field_security": [],
        "field_mask": []
      }
    ],
    "description": "管理员角色",
    "reserved": false,
    "hidden": false,
    "static": false
  }
}
```

### 错误响应 - 权限不足

```
403 Forbidden
```

```json
{
  "error": "Authentication required"
}
```

### 错误响应 - 角色不存在（非超级管理员）

```
404 Not Found
```

```json
{
  "status": 404,
  "error": "role 'hidden_role' not found"
}
```

## 响应字段说明

### 顶层字段

| 字段 | 类型 | 描述 |
|------|------|------|
| `{role_name}` | Object | 以角色名称为键的角色配置对象 |

### 角色配置字段

| 字段 | 类型 | 描述 |
|------|------|------|
| `cluster` | String[] | 集群级别的权限列表 |
| `indices` | Object[] | 索引级别的权限配置数组 |
| `description` | String | 角色的描述信息 |
| `reserved` | Boolean | 是否为保留角色（系统角色） |
| `hidden` | Boolean | 是否为隐藏角色 |
| `static` | Boolean | 是否为静态角色（不可修改） |

### indices 数组元素字段

| 字段 | 类型 | 描述 |
|------|------|------|
| `names` | String[] | 索引模式列表 |
| `privileges` | String[] | 权限列表 |
| `query` | String/null | 文档级安全查询 |
| `field_security` | String[] | 可访问的字段列表 |
| `field_mask` | String[] | 需要隐藏的字段列表 |

## 访问控制行为

| 用户类型 | 可见角色 |
|----------|----------|
| **超级管理员** | 所有角色，包括隐藏角色 |
| **普通用户** | 仅非隐藏角色 |
| **未认证用户** | 返回 403 Forbidden |

## 常见集群权限

| 权限 | 描述 |
|------|------|
| `"*"` | 所有权限 |
| `"cluster:monitor*"` | 所有集群监控权限 |
| `"cluster:monitor/health"` | 监控集群健康状态 |
| `"cluster:monitor/nodes/info"` | 获取节点信息 |
| `"cluster:all"` | 所有集群权限 |

## 常见索引权限

| 权限 | 描述 |
|------|------|
| `"*"` 或 `"ALL"` | 所有索引权限 |
| `"READ_UT"` | 读取、查看和索引映射 |
| `"CRUD_UT"` | 创建、读取、更新、删除 |
| `"SECURITY_CRUD"` | 安全相关的 CRUD 操作 |
| `"indices:data/read/search"` | 搜索权限 |

## 注意事项

1. **需要认证**：该 API 需要通过证书进行身份验证
2. **隐藏角色**：只有超级管理员可以查看隐藏角色
3. **安全索引**：使用该 API 前必须初始化 `.security` 索引
4. **空结果**：如果安全配置未初始化，会返回 500 错误

## 相关操作

- **PUT /_security/role/{name}**：创建或更新角色
- **DELETE /_security/role/{name}**：删除角色
- **PATCH /_security/role/{name}**：部分更新角色
- **GET /_security/user**：查询用户信息

## 实现细节

- **处理器**：`RolesApiAction.java`
- **继承**：继承自 `PatchableResourceApiAction` 和 `AbstractApiAction`
- **实际处理**：在 `AbstractApiAction.handleGet` 方法中（第 237-266 行）
- **配置加载**：从安全索引加载角色配置
- **过滤逻辑**：为非超级管理员用户过滤隐藏角色