› › ›

创建或更新组件模板 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/<component-template>

先决条件

编辑

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

描述

编辑

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

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

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

组件模板中的注释

编辑

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

路径参数

编辑

<component-template>

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

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 对象的属性

<alias>

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

对象主体包含别名的选项。支持空对象。

<alias> 的属性

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 »