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

创建或更新组件模板 API

编辑

创建或更新组件模板 API编辑

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

response = client.cluster.put_component_template(
  name: 'template_1',
  body: {
    template: {
      settings: {
        number_of_shards: 1
      },
      mappings: {
        _source: {
          enabled: false
        },
        properties: {
          host_name: {
            type: 'keyword'
          },
          created_at: {
            type: 'date',
            format: 'EEE MMM dd HH:mm:ss Z yyyy'
          }
        }
      }
    }
  }
)
puts response
PUT _component_template/template_1
{
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "mappings": {
      "_source": {
        "enabled": false
      },
      "properties": {
        "host_name": {
          "type": "keyword"
        },
        "created_at": {
          "type": "date",
          "format": "EEE MMM dd HH:mm:ss Z yyyy"
        }
      }
    }
  }
}

请求编辑

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 将发出弃用警告。

示例编辑

具有索引别名的组件模板编辑

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

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
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，请替换模板而不指定版本。

response = client.cluster.put_component_template(
  name: 'template_1',
  body: {
    template: {
      settings: {
        number_of_shards: 1
      }
    },
    version: 123
  }
)
puts response
PUT /_component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "version": 123
}

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

组件模板元数据编辑

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

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

要取消设置 _meta，请替换模板而不指定元数据。

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
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 »