PUT _ingest/pipeline/my-pipeline-id
{
  "description" : "My optional pipeline description",
  "processors" : [
    {
      "set" : {
        "description" : "My optional processor description",
        "field": "my-keyword-field",
        "value": "foo"
      }
    }
  ]
}

请求

edit

PUT /_ingest/pipeline/

先决条件

edit

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

路径参数

edit

<pipeline>: （必需，字符串）要创建或更新的摄取管道的ID。

为了避免与内置和Fleet管理的摄取管道命名冲突，请避免在自己的摄取管道名称中使用@。该规则的例外是*@custom摄取管道，它们允许您安全地将自定义管道添加到管理管道中。另请参阅Fleet和Elastic Agent的管道。

查询参数

edit

if_version: (可选，整数) 仅当管道具有此版本时才执行操作。如果指定且更新成功，管道的版本将递增。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

description

(可选, 字符串) 摄取管道的描述。

on_failure

(可选，处理器对象数组) 在处理器失败后立即运行的处理器。

每个处理器都支持一个处理器级别的 on_failure 值。如果一个没有 on_failure 值的处理器失败，Elasticsearch 会使用这个管道级别的参数作为回退。该参数中的处理器会按照指定的顺序依次运行。Elasticsearch 不会尝试运行管道的其余处理器。

processors

(必需的，处理器对象的数组) 处理器用于在索引文档之前执行转换。处理器按照指定的顺序依次运行。

version

(可选, 整数) 外部系统用于跟踪摄取管道的版本号。

请参阅上述if_version参数，了解版本属性的使用方式。

_meta

(可选, 对象) 关于摄取管道的可选元数据。可以包含任何内容。此映射不会由Elasticsearch自动生成。

deprecated

(可选, 布尔值) 将此摄取管道标记为已弃用。当引用已弃用的摄取管道作为创建或更新非弃用索引模板时的默认或最终管道时， Elasticsearch 将发出弃用警告。

示例

edit

管道元数据

edit

您可以使用 _meta 参数将任意元数据添加到管道中。这个用户定义的对象存储在集群状态中，因此保持其简短是可取的。

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

要取消设置_meta，请在不指定的情况下替换管道。

PUT /_ingest/pipeline/my-pipeline-id
{
  "description" : "My optional pipeline description",
  "processors" : [
    {
      "set" : {
        "description" : "My optional processor description",
        "field": "my-keyword-field",
        "value": "foo"
      }
    }
  ],
  "_meta": {
    "reason": "set my-keyword-field to foo",
    "serialization": {
      "class": "MyPipeline",
      "id": 10
    }
  }
}

要检查 _meta，请使用 get pipeline API。

获取管道 API

edit

返回一个或多个摄取管道的信息。此API返回管道的本地引用。

GET /_ingest/pipeline/my-pipeline-id

请求

edit

GET /_ingest/pipeline/

GET /_ingest/pipeline

先决条件

edit

如果启用了Elasticsearch的安全功能，您必须拥有read_pipeline、manage_pipeline、manage_ingest_pipelines或manage 集群权限才能使用此API。

路径参数

edit

<pipeline>

(可选，字符串) 以逗号分隔的管道ID列表以进行检索。支持通配符 (*) 表达式。

要获取所有摄取管道，请省略此参数或使用 *。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

示例

edit

获取特定摄取管道的信息

edit

GET /_ingest/pipeline/my-pipeline-id

API返回以下响应：

{
  "my-pipeline-id" : {
    "description" : "describe pipeline",
    "version" : 123,
    "processors" : [
      {
        "set" : {
          "field" : "foo",
          "value" : "bar"
        }
      }
    ]
  }
}

删除管道 API

edit

删除一个或多个现有的摄取管道。

DELETE /_ingest/pipeline/my-pipeline-id

请求

edit

DELETE /_ingest/pipeline/

前提条件

edit

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

路径参数

edit

<pipeline>

(必需，字符串) 管道ID或管道ID的通配符表达式，用于限制请求。

要删除集群中的所有摄取管道，请使用值 *。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

示例

edit

删除特定的摄取管道

edit

DELETE /_ingest/pipeline/pipeline-one

使用通配符表达式删除摄取管道

edit

DELETE /_ingest/pipeline/pipeline-*

删除所有摄取管道

edit

DELETE /_ingest/pipeline/*

模拟管道API

edit

对一组提供的文档执行摄取管道。

POST /_ingest/pipeline/my-pipeline-id/_simulate
{
  "docs": [
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}

请求

edit

POST /_ingest/pipeline//_simulate

GET /_ingest/pipeline//_simulate

POST /_ingest/pipeline/_simulate

GET /_ingest/pipeline/_simulate

先决条件

edit

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

描述

edit

模拟管道API针对请求体中提供的一组文档执行特定的管道。

您可以指定一个现有的管道来对提供的文档执行操作，或者在请求的正文中提供一个管道定义。

路径参数

edit

<pipeline>: (必填*, 字符串) 要测试的管道。如果在请求体中未指定pipeline，则此参数是必需的。

查询参数

edit

verbose: (可选, 布尔值) 如果 true，响应将包括执行的管道中每个处理器的数据输出。

请求体

edit

pipeline

(必需*, 对象) 要测试的管道。如果您没有指定请求路径参数，则此参数是必需的。如果您同时指定了此参数和请求路径参数，API 仅使用请求路径参数。

Properties of pipeline

description

(可选, 字符串) 摄取管道的描述。

on_failure

(可选，处理器对象数组) 在处理器失败后立即运行的处理器。

processors

(必需, 处理器对象数组) 用于在索引文档之前执行转换的处理器。处理器按照指定的顺序依次运行。

version

(可选, 整数) 外部系统用于跟踪摄取管道的版本号。

请参阅上述if_version参数，了解版本属性的使用方式。

_meta

(可选, 对象) 关于摄取管道的可选元数据。可以包含任何内容。此映射不会由 Elasticsearch 自动生成。

deprecated

(可选, 布尔值) 将此摄取管道标记为已弃用。当一个已弃用的摄取管道在创建或更新非弃用索引模板时被引用为默认或最终管道时， Elasticsearch 将发出弃用警告。

docs

(必需，对象数组) 用于在管道中测试的示例文档。

Properties of docs objects

_id: (可选，字符串) 文档的唯一标识符。此ID在_index中必须是唯一的。
_index: (可选，字符串) 包含文档的索引名称。
_routing: (可选，字符串) 用于将文档发送到特定主分片的值。请参阅 _routing字段。
_source: (必需，对象) 文档的JSON主体。

示例

edit

将管道指定为路径参数

edit

POST /_ingest/pipeline/my-pipeline-id/_simulate
{
  "docs": [
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}

API返回以下响应：

{
   "docs": [
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "bar"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.187Z"
            }
         }
      },
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "rab"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.188Z"
            }
         }
      }
   ]
}

在请求体中指定一个管道

edit

POST /_ingest/pipeline/_simulate
{
  "pipeline" :
  {
    "description": "_description",
    "processors": [
      {
        "set" : {
          "field" : "field2",
          "value" : "_value"
        }
      }
    ]
  },
  "docs": [
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}

API返回以下响应：

{
   "docs": [
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "bar"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.187Z"
            }
         }
      },
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "rab"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.188Z"
            }
         }
      }
   ]
}

查看详细结果

edit

您可以使用模拟管道API来查看每个处理器如何影响通过管道的摄取文档。要在模拟请求中查看每个处理器的中间结果，您可以向请求中添加verbose参数。

POST /_ingest/pipeline/_simulate?verbose=true
{
  "pipeline" :
  {
    "description": "_description",
    "processors": [
      {
        "set" : {
          "field" : "field2",
          "value" : "_value2"
        }
      },
      {
        "set" : {
          "field" : "field3",
          "value" : "_value3"
        }
      }
    ]
  },
  "docs": [
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}

API返回以下响应：

{
  "docs" : [
    {
      "processor_results" : [
        {
          "processor_type" : "set",
          "status" : "success",
          "doc" : {
            "_index" : "index",
            "_id" : "id",
            "_version": "-3",
            "_source" : {
              "field2" : "_value2",
              "foo" : "bar"
            },
            "_ingest" : {
              "pipeline" : "_simulate_pipeline",
              "timestamp" : "2020-07-30T01:21:24.251836Z"
            }
          }
        },
        {
          "processor_type" : "set",
          "status" : "success",
          "doc" : {
            "_index" : "index",
            "_id" : "id",
            "_version": "-3",
            "_source" : {
              "field3" : "_value3",
              "field2" : "_value2",
              "foo" : "bar"
            },
            "_ingest" : {
              "pipeline" : "_simulate_pipeline",
              "timestamp" : "2020-07-30T01:21:24.251836Z"
            }
          }
        }
      ]
    },
    {
      "processor_results" : [
        {
          "processor_type" : "set",
          "status" : "success",
          "doc" : {
            "_index" : "index",
            "_id" : "id",
            "_version": "-3",
            "_source" : {
              "field2" : "_value2",
              "foo" : "rab"
            },
            "_ingest" : {
              "pipeline" : "_simulate_pipeline",
              "timestamp" : "2020-07-30T01:21:24.251863Z"
            }
          }
        },
        {
          "processor_type" : "set",
          "status" : "success",
          "doc" : {
            "_index" : "index",
            "_id" : "id",
            "_version": "-3",
            "_source" : {
              "field3" : "_value3",
              "field2" : "_value2",
              "foo" : "rab"
            },
            "_ingest" : {
              "pipeline" : "_simulate_pipeline",
              "timestamp" : "2020-07-30T01:21:24.251863Z"
            }
          }
        }
      ]
    }
  ]
}

模拟摄取 API

edit

对一组提供的文档执行摄取管道，可选地使用替代管道定义。此API旨在用于故障排除或管道开发，因为它实际上不会将任何数据索引到Elasticsearch中。

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "my-index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ],
  "pipeline_substitutions": { 
    "my-pipeline": {
      "processors": [
        {
          "set": {
            "field": "field3",
            "value": "value3"
          }
        }
      ]
    }
  },
  "component_template_substitutions": { 
    "my-component-template": {
      "template": {
        "mappings": {
          "dynamic": "true",
          "properties": {
            "field3": {
              "type": "keyword"
            }
          }
        },
        "settings": {
          "index": {
            "default_pipeline": "my-pipeline"
          }
        }
      }
    }
  },
  "index_template_substitutions": { 
    "my-index-template": {
      "index_patterns": ["my-index-*"],
      "composed_of": ["component_template_1", "component_template_2"]
    }
  }
}

	这将替换现有的 `my-pipeline` 管道，替换内容为此请求期间给出的内容。
	这将替换现有的 `my-component-template` 组件模板，在此请求期间使用此处给出的内容。这些模板可以用于更改使用的管道，或修改用于验证结果的映射。
	这将替换现有的 `my-index-template` 索引模板，替换内容为此请求期间给出的内容。这些模板可以用于更改使用的管道，或修改用于验证结果的映射。

请求

edit

POST /_ingest/_simulate

GET /_ingest/_simulate

POST /_ingest//_simulate

GET /_ingest//_simulate

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有index或create 索引权限才能使用此API。

描述

edit

模拟摄取 API 模拟将数据摄取到索引中。它对请求体中提供的一组文档执行该索引的默认和最终管道。如果管道包含一个reroute processor，它会遵循该reroute processor到新的索引，并以与非模拟摄取相同的方式执行该索引的管道。数据不会被索引到 Elasticsearch 中。相反，返回转换后的文档，以及已执行的管道列表和文档将被索引的索引名称（如果这不是模拟）。转换后的文档会根据适用于该索引的映射进行验证，任何验证错误都会在结果中报告。

此API与 simulate pipeline API 不同之处在于，您为此API指定了一个单独的管道，并且它仅运行该一个管道。simulate pipeline API 更适合用于开发单个管道，而 simulate ingest API 则更适合用于排查在索引中摄取时应用的各种管道之间的交互问题。

默认情况下，系统中当前存在的管道定义将被使用。然而，您可以在请求的正文中提供替代的管道定义。这些定义将代替系统中已有的管道定义使用。这可以用于替换现有的管道定义或创建新的管道定义。管道替换仅在此请求中使用。

路径参数

edit

<target>: (可选，字符串) 要模拟摄取到的索引。这可以通过在每个文档上指定一个索引来覆盖。如果在请求路径中提供了一个，它将用于任何未明确指定索引参数的文档。

查询参数

edit

pipeline: (可选，字符串) 用作默认管道的管道。这可以用来覆盖正在摄取的索引的默认管道。

请求体

edit

docs

(必需，对象数组) 用于在管道中测试的示例文档。

Properties of docs objects

_id: (可选，字符串) 文档的唯一标识符。
_index: (可选，字符串) 文档将被索引到的索引名称。
_source: (必需，对象) 文档的JSON主体。

pipeline_substitutions

(可选，字符串到对象的映射) 管道ID到替代管道定义对象的映射。

管道定义对象的属性

description

(可选, 字符串) 摄取管道的描述。

on_failure

(可选，处理器对象数组) 在处理器失败后立即运行的处理器。

processors

(必需, 数组 of processor 对象) 用于在索引之前对文档执行转换的处理器。处理器按照指定的顺序依次运行。

version

(可选, 整数) 外部系统用于跟踪摄取管道的版本号。

请参阅上述if_version参数，了解版本属性的使用方式。

_meta

(可选, 对象) 关于摄取管道的可选元数据。可以包含任何内容。此映射不会由 Elasticsearch 自动生成。

deprecated

(可选, 布尔值) 将此摄取管道标记为已弃用。当一个已弃用的摄取管道被引用为创建或更新非弃用索引模板时的默认或最终管道时， Elasticsearch 将发出弃用警告。

component_template_substitutions

(可选，字符串到对象的映射) 组件模板名称到替代组件模板定义对象的映射。

组件模板定义对象的属性

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

index_template_substitutions

(可选，字符串到对象的映射) 索引模板名称到替代索引模板定义对象的映射。

索引模板定义对象的属性

composed_of

(可选，字符串数组) 组件模板名称的有序列表。组件模板按指定的顺序合并，这意味着指定的最后一个组件模板具有最高优先级。请参阅组合多个组件模板以获取示例。

data_stream

(可选, 对象) 如果包含此对象，模板将用于创建数据流及其支持的索引。支持空对象。

数据流需要一个匹配的索引模板，其中包含一个data_stream对象。请参阅创建索引模板。

data_stream 的属性

allow_custom_routing

(可选, 布尔值) 如果 true，数据流支持自定义路由。默认为 false。

hidden

(可选, 布尔值) 如果 true，数据流是隐藏的。默认为 false。

index_mode

(可选, 字符串) 要创建的数据流类型。有效值为 null (常规数据流) 和 time_series (时间序列数据流)。

如果 time_series，每个后备索引都有一个 index.mode 索引设置为 time_series。

index_patterns

(必需，字符串数组) 用于在创建时匹配数据流和索引名称的通配符 (*) 表达式数组。

Elasticsearch 包含多个内置的索引模板。为了避免与这些模板发生命名冲突，请参阅避免索引模式冲突。

_meta

(可选, 对象) 关于索引模板的可选用户元数据。可以包含任何内容。此映射不会由 Elasticsearch 自动生成。

priority

(可选, 整数) 用于确定新数据流或索引创建时索引模板优先级的优先级。具有最高优先级的索引模板将被选择。如果未指定优先级，则模板将被视为优先级为 0 (最低优先级)。此数字不会由 Elasticsearch 自动生成。

template

(可选, 对象) 要应用的模板。它可以选择性地包括一个 aliases、mappings 或 settings 配置。

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 自动生成。

deprecated

(可选, 布尔值) 将此索引模板标记为已弃用。当创建或更新使用已弃用组件的非弃用索引模板时， Elasticsearch 将发出弃用警告。

示例

edit

使用预先存在的管道定义

edit

在这个例子中，索引 index 有一个默认的管道叫做 my-pipeline，以及一个最终的管道叫做 my-final-pipeline。由于两个文档都被索引到 index 中，系统中已有的管道定义将被用于执行这两个管道。

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "123",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "my-index",
      "_id": "456",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}

API返回以下响应：

{
   "docs": [
      {
         "doc": {
            "_id": "123",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field1": "value1",
               "field2": "value2",
               "foo": "bar"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      },
      {
         "doc": {
            "_id": "456",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field1": "value1",
               "field2": "value2",
               "foo": "rab"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      }
   ]
}

在请求体中指定管道替换

edit

在这个例子中，索引 my-index 有一个默认的管道叫做 my-pipeline，以及一个最终的管道叫做 my-final-pipeline。但在 pipeline_substitutions 中提供了一个 my-pipeline 的替代定义。替代的 my-pipeline 将被用来代替系统中的 my-pipeline，然后系统中已经定义的 my-final-pipeline 将被执行。

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "123",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "my-index",
      "_id": "456",
      "_source": {
        "foo": "rab"
      }
    }
  ],
  "pipeline_substitutions": {
    "my-pipeline": {
      "processors": [
        {
          "uppercase": {
            "field": "foo"
          }
        }
      ]
    }
  }
}

API返回以下响应：

{
   "docs": [
      {
         "doc": {
            "_id": "123",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field2": "value2",
               "foo": "BAR"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      },
      {
         "doc": {
            "_id": "456",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field2": "value2",
               "foo": "RAB"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      }
   ]
}

在请求体中指定组件模板替换

edit

在这个例子中，假设索引 my-index 有一个严格的映射，只定义了 foo 关键字字段。假设该字段映射来自一个名为 my-mappings-template 的组件模板。我们想要测试添加一个新字段，bar。因此，在 component_template_substitutions 中提供了一个 my-mappings-template 的替代定义。替代的 my-mappings-template 将用于替代现有 my-index 的映射，并替代系统中的 my-mappings-template。

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "123",
      "_source": {
        "foo": "foo"
      }
    },
    {
      "_index": "my-index",
      "_id": "456",
      "_source": {
        "bar": "rab"
      }
    }
  ],
  "component_template_substitutions": {
    "my-mappings_template": {
      "template": {
        "mappings": {
          "dynamic": "strict",
          "properties": {
            "foo": {
              "type": "keyword"
            },
            "bar": {
              "type": "keyword"
            }
          }
        }
      }
    }
  }
}

API返回以下响应：

{
   "docs": [
      {
         "doc": {
            "_id": "123",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "foo": "foo"
            },
            "executed_pipelines": []
         }
      },
      {
         "doc": {
            "_id": "456",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "bar": "rab"
            },
            "executed_pipelines": []
         }
      }
   ]
}

GeoIP 统计 API

edit

获取关于geoip处理器的统计信息，包括与它一起使用的GeoIP2数据库的下载统计信息。

GET _ingest/geoip/stats

请求

edit

GET _ingest/geoip/stats

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有monitor或manage 集群权限才能使用此API。
如果ingest.geoip.downloader.enabled被禁用且未配置自定义数据库，此API将返回零值和一个空的nodes对象。

响应体

edit

stats

(对象) 下载所有GeoIP2数据库的统计信息。

Properties of stats

successful_downloads: (整数) 成功下载数据库的总次数。
failed_downloads: (整数) 下载数据库失败的总次数。
total_download_time: (整数) 下载数据库所花费的总毫秒数。
database_count: (整数) 当前可用的数据库数量。
skipped_updates: (整数) 跳过的数据库更新总次数。

nodes

(对象) 每个节点的统计信息。

Properties of nodes

(对象) 下载的节点数据库。字段键是节点ID。

Properties of

databases

(对象数组) 节点的已下载数据库。

Properties of databases objects

name: (字符串) 数据库的名称。

cache_stats

(对象) 节点的GeoIP缓存统计信息。

Properties of cache_stats

count: (长整型) 缓存条目的数量。
hits: (长整型) 从缓存中提供服务的丰富查找次数。
misses: (长整型) 无法从缓存中提供服务的geoIP查找次数。
evictions: (长整型) 从缓存中驱逐的缓存条目数量。
hits_time_in_millis: (长整型) 仅在成功缓存命中时，从缓存中获取数据所花费的时间（以毫秒为单位）。
misses_time_in_millis: (长整型) 仅在缓存未命中时，从缓存和后备GeoIP2数据库中获取数据并更新缓存所花费的时间（以毫秒为单位）。

files_in_temp

(字符串数组) 下载的数据库文件，包括相关的许可证文件。Elasticsearch将这些文件存储在节点的临时目录中： $ES_TMPDIR/geoip-databases/。

创建或更新geoip数据库配置API

edit

创建或更新IP地理位置数据库配置。

下面显示的 Maxmind account_id 需要一个许可证密钥。由于许可证密钥是敏感信息，它作为安全设置存储在 Elasticsearch 中，名称为 ingest.geoip.downloader.maxmind.license_key。目前每个 Elasticsearch 集群只允许一个 Maxmind 许可证密钥。为了从 Maxmind 下载数据，必须在安全设置中提供有效的许可证密钥。许可证密钥设置在所有节点重新启动之前不会生效。

PUT _ingest/geoip/database/my-database-id
{
  "name": "GeoIP2-Domain",
  "maxmind": {
    "account_id": "1025402"
  }
}

请求

edit

PUT /_ingest/geoip/database/

先决条件

edit

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

路径参数

edit

<database>: __ （必需，字符串）要创建或更新的数据库配置的ID。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

name

(必需，字符串) 要下载的IP地理位置数据库的提供者分配名称。

<provider>

(必需的，一个提供者对象及其相关配置) 用于识别要使用哪个IP地理位置提供者来下载数据库的必要配置，以及任何特定于提供者的下载所需配置。

目前，唯一支持的提供商是 maxmind，并且 maxmind 提供商要求配置一个 account_id（字符串）。

许可

edit

从第三方提供商下载数据库是一项需要适当许可的商业功能。更多信息，请参阅 https://www.elastic.co/subscriptions。

获取geoip数据库配置API

edit

返回一个或多个GeoIP数据库配置的信息。

GET /_ingest/geoip/database/my-database-id

请求

edit

GET /_ingest/geoip/database/

GET /_ingest/geoip/database

先决条件

edit

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

路径参数

edit

<database>

(可选，字符串) 逗号分隔的数据库配置ID列表，用于检索。支持通配符 (*) 表达式。

要获取所有数据库配置，请省略此参数或使用 *。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

示例

edit

获取特定geoip数据库配置的信息

edit

GET /_ingest/geoip/database/my-database-id

API返回以下响应：

{
  "databases" : [
    {
      "id" : "my-database-id",
      "version" : 1,
      "modified_date_millis" : 1723040276114,
      "database" : {
        "name" : "GeoIP2-Domain",
        "maxmind" : {
          "account_id" : "1234567"
        }
      }
    }
  ]
}

删除 geoip 数据库配置 API

edit

删除一个地理IP数据库配置。

DELETE /_ingest/geoip/database/my-database-id

请求

edit

DELETE /_ingest/geoip/database/

先决条件

edit

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

路径参数

edit

<database>: (必需, 字符串) 用于限制请求的数据库配置ID。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

示例

edit

删除特定的geoip数据库配置

edit

DELETE /_ingest/geoip/database/example-database-id

« Info API Licensing APIs »