« 创建或更新别名 API 创建或更新索引模板 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›索引 API

创建或更新组件模板 API

编辑

创建或更新组件模板 API

编辑

创建或更新组件模板。组件模板是用于构建索引模板的构建块，这些索引模板指定索引映射、设置和别名。

PUT _component_template/template_1
{
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "mappings": {
      "_source": {
        "enabled": false
      },
      "properties": {
        "host_name": {
          "type": "keyword"
        },
        "created_at": {
          "type": "date"
        }
      }
    }
  }
}

请求

编辑

PUT /_component_template/<组件模板>

先决条件

编辑
  • 如果启用了 Elasticsearch 安全功能，您必须具有 manage_index_templates 或 manage 集群权限才能使用此 API。

描述

编辑

索引模板可以由多个组件模板组成。要使用组件模板，请在索引模板的 composed_of 列表中指定它。组件模板仅作为匹配索引模板的一部分应用于新的数据流和索引。

直接在索引模板或创建索引请求中指定的设置和映射将覆盖组件模板中指定的任何设置或映射。

组件模板仅在索引创建期间使用。对于数据流，这包括数据流创建和流的后备索引的创建。对组件模板的更改不会影响现有索引，包括流的后备索引。

组件模板中的注释

编辑

您可以在组件模板中使用 C 风格的 /* */ 块注释。您可以在请求正文中的任何位置包含注释，但不能在开头的花括号之前。

路径参数

编辑
<组件模板>

(必需，字符串) 要创建的组件模板的名称。

Elasticsearch 包括以下内置组件模板

  • logs@mappings
  • logs@settings
  • metrics@mappings
  • metrics@settings
  • metrics@tsdb-settings
  • synthetics@mapping
  • synthetics@settings

Elastic Agent 使用这些模板为其数据流配置后备索引。如果要自定义这些模板，请不要覆盖它们，因为它们可能会在更新后重置。相反，请在托管索引模板的 composed_of 部分中查找 *@custom 组件模板。这些自定义组件模板允许您自定义托管索引模板的映射，而无需覆盖托管索引模板或组件模板。请注意，自定义组件模板可能尚不存在。在使用创建或更新组件模板创建它们之后，它们将被索引模板拾取。请参阅更改数据流的映射和设置，了解如何将更改应用于相应的数据流。

为了避免与内置和 Fleet 管理的组件模板发生命名冲突，请避免在您自己的组件模板名称中使用 @。该规则的例外是 *@custom 组件模板，它们使您可以安全地自定义托管索引模板。

查询参数

编辑
create
(可选，布尔值) 如果为 true，则此请求不能替换或更新现有组件模板。默认为 false。
master_timeout
(可选，时间单位) 等待主节点的时间。如果主节点在超时过期之前不可用，则请求失败并返回错误。默认为 30s。也可以设置为 -1 以表示请求永远不应超时。

请求正文

编辑
template

(必需，对象) 这是要应用的模板，可以选择包括 mappings、settings 或 aliases 配置。

template 的属性
aliases

(可选，对象数组) 要添加的别名。

如果索引模板包含 data_stream 对象，则这些是数据流别名。否则，这些是索引别名。数据流别名忽略 index_routing、routing 和 search_routing 选项。

aliases 对象的属性
<别名>

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象正文包含别名的选项。支持空对象。

<别名> 的属性
filter
(可选，查询 DSL 对象) 用于限制别名可以访问的文档的查询。
index_routing
(可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden
(可选，布尔值) 如果为 true，则该别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index
(可选，布尔值) 如果为 true，则该索引是别名的写入索引。默认为 false。
routing
(可选，字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing
(可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。
mappings

(可选，映射对象) 索引中字段的映射。如果指定，此映射可以包括

请参阅映射。

settings
(可选，索引设置对象) 索引的配置选项。请参阅索引设置。
version
(可选，整数) 用于在外部管理组件模板的版本号。此数字不是由 Elasticsearch 自动生成或递增的。
allow_auto_create
(可选，布尔值) 此设置将覆盖 action.auto_create_index 集群设置的值。如果在模板中设置为 true，即使通过 actions.auto_create_index 禁用了索引的自动创建，也可以使用该模板自动创建索引。如果设置为 false，则与模板匹配的索引或数据流必须始终显式创建，并且永远不能自动创建。
_meta
(可选，对象) 关于组件模板的可选用户元数据。可以包含任何内容。此映射不是由 Elasticsearch 自动生成的。
deprecated
(可选，布尔值) 将此组件模板标记为已弃用。当在创建或更新非弃用的索引模板时引用已弃用的组件模板时，Elasticsearch 将发出弃用警告。end::template[]

示例

编辑

带有索引别名的组件模板

编辑

您可以在组件模板中包含索引别名。

resp = client.cluster.put_component_template(
    name="template_1",
    template={
        "settings": {
            "number_of_shards": 1
        },
        "aliases": {
            "alias1": {},
            "alias2": {
                "filter": {
                    "term": {
                        "user.id": "kimchy"
                    }
                },
                "routing": "shard-1"
            },
            "{index}-alias": {}
        }
    },
)
print(resp)
response = client.cluster.put_component_template(
  name: 'template_1',
  body: {
    template: {
      settings: {
        number_of_shards: 1
      },
      aliases: {
        "alias1": {},
        "alias2": {
          filter: {
            term: {
              'user.id' => 'kimchy'
            }
          },
          routing: 'shard-1'
        },
        "{index}-alias": {}
      }
    }
  }
)
puts response
const response = await client.cluster.putComponentTemplate({
  name: "template_1",
  template: {
    settings: {
      number_of_shards: 1,
    },
    aliases: {
      alias1: {},
      alias2: {
        filter: {
          term: {
            "user.id": "kimchy",
          },
        },
        routing: "shard-1",
      },
      "{index}-alias": {},
    },
  },
});
console.log(response);
PUT _component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user.id" : "kimchy" }
            },
            "routing" : "shard-1"
        },
        "{index}-alias" : {} 
    }
  }
}

别名名称中的 {index} 占位符将在索引创建期间替换为模板所应用的实际索引名称。

应用组件模板

编辑

您不能直接将组件模板应用于数据流或索引。要应用，组件模板必须包含在索引模板的 composed_of 列表中。请参阅索引模板。

组件模板版本控制

编辑

您可以使用 version 参数向组件模板添加版本号。外部系统可以使用这些版本号来简化模板管理。

version 参数是可选的，并且不是由 Elasticsearch 自动生成或使用的。

要取消设置 version，请在不指定版本的情况下替换模板。

resp = client.cluster.put_component_template(
    name="template_1",
    template={
        "settings": {
            "number_of_shards": 1
        }
    },
    version=123,
)
print(resp)
response = client.cluster.put_component_template(
  name: 'template_1',
  body: {
    template: {
      settings: {
        number_of_shards: 1
      }
    },
    version: 123
  }
)
puts response
const response = await client.cluster.putComponentTemplate({
  name: "template_1",
  template: {
    settings: {
      number_of_shards: 1,
    },
  },
  version: 123,
});
console.log(response);
PUT /_component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "version": 123
}

要检查 version，您可以使用获取组件模板 API。

组件模板元数据

编辑

您可以使用 _meta 参数向组件模板添加任意元数据。此用户定义的对象存储在集群状态中，因此最好保持其简短。

_meta 参数是可选的，并且不是由 Elasticsearch 自动生成或使用的。

要取消设置 _meta，请在不指定元数据的情况下替换模板。

resp = client.cluster.put_component_template(
    name="template_1",
    template={
        "settings": {
            "number_of_shards": 1
        }
    },
    meta={
        "description": "set number of shards to one",
        "serialization": {
            "class": "MyComponentTemplate",
            "id": 10
        }
    },
)
print(resp)
response = client.cluster.put_component_template(
  name: 'template_1',
  body: {
    template: {
      settings: {
        number_of_shards: 1
      }
    },
    _meta: {
      description: 'set number of shards to one',
      serialization: {
        class: 'MyComponentTemplate',
        id: 10
      }
    }
  }
)
puts response
const response = await client.cluster.putComponentTemplate({
  name: "template_1",
  template: {
    settings: {
      number_of_shards: 1,
    },
  },
  _meta: {
    description: "set number of shards to one",
    serialization: {
      class: "MyComponentTemplate",
      id: 10,
    },
  },
});
console.log(response);
PUT /_component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "_meta": {
    "description": "set number of shards to one",
    "serialization": {
      "class": "MyComponentTemplate",
      "id": 10
    }
  }
}

要检查 _meta，您可以使用获取组件模板 API。

« 创建或更新别名 API 创建或更新索引模板 API »