--- title: "管理索引模板" date: 2026-01-06 lastmod: 2026-01-06 description: "创建、获取、删除可组合索引模板" tags: ["索引模板", "索引管理", "配置管理"] summary: "创建、获取、删除可组合索引模板（Composable Index Templates）。 API # PUT /_index_template/{name} POST /_index_template/{name} GET /_index_template GET /_index_template/{name} DELETE /_index_template/{name} API 的作用 # 索引模板允许您定义在创建新索引时自动应用的设置、映射和别名。 可组合索引模板 # 可组合索引模板是 Easysearch 推荐的模板管理方式，具有以下特点： 模块化：由组件模板（component templates）组成 可组合：多个模板可以组合在一起 优先级：通过 priority 控制模板应用顺序 版本控制：支持版本号管理 API 的参数 # 创建/更新索引模板 # 路由参数 # 参数 类型 是否必填 描述 {name} 字符串 必需 索引模板名称 Query String 参数 # 参数 类型 是否必填 默认值 描述 cause 字符串 否 api 创建/更新索引模板的原因 create 布尔值 否 false 是否只创建新模板，不允许更新已存在的模板 master_timeout 时间值 否 30s 连接到主节点的超时时间 请求体参数 # 参数 类型 是否必填 描述 index_patterns 数组 必需 匹配的索引模式列表，如 ["logs-*", "metrics-*"] priority 整数 否 模板优先级，数值越大优先级越高 template 对象 是 模板配置，包含 settings、mappings、aliases version 整数 否 模板版本号 _meta 对象 否 模板元数据 获取索引模板 # 路由参数 # 参数 类型 是否必填 描述 {name} 字符串 否 索引模板名称，支持逗号分隔的多个名称。不指定则获取所有模板 Query String 参数 # 参数 类型 是否必填 默认值 描述 flat_settings 布尔值 否 false 是否以扁平格式返回设置 local 布尔值 否 false 是否只从本地节点获取信息 master_timeout 时间值 否 30s 连接到主节点的超时时间 删除索引模板 # 路由参数 # 参数 类型 是否必填 描述 {name} 字符串 必需 要删除的索引模板名称 Query String 参数 # 参数 类型 是否必填 默认值 描述 master_timeout 时间值 否 30s 连接到主节点的超时时间 timeout 时间值 否 默认超时 操作超时时间 示例 # 创建索引模板 # PUT /_index_template/logs_template { "index_patterns": ["logs-*"], "priority": 100, "template": { "settings": { "number_of_shards": 3, "number_of_replicas": 1 }, "mappings": { "properties": { "@timestamp": { "type": "date" }, "message": { "type": "text" }, "level": { "type": "keyword" } } }, "aliases": { "logs_current": {} } } } 响应示例：" --- 创建、获取、删除可组合索引模板（Composable Index Templates）。 ## API ``` PUT /_index_template/{name} POST /_index_template/{name} GET /_index_template GET /_index_template/{name} DELETE /_index_template/{name} ``` ## API 的作用 索引模板允许您定义在创建新索引时自动应用的设置、映射和别名。 ### 可组合索引模板 可组合索引模板是 Easysearch 推荐的模板管理方式，具有以下特点： - **模块化**：由组件模板（component templates）组成 - **可组合**：多个模板可以组合在一起 - **优先级**：通过 priority 控制模板应用顺序 - **版本控制**：支持版本号管理 ## API 的参数 ### 创建/更新索引模板 #### 路由参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `{name}` | 字符串 | 必需 | 索引模板名称 | #### Query String 参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `cause` | 字符串 | 否 | api | 创建/更新索引模板的原因 | | `create` | 布尔值 | 否 | false | 是否只创建新模板，不允许更新已存在的模板 | | `master_timeout` | 时间值 | 否 | 30s | 连接到主节点的超时时间 | #### 请求体参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `index_patterns` | 数组 | 必需 | 匹配的索引模式列表，如 `["logs-*", "metrics-*"]` | | `priority` | 整数 | 否 | 模板优先级，数值越大优先级越高 | | `template` | 对象 | 是 | 模板配置，包含 settings、mappings、aliases | | `version` | 整数 | 否 | 模板版本号 | | `_meta` | 对象 | 否 | 模板元数据 | ### 获取索引模板 #### 路由参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `{name}` | 字符串 | 否 | 索引模板名称，支持逗号分隔的多个名称。不指定则获取所有模板 | #### Query String 参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `flat_settings` | 布尔值 | 否 | false | 是否以扁平格式返回设置 | | `local` | 布尔值 | 否 | false | 是否只从本地节点获取信息 | | `master_timeout` | 时间值 | 否 | 30s | 连接到主节点的超时时间 | ### 删除索引模板 #### 路由参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `{name}` | 字符串 | 必需 | 要删除的索引模板名称 | #### Query String 参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `master_timeout` | 时间值 | 否 | 30s | 连接到主节点的超时时间 | | `timeout` | 时间值 | 否 | 默认超时 | 操作超时时间 | ## 示例 ### 创建索引模板 ```bash PUT /_index_template/logs_template { "index_patterns": ["logs-*"], "priority": 100, "template": { "settings": { "number_of_shards": 3, "number_of_replicas": 1 }, "mappings": { "properties": { "@timestamp": { "type": "date" }, "message": { "type": "text" }, "level": { "type": "keyword" } } }, "aliases": { "logs_current": {} } } } ``` **响应示例：** ```json { "acknowledged": true } ``` ### 只创建不更新 ```bash PUT /_index_template/logs_template?create=true { "index_patterns": ["logs-*"], "template": { ... } } ``` ### 获取所有模板 ```bash GET /_index_template ``` ### 获取特定模板 ```bash GET /_index_template/logs_template ``` ### 获取多个模板 ```bash GET /_index_template/logs_template,metrics_template ``` ### 以扁平格式获取 ```bash GET /_index_template/logs_template?flat_settings=true ``` ### 删除模板 ```bash DELETE /_index_template/logs_template ``` **响应示例：** ```json { "acknowledged": true } ``` ### 使用组件模板 ```bash # 先创建组件模板 PUT /_component_template/logs_settings { "template": { "settings": { "number_of_shards": 3, "number_of_replicas": 1 } } } # 在索引模板中引用组件模板 PUT /_index_template/logs_template { "index_patterns": ["logs-*"], "priority": 100, "composed_of": ["logs_settings"], "template": { "mappings": { "properties": { "@timestamp": { "type": "date" } } } } } ``` ### 设置优先级 ```bash PUT /_index_template/default_logs { "index_patterns": ["logs-*"], "priority": 50, "template": { "settings": { "number_of_replicas": 0 } } } PUT /_index_template/production_logs { "index_patterns": ["logs-prod-*"], "priority": 100, "template": { "settings": { "number_of_replicas": 2 } } } ``` ### 添加版本和元数据 ```bash PUT /_index_template/logs_template { "index_patterns": ["logs-*"], "version": 1, "_meta": { "description": "Logs index template", "owner": "data-team" }, "template": { ... } } ``` ## 模板优先级 当多个模板匹配同一个索引时： 1. 按 `priority` 降序应用 2. 相同优先级时按名称字典序 3. 后应用的模板设置会覆盖先应用的 | 优先级 | 应用顺序 | |--------|----------| | 高值 | 优先应用 | | 相同 | 按名称排序 | ## 索引模式 支持通配符模式： | 模式 | 匹配示例 | |------|----------| | `logs-*` | logs-2024, logs-app | | `*_prod` | app_prod, db_prod | | `test-*` | test-1, test-data | ## 错误处理 ### 模板已存在（create=true） ```json { "error": { "type": "resource_already_exists_exception", "reason": "index_template [logs_template] already exists" } } ``` ### 模板不存在 ```json { "error": { "type": "index_template_missing_exception", "reason": "index_template [logs_template] missing" } } ``` ## 使用场景 ### 场景 1：时间序列索引 ```bash PUT /_index_template/metrics_template { "index_patterns": ["metrics-*"], "priority": 100, "template": { "settings": { "number_of_shards": 3, "number_of_replicas": 1, "refresh_interval": "30s" } } } ``` ### 场景 2：环境特定配置 ```bash # 开发环境 PUT /_index_template/dev_logs { "index_patterns": ["logs-dev-*"], "priority": 100, "template": { "settings": { "number_of_replicas": 0 } } } # 生产环境 PUT /_index_template/prod_logs { "index_patterns": ["logs-prod-*"], "priority": 200, "template": { "settings": { "number_of_replicas": 2 } } } ``` ## 注意事项 1. **全局模板限制**：全局模板（使用 `*` 模式）不能设置 `index.hidden` 2. **不可变设置**：某些设置（如 `number_of_shards`）在索引创建后不能修改 3. **模板验证**：模板定义会进行严格验证 4. **向后兼容**：保留对旧版模板（`/_template`）的支持 5. **优先级管理**：合理设置优先级避免意外覆盖