---
title: "导入规则库（指定ID追加）"
date: 2026-01-02
lastmod: 2026-01-02
description: "向指定规则库追加规则"
tags: ["规则库", "导入", "追加"]
summary: "向指定的规则库中追加新规则，保留原有规则。
API 格式 #  PUT /_match_rules/{repo_id}/_import API 作用 #  该 API 用于向指定的规则库追加新规则：
 追加模式：在现有规则后添加新规则 如果规则库不存在，则创建新的规则库 支持批量导入多条规则 自动重新计算规则偏移量 保留现有元数据（名称、描述、标签）  API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {repo_id} String 是 - 规则库的唯一标识符    请求体参数 #     参数 类型 是否必填 默认值 描述     name String 否 保留原值 规则库名称   description String 否 保留原值 规则库描述   tags String[] 否 保留原值 用于分类的标签数组   rules Array 是 - 规则对象数组（至少包含一条规则）    rules 数组元素结构 #     字段 类型 是否必填 描述     expression String 是 规则表达式（匹配条件）   description String 是 规则描述（匹配时作为标签使用）    请求示例 #  向现有规则库追加规则 #  PUT /_match_rules/security_rules/_import { "rules": [ { "expression": "刀 or 匕首 or 三棱刮刀", "description": "管制刀具关键词" }, { "expression": "匕首 or 弹簧刀", "description": "其他危险刀具" } ] } 追加规则并更新元数据 #  PUT /_match_rules/security_rules/_import { "name": "安全规则库（扩展版）", "description": "包含更多安全规则的规则库", "tags": ["security", "weapon", "expanded"], "rules": [ { "expression": "毒性化学品 or 氰化物", "description": "危险化学品关键词" } ] } 响应示例 #  成功响应 #  { "success": true, "message": "Successfully imported 2 rules to repo_id 'security_rules' (version: 3)", "repo_id": "security_rules", "version": "3", "rule_count": 5 } 错误响应 #  { "success": false, "message": "Rules array cannot be empty" } 响应字段说明 #     字段 类型 描述     success Boolean 操作是否成功   message String 详细结果消息   repo_id String 规则库 ID   version String 规则库版本号（每次导入递增）   rule_count Integer 规则库中的规则总数（包含追加前的规则）    内部处理逻辑 #    检查文档是否存在"
---


向指定的规则库中追加新规则，保留原有规则。

## API 格式

```
PUT /_match_rules/{repo_id}/_import
```

## API 作用

该 API 用于向指定的规则库追加新规则：
- **追加模式**：在现有规则后添加新规则
- 如果规则库不存在，则创建新的规则库
- 支持批量导入多条规则
- 自动重新计算规则偏移量
- 保留现有元数据（名称、描述、标签）

## API 参数

### 路径参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `{repo_id}` | String | **是** | - | 规则库的唯一标识符 |

### 请求体参数

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

### rules 数组元素结构

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

## 请求示例

### 向现有规则库追加规则

```json
PUT /_match_rules/security_rules/_import
{
  "rules": [
    {
      "expression": "刀 or 匕首 or 三棱刮刀",
      "description": "管制刀具关键词"
    },
    {
      "expression": "匕首 or 弹簧刀",
      "description": "其他危险刀具"
    }
  ]
}
```

### 追加规则并更新元数据

```json
PUT /_match_rules/security_rules/_import
{
  "name": "安全规则库（扩展版）",
  "description": "包含更多安全规则的规则库",
  "tags": ["security", "weapon", "expanded"],
  "rules": [
    {
      "expression": "毒性化学品 or 氰化物",
      "description": "危险化学品关键词"
    }
  ]
}
```

## 响应示例

### 成功响应

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

### 错误响应

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

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `success` | Boolean | 操作是否成功 |
| `message` | String | 详细结果消息 |
| `repo_id` | String | 规则库 ID |
| `version` | String | 规则库版本号（每次导入递增） |
| `rule_count` | Integer | 规则库中的规则总数（包含追加前的规则） |

## 内部处理逻辑

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

2. **追加规则**
   - 将新规则追加到现有规则后
   - 自动重新计算所有规则的偏移量（offset）
   - 偏移量从 0 开始连续编号

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

4. **版本管理**
   - 版本号递增
   - 更新 `updated` 时间戳
   - 保留 `created` 时间戳

## 内部存储格式

规则在内部以以下格式存储：
```
expression1\t#0#description1
expression2\t#1#description2
expression3\t#2#description3
```

- 每条规则一行
- `\t` 分隔表达式和描述
- `#<offset>#` 表示规则编号（追加后会重新计算）

## POST 与 PUT 的区别

| 方法 | 行为 | 适用场景 |
|------|------|----------|
| **POST** | 覆盖模式：完全替换现有规则 | 完全更新规则库 |
| **PUT** | 追加模式：在现有规则后添加新规则 | 增量添加规则 |

## 使用场景

1. **增量更新**：向现有规则库添加新规则
2. **扩展规则集**：不丢失原有规则的情况下扩展规则库
3. **协作更新**：不同团队可以追加各自领域的规则
4. **版本迭代**：保留历史规则的同时添加新规则

## 注意事项

1. **规则去重**：API 不会自动去重，追加重复规则可能导致冗余匹配
2. **偏移量重算**：追加后所有规则的偏移量会重新计算
3. **元数据保留**：未提供的元数据字段会保留原有值
4. **版本递增**：每次追加都会递增版本号
5. **编译状态**：追加后规则库状态会变为 `pending`，需要重新编译