---
title: "导入规则库（指定ID覆盖）"
date: 2026-02-06
lastmod: 2026-02-06
description: "导入规则库到指定的规则仓库（覆盖模式）"
tags: ["规则库", "导入", "覆盖"]
summary: "将规则导入到指定的规则库中，使用覆盖模式。如果规则库已存在，将完全替换原有规则。
API 格式 #  POST /_match_rules/{repo_id}/_import API 作用 #  该 API 用于将规则导入到指定的规则库（规则仓库）中：
 覆盖模式：完全替换规则库中的现有规则 如果规则库不存在，则创建新的规则库 支持批量导入多条规则 自动管理规则库版本号  API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {repo_id} String 是 - 规则库的唯一标识符    请求体参数 #     参数 类型 是否必填 默认值 描述     name String 是 - 规则库名称   description String 否 "" 规则库描述   tags String[] 否 [] 用于分类的标签数组   rules Array 是 - 规则对象数组（至少包含一条规则）    rules 数组元素结构 #     字段 类型 是否必填 描述     expression String 是 规则表达式（匹配条件）   description String 是 规则描述（匹配时作为标签使用）    请求示例 #  导入规则到指定规则库 #  POST /_match_rules/security_rules/_import { "name": "安全规则库", "description": "用于安全事件分类的规则库", "tags": ["security", "content-filter"], "rules": [ { "expression": "枪 or 手枪 or 步步枪", "description": "涉枪武器关键词" }, { "expression": "AK47 or AK-47 or M16 or M4A1", "description": "枪支型号" }, { "expression": "爆炸物 or 炸弹 or 雷管", "description": "爆炸物品关键词" } ] } 覆盖已存在的规则库 #  POST /_match_rules/security_rules/_import { "name": "安全规则库", "description": "更新后的安全规则库", "tags": ["security", "weapon"], "rules": [ { "expression": "刀 or 匕首 or 三棱刮刀", "description": "管制刀具关键词" } ] } 响应示例 #  成功响应 #  { "success": true, "message": "Successfully imported 3 rules to repo_id 'security_rules' (version: 2)", "repo_id": "security_rules", "version": "2", "rule_count": 3 } 错误响应 #  { "success": false, "message": "Rules array cannot be empty" } 响应字段说明 #     字段 类型 描述     success Boolean 操作是否成功   message String 详细结果消息   repo_id String 规则库 ID   version String 规则库版本号（每次导入递增）   rule_count Integer 导入的规则数量    内部存储格式 #  规则在内部以以下格式存储："
---


将规则导入到指定的规则库中，使用覆盖模式。如果规则库已存在，将完全替换原有规则。

## API 格式

```
POST /_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
POST /_match_rules/security_rules/_import
{
  "name": "安全规则库",
  "description": "用于安全事件分类的规则库",
  "tags": ["security", "content-filter"],
  "rules": [
    {
      "expression": "枪 or 手枪 or 步步枪",
      "description": "涉枪武器关键词"
    },
    {
      "expression": "AK47 or AK-47 or M16 or M4A1",
      "description": "枪支型号"
    },
    {
      "expression": "爆炸物 or 炸弹 or 雷管",
      "description": "爆炸物品关键词"
    }
  ]
}
```

### 覆盖已存在的规则库

```json
POST /_match_rules/security_rules/_import
{
  "name": "安全规则库",
  "description": "更新后的安全规则库",
  "tags": ["security", "weapon"],
  "rules": [
    {
      "expression": "刀 or 匕首 or 三棱刮刀",
      "description": "管制刀具关键词"
    }
  ]
}
```

## 响应示例

### 成功响应

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

### 错误响应

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

## 响应字段说明

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

## 内部存储格式

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

- 每条规则一行
- `\t` 分隔表达式和描述
- `#<offset>#` 表示规则编号

## POST 与 PUT 的区别

| 方法 | 行为 |
|------|------|
| **POST** | 覆盖模式：完全替换现有规则 |
| **PUT** | 追加模式：在现有规则后添加新规则 |

## 文档元数据字段

导入后，文档会包含以下额外字段：

| 字段 | 类型 | 描述 |
|------|------|------|
| `version` | String | 版本号（每次导入递增） |
| `created` | Date | 创建时间戳 |
| `updated` | Date | 最后更新时间戳 |
| `status` | String | 编译状态（初始为 `pending`） |
| `compiled_at` | Date/null | 编译完成时间 |
| `total_rules` | Integer/null | 规则总数（编译后设置） |
| `compiled_nodes` | String[] | 已编译的节点列表 |
| `error_message` | String/null | 编译失败时的错误信息 |

## 使用场景

1. **初始化规则库**：首次创建并导入规则
2. **完全更新规则库**：替换规则库中的所有规则
3. **版本管理**：每次覆盖会递增版本号，便于追踪变更

## 注意事项

1. **数据丢失**：使用 POST 方法会完全替换现有规则，请谨慎操作
2. **规则验证**：每条规则必须包含 `expression` 和 `description` 字段
3. **版本递增**：每次导入都会递增版本号
4. **编译状态**：导入后规则库状态为 `pending`，需要编译后才能使用