---
title: "创建API密钥"
date: 2026-03-08
lastmod: 2026-03-08
description: "创建新的API密钥"
tags: ["安全", "API密钥", "认证"]
summary: "注意：POST /_security/api_key API 在当前版本的 Easysearch 中尚未实现服务器端。
API 说明 #  POST /_security/api_key 端点在当前 Easysearch 版本中未实现服务器端 REST 处理器。
虽然客户端库中存在相关的数据结构类（如 CreateApiKeyResponse.java），但服务器端缺少相应的 REST 处理器来处理 API 密钥的创建请求。
预期 API 格式 #  POST /_security/api_key 预期参数 #  请求体参数 #     参数 类型 是否必填 默认值 描述     name String 是 - API 密钥的名称   expiration String 否 - 过期时间（如 1d、7d、30d）   role_descriptors Object 否 - 角色权限描述    预期请求示例 #  创建基本 API 密钥 #  POST /_security/api_key { "name": "my-api-key" } 创建有过期时间的 API 密钥 #  POST /_security/api_key { "name": "temp-api-key", "expiration": "7d" } 创建带权限的 API 密钥 #  POST /_security/api_key { "name": "limited-api-key", "expiration": "30d", "role_descriptors": { "my_role": { "cluster": ["cluster:monitor/health"], "indices": [ { "names": ["logs-*"], "privileges": ["read"] } ] } } } 预期响应格式 #  根据客户端类 CreateApiKeyResponse 的定义："
---


**注意**：POST /_security/api_key API 在当前版本的 Easysearch 中**尚未实现**服务器端。

## API 说明

`POST /_security/api_key` 端点在当前 Easysearch 版本中未实现服务器端 REST 处理器。

虽然客户端库中存在相关的数据结构类（如 `CreateApiKeyResponse.java`），但服务器端缺少相应的 REST 处理器来处理 API 密钥的创建请求。

## 预期 API 格式

```
POST /_security/api_key
```

## 预期参数

### 请求体参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `name` | String | **是** | - | API 密钥的名称 |
| `expiration` | String | 否 | - | 过期时间（如 `1d`、`7d`、`30d`） |
| `role_descriptors` | Object | 否 | - | 角色权限描述 |

## 预期请求示例

### 创建基本 API 密钥

```json
POST /_security/api_key
{
  "name": "my-api-key"
}
```

### 创建有过期时间的 API 密钥

```json
POST /_security/api_key
{
  "name": "temp-api-key",
  "expiration": "7d"
}
```

### 创建带权限的 API 密钥

```json
POST /_security/api_key
{
  "name": "limited-api-key",
  "expiration": "30d",
  "role_descriptors": {
    "my_role": {
      "cluster": ["cluster:monitor/health"],
      "indices": [
        {
          "names": ["logs-*"],
          "privileges": ["read"]
        }
      ]
    }
  }
}
```

## 预期响应格式

根据客户端类 `CreateApiKeyResponse` 的定义：

```json
{
  "id": "VuaCfGcBCdbkQm-e5aOx",
  "name": "my-api-key",
  "key": "VuaCfGcBCdbkQm-e5aOx_api_key_value_here",
  "expiration": 1638316800000
}
```

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `id` | String | API 密钥的唯一标识符 |
| `name` | String | API 密钥的名称 |
| `key` | String | 实际的 API 密钥令牌（**仅在创建时返回一次**） |
| `expiration` | Long/DateTime | API 密钥的过期时间（毫秒时间戳） |

## 使用 API 密钥

创建后，可以在 HTTP 请求头中使用 API 密钥：

```
Authorization: ApiKey VuaCfGcBCdbkQm-e5aOx_api_key_value_here
```

## 当前状态

在 Easysearch 当前版本中：
- **客户端支持**：存在完整的客户端类定义
- **服务器端实现**：未实现 REST 处理器
- **安全模块**：`SecurityRestApiActions.java` 中未包含 API 密钥处理器

## 相关文件

### 客户端类
- `client/rest-high-level/src/main/java/org/easysearch/client/security/CreateApiKeyResponse.java`
- `client/rest-high-level/src/main/java/org/easysearch/client/security/GetApiKeyResponse.java`
- `client/rest-high-level/src/main/java/org/easysearch/client/security/support/ApiKey.java`
- `client/rest-high-level/src/main/java/org/easysearch/client/security/ClearApiKeyCacheRequest.java`

### 服务器端（缺少实现）
- `modules/security/src/main/java/com/infinilabs/security/dlic/rest/api/SecurityRestApiActions.java`

## 实现建议

如需实现此功能，需要：
1. 创建新的 `ApiKeyAction` 类，继承 `AbstractApiAction`
2. 将其添加到 `SecurityRestApiActions.getHandler()` 方法
3. 实现 `handlePost` 方法处理 API 密钥创建
4. 定义适当的验证和响应处理
5. 实现密钥存储和管理机制

## 替代方案

目前可以使用以下替代方案进行认证：
- **基本认证**：使用用户名和密码
- **Bearer Token**：使用 JWT 令牌
- **SSL/TLS 证书**：基于证书的认证

## 注意事项

1. **未实现功能**：该 API 当前不可用
2. **密钥安全**：密钥仅在创建时返回一次，请妥善保存
3. **客户端准备**：客户端已准备好支持此功能
4. **过期管理**：建议设置合理的过期时间

## 参考文档

如需实现此功能，可以参考：
- Elasticsearch 的 API 密钥管理功能
- OpenSearch 的 API 密钥实现