--- title: "管理传统索引模板" date: 2026-01-07 lastmod: 2026-01-07 description: "创建、获取、删除传统索引模板（Legacy Index Templates）" tags: ["索引模板", "模板管理", "配置管理"] summary: "创建、获取、删除传统索引模板（Legacy Index Templates）。 API # POST /_template/{name} PUT /_template/{name} GET /_template GET /_template/{name} DELETE /_template/{name} API 的作用 # 传统索引模板允许您定义在创建新索引时自动应用的设置、映射和别名。 注意：传统模板（/_template）是旧版本 API。推荐使用可组合索引模板（/_index_template）和组件模板（/_component_template）。 传统模板 vs 可组合模板 # 特性 传统模板 可组合模板 API 路径 /_template /_index_template 模块化 否 是，可使用组件模板 优先级 order priority 组合性 不支持 支持多个模板组合 推荐度 已弃用 推荐 API 的参数 # 创建/更新传统模板 # 路由参数 # 参数 类型 是否必填 描述 {name} 字符串 必需 模板名称 Query String 参数 # 参数 类型 是否必填 默认值 描述 cause 字符串 否 "" 创建模板的原因 create 布尔值 否 false 是否只创建新模板（不允许覆盖） include_type_name 布尔值 否 false 是否在请求体中包含类型名称（已弃用） master_timeout 时间值 否 30s 连接到主节点的超时时间 order 整数 否 0 模板的优先级顺序 请求体参数 # 参数 类型 是否必填 描述 index_patterns 数组 必需 索引模式列表（如 ["logs-*", "metrics-*"]） order 整数 否 模板优先级，数值越小优先级越高 version 整数 否 模板版本号 settings 对象 否 索引设置配置 mappings 对象 否 字段映射定义 aliases 对象 否 索引别名配置 获取传统模板 # 路由参数 # 参数 类型 是否必填 描述 {name} 字符串 否 模板名称，支持逗号分隔的多个名称。不指定则获取所有模板 Query String 参数 # 参数 类型 是否必填 默认值 描述 flat_settings 布尔值 否 false 是否以扁平格式返回设置 include_type_name 布尔值 否 false 是否在响应中包含类型名称（已弃用） local 布尔值 否 false 是否只从本地节点获取信息 master_timeout 时间值 否 30s 连接到主节点的超时时间 删除传统模板 # 路由参数 # 参数 类型 是否必填 描述 {name} 字符串 必需 要删除的模板名称 Query String 参数 # 参数 类型 是否必填 默认值 描述 master_timeout 时间值 否 30s 连接到主节点的超时时间 timeout 时间值 否 默认超时 操作超时时间 示例 # 创建传统模板 # PUT /_template/logs_template { "index_patterns": ["logs-*"], "order": 1, "settings": { "number_of_shards": 3, "number_of_replicas": 1 }, "mappings": { "properties": { "@timestamp": { "type": "date" }, "message": { "type": "text" }, "level": { "type": "keyword" } } }, "aliases": { "logs_all": {} } } 响应示例：" --- 创建、获取、删除传统索引模板（Legacy Index Templates）。 ## API ``` POST /_template/{name} PUT /_template/{name} GET /_template GET /_template/{name} DELETE /_template/{name} ``` ## API 的作用 传统索引模板允许您定义在创建新索引时自动应用的设置、映射和别名。 > **注意**：传统模板（`/_template`）是旧版本 API。推荐使用可组合索引模板（`/_index_template`）和组件模板（`/_component_template`）。 ### 传统模板 vs 可组合模板 | 特性 | 传统模板 | 可组合模板 | |------|----------|------------| | API 路径 | `/_template` | `/_index_template` | | 模块化 | 否 | 是，可使用组件模板 | | 优先级 | order | priority | | 组合性 | 不支持 | 支持多个模板组合 | | 推荐度 | 已弃用 | 推荐 | ## API 的参数 ### 创建/更新传统模板 #### 路由参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `{name}` | 字符串 | 必需 | 模板名称 | #### Query String 参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `cause` | 字符串 | 否 | "" | 创建模板的原因 | | `create` | 布尔值 | 否 | false | 是否只创建新模板（不允许覆盖） | | `include_type_name` | 布尔值 | 否 | false | 是否在请求体中包含类型名称（已弃用） | | `master_timeout` | 时间值 | 否 | 30s | 连接到主节点的超时时间 | | `order` | 整数 | 否 | 0 | 模板的优先级顺序 | #### 请求体参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `index_patterns` | 数组 | 必需 | 索引模式列表（如 `["logs-*", "metrics-*"]`） | | `order` | 整数 | 否 | 模板优先级，数值越小优先级越高 | | `version` | 整数 | 否 | 模板版本号 | | `settings` | 对象 | 否 | 索引设置配置 | | `mappings` | 对象 | 否 | 字段映射定义 | | `aliases` | 对象 | 否 | 索引别名配置 | ### 获取传统模板 #### 路由参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `{name}` | 字符串 | 否 | 模板名称，支持逗号分隔的多个名称。不指定则获取所有模板 | #### Query String 参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `flat_settings` | 布尔值 | 否 | false | 是否以扁平格式返回设置 | | `include_type_name` | 布尔值 | 否 | false | 是否在响应中包含类型名称（已弃用） | | `local` | 布尔值 | 否 | false | 是否只从本地节点获取信息 | | `master_timeout` | 时间值 | 否 | 30s | 连接到主节点的超时时间 | ### 删除传统模板 #### 路由参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `{name}` | 字符串 | 必需 | 要删除的模板名称 | #### Query String 参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `master_timeout` | 时间值 | 否 | 30s | 连接到主节点的超时时间 | | `timeout` | 时间值 | 否 | 默认超时 | 操作超时时间 | ## 示例 ### 创建传统模板 ```bash PUT /_template/logs_template { "index_patterns": ["logs-*"], "order": 1, "settings": { "number_of_shards": 3, "number_of_replicas": 1 }, "mappings": { "properties": { "@timestamp": { "type": "date" }, "message": { "type": "text" }, "level": { "type": "keyword" } } }, "aliases": { "logs_all": {} } } ``` **响应示例：** ```json { "acknowledged": true } ``` ### 只创建不更新 ```bash PUT /_template/logs_template?create=true { "index_patterns": ["logs-*"], "settings": { ... } } ``` ### 设置优先级（order） ```bash PUT /_template/default_template { "index_patterns": ["*"], "order": 0, "settings": { "number_of_replicas": 0 } } PUT /_template/prod_template { "index_patterns": ["prod-*"], "order": 10, "settings": { "number_of_replicas": 2 } } ``` ### 获取所有模板 ```bash GET /_template ``` **响应示例：** ```json { "logs_template": { "index_patterns": ["logs-*"], "order": 1, "settings": { ... }, "mappings": { ... }, "aliases": { ... } } } ``` ### 获取特定模板 ```bash GET /_template/logs_template ``` ### 获取多个模板 ```bash GET /_template/logs_template,metrics_template ``` ### 以扁平格式获取 ```bash GET /_template/logs_template?flat_settings=true ``` ### 删除模板 ```bash DELETE /_template/logs_template ``` **响应示例：** ```json { "acknowledged": true } ``` ### 使用 template 参数（向后兼容） ```bash PUT /_template/old_template { "template": "logs-*", "settings": { ... } } ``` > **注意**：`template` 参数已被 `index_patterns` 替代。 ## 模板优先级（order） 当多个模板匹配同一个索引时： 1. 按 `order` 值升序应用（数值越小优先级越高） 2. 相同 order 时按模板名称字典序 3. 后应用的模板设置会覆盖先应用的 | order 值 | 应用顺序 | |----------|----------| | 0 | 最后应用 | | 10 | 优先应用 | | 100 | 最先应用 | ## 迁移到可组合模板 传统模板可以迁移到可组合模板： ```bash # 传统模板 PUT /_template/logs { "index_patterns": ["logs-*"], "settings": { ... }, "mappings": { ... } } # 等效的可组合模板 # 1. 创建组件模板 PUT /_component_template/logs_settings { "template": { "settings": { ... } } } # 2. 创建索引模板 PUT /_index_template/logs { "index_patterns": ["logs-*"], "priority": 100, "template": { "mappings": { ... } } } ``` ## 使用场景 ### 场景 1：时间序列索引 ```bash PUT /_template/daily_logs { "index_patterns": ["logs-[YYYY.MM.DD]"], "settings": { "number_of_shards": 3, "number_of_replicas": 1, "index.format": "yyyy.MM.dd" } } ``` ### 场景 2：环境分离 ```bash # 开发环境 PUT /_template/dev_logs { "index_patterns": ["logs-dev-*"], "order": 5, "settings": { "number_of_replicas": 0 } } # 生产环境 PUT /_template/prod_logs { "index_patterns": ["logs-prod-*"], "order": 10, "settings": { "number_of_replicas": 2 } } ``` ## 注意事项 1. **已弃用**：传统模板 API 已被标记为弃用，推荐使用可组合模板 2. **不可组合**：不能像组件模板那样组合使用 3. **版本控制**：版本控制不如可组合模板灵活 4. **全局限制**：全局模板（`*` 模式）不能设置某些隐藏设置 5. **迁移建议**：新项目推荐使用可组合模板和组件模板