---
title: "导入规则库（自动ID追加）"
date: 2026-02-16
lastmod: 2026-02-16
description: "自动生成ID并导入规则库（追加模式）"
tags: ["规则库", "导入", "追加"]
summary: "自动生成规则库 ID 并导入规则，使用追加模式。如果同 ID 的规则库已存在，将追加规则；否则创建新规则库。
API 格式 #  PUT /_match_rules/_import API 作用 #  该 API 用于自动生成规则库 ID 并导入规则：
 自动生成 ID：系统自动生成格式为 repo_<timestamp> 的规则库 ID 追加模式：如果规则库已存在，追加新规则；否则创建新规则库 支持批量导入多条规则 自动管理规则库版本号  API 参数 #  请求体参数 #     参数 类型 是否必填 默认值 描述     name String 是 - 规则库名称   description String 否 "" 规则库描述   tags String[] 否 [] 用于分类的标签数组   rules Array 是 - 规则对象数组（至少包含一条规则）    rules 数组元素结构 #     字段 类型 是否必填 描述     expression String 是 规则表达式（匹配条件）   description String 是 规则描述（匹配时作为标签使用）    请求示例 #  导入规则（自动生成 ID） #  PUT /_match_rules/_import { "name": "安全规则库", "description": "用于安全事件分类的规则库", "tags": ["security", "content-filter"], "rules": [ { "expression": "枪 or 手枪 or 步步枪", "description": "涉枪武器关键词" }, { "expression": "AK47 or AK-47 or M16", "description": "枪支型号" } ] } 向已存在规则库追加规则 #  PUT /_match_rules/_import { "name": "安全规则库", "rules": [ { "expression": "刀 or 匕首 or 三棱刮刀", "description": "管制刀具关键词" } ] } 响应示例 #  创建新规则库成功 #  { "success": true, "message": "Successfully imported 2 rules to repo_id 'repo_1704123456789' (version: 1)", "repo_id": "repo_1704123456789", "version": "1", "rule_count": 2 } 追加到现有规则库成功 #  { "success": true, "message": "Successfully imported 1 rules to repo_id 'repo_1704123456789' (version: 2)", "repo_id": "repo_1704123456789", "version": "2", "rule_count": 3 } 错误响应 #  { "success": false, "message": "Rules array cannot be empty" } 响应字段说明 #     字段 类型 描述     success Boolean 操作是否成功   message String 详细结果消息   repo_id String 自动生成的规则库 ID（格式：repo_<timestamp>）   version String 规则库版本号   rule_count Integer 规则库中的规则总数    ID 生成规则 #  规则库 ID 按以下格式自动生成："
---


自动生成规则库 ID 并导入规则，使用追加模式。如果同 ID 的规则库已存在，将追加规则；否则创建新规则库。

## API 格式

```
PUT /_match_rules/_import
```

## API 作用

该 API 用于自动生成规则库 ID 并导入规则：
- **自动生成 ID**：系统自动生成格式为 `repo_<timestamp>` 的规则库 ID
- **追加模式**：如果规则库已存在，追加新规则；否则创建新规则库
- 支持批量导入多条规则
- 自动管理规则库版本号

## API 参数

### 请求体参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `name` | String | **是** | - | 规则库名称 |
| `description` | String | 否 | `""` | 规则库描述 |
| `tags` | String[] | 否 | `[]` | 用于分类的标签数组 |
| `rules` | Array | **是** | - | 规则对象数组（至少包含一条规则） |

### rules 数组元素结构

| 字段 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `expression` | String | **是** | 规则表达式（匹配条件） |
| `description` | String | **是** | 规则描述（匹配时作为标签使用） |

## 请求示例

### 导入规则（自动生成 ID）

```json
PUT /_match_rules/_import
{
  "name": "安全规则库",
  "description": "用于安全事件分类的规则库",
  "tags": ["security", "content-filter"],
  "rules": [
    {
      "expression": "枪 or 手枪 or 步步枪",
      "description": "涉枪武器关键词"
    },
    {
      "expression": "AK47 or AK-47 or M16",
      "description": "枪支型号"
    }
  ]
}
```

### 向已存在规则库追加规则

```json
PUT /_match_rules/_import
{
  "name": "安全规则库",
  "rules": [
    {
      "expression": "刀 or 匕首 or 三棱刮刀",
      "description": "管制刀具关键词"
    }
  ]
}
```

## 响应示例

### 创建新规则库成功

```json
{
  "success": true,
  "message": "Successfully imported 2 rules to repo_id 'repo_1704123456789' (version: 1)",
  "repo_id": "repo_1704123456789",
  "version": "1",
  "rule_count": 2
}
```

### 追加到现有规则库成功

```json
{
  "success": true,
  "message": "Successfully imported 1 rules to repo_id 'repo_1704123456789' (version: 2)",
  "repo_id": "repo_1704123456789",
  "version": "2",
  "rule_count": 3
}
```

### 错误响应

```json
{
  "success": false,
  "message": "Rules array cannot be empty"
}
```

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `success` | Boolean | 操作是否成功 |
| `message` | String | 详细结果消息 |
| `repo_id` | String | 自动生成的规则库 ID（格式：`repo_<timestamp>`） |
| `version` | String | 规则库版本号 |
| `rule_count` | Integer | 规则库中的规则总数 |

## ID 生成规则

规则库 ID 按以下格式自动生成：
```
repo_<timestamp>
```

其中 `<timestamp>` 是当前时间的毫秒级时间戳（`System.currentTimeMillis()`）。

## 内部处理逻辑

1. **ID 生成**
   - 使用当前时间戳生成唯一的规则库 ID
   - 格式：`repo_<timestamp>`

2. **检查文档是否存在**
   - 如果存在：读取现有规则和元数据，追加新规则
   - 如果不存在：创建新文档

3. **追加规则**
   - 将新规则追加到现有规则后（或创建新规则）
   - 自动重新计算所有规则的偏移量

4. **元数据处理**
   - 保留原有的 `name`、`description`、`tags`
   - 除非请求中提供了新值

## POST 与 PUT 的区别

| 方法 | ID 处理 | 行为 |
|------|---------|------|
| **POST** | 自动生成 ID | 覆盖模式：替换现有规则 |
| **PUT** | 自动生成 ID | 追加模式：添加新规则 |

## 使用场景

1. **快速创建**：无需指定 ID，快速创建规则库
2. **批量导入**：一次性导入多条规则
3. **测试环境**：在测试时快速创建临时规则库
4. **自动化脚本**：脚本中无需管理 ID 冲突

## 注意事项

1. **ID 不可预测**：由于 ID 基于时间戳生成，无法提前预测
2. **时间戳冲突**：极短时间内多次调用可能生成相同 ID（后一次会追加到前一次）
3. **版本管理**：每次操作都会递增版本号
4. **元数据保留**：追加时保留原有元数据，除非明确提供新值
5. **编译状态**：导入后规则库状态为 `pending`，需要编译后才能使用

## 与其他 API 的配合

- 如果需要指定规则库 ID，请使用 `PUT /_match_rules/{repo_id}/_import`
- 如果需要覆盖模式，请使用 `POST /_match_rules/_import`
- 导入后可使用 `GET .match_rules/_doc/{repo_id}` 查看规则库详情