› › ›

模拟摄取 API

针对一组提供的文档执行摄取管道，可以选择使用替代管道定义。此 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` 索引模板替换为此处提供的內容，并在本次请求期间有效。这些模板可用于更改使用的管道或修改用于验证结果的映射。

请求

编辑

POST /_ingest/_simulate

GET /_ingest/_simulate

POST /_ingest/<target>/_simulate

GET /_ingest/<target>/_simulate

先决条件

编辑

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

描述

编辑

模拟摄取 API 模拟将数据摄取到索引中。它针对请求正文中提供的一组文档执行该索引的默认和最终管道。如果管道包含重路由处理器，则它会遵循该重路由处理器到新索引，并以与非模拟摄取相同的方式执行该索引的管道。不会将任何数据索引到 Elasticsearch 中。而是返回转换后的文档，以及已执行的管道列表以及文档在未模拟的情况下将被索引到的索引名称。转换后的文档将根据适用于此索引的映射进行验证，并且任何验证错误都将在结果中报告。

此 API 与模拟管道 API 不同，因为您为该 API 指定了一个管道，并且它仅运行该管道。模拟管道 API 更有助于开发单个管道，而模拟摄取 API 更有助于对摄取到索引时应用的各种管道的交互进行故障排除。

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

路径参数

编辑

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

查询参数

编辑

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

请求正文

编辑

docs

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

docs 对象的属性

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

pipeline_substitutions

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

管道定义对象的属性

description

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

on_failure

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

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

processors

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

version

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

有关如何使用版本属性，请参阅上面的 if_version 参数。

_meta

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

deprecated

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

component_template_substitutions

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

组件模板定义对象的属性

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

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

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

deprecated

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

示例

编辑

使用预先存在的管道定义

编辑

在此示例中，索引index具有名为my-pipeline的默认管道和名为my-final-pipeline的最终管道。由于两个文档都正在摄取到index中，因此两个管道都使用系统中已存在的管道定义执行。

resp = client.simulate.ingest(
    body={
        "docs": [
            {
                "_index": "my-index",
                "_id": "123",
                "_source": {
                    "foo": "bar"
                }
            },
            {
                "_index": "my-index",
                "_id": "456",
                "_source": {
                    "foo": "rab"
                }
            }
        ]
    },
)
print(resp)

response = client.simulate.ingest(
  body: {
    docs: [
      {
        _index: 'my-index',
        _id: '123',
        _source: {
          foo: 'bar'
        }
      },
      {
        _index: 'my-index',
        _id: '456',
        _source: {
          foo: 'rab'
        }
      }
    ]
  }
)
puts response

const response = await client.simulate.ingest({
  body: {
    docs: [
      {
        _index: "my-index",
        _id: "123",
        _source: {
          foo: "bar",
        },
      },
      {
        _index: "my-index",
        _id: "456",
        _source: {
          foo: "rab",
        },
      },
    ],
  },
});
console.log(response);

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"
            ]
         }
      }
   ]
}

在请求正文中指定管道替换

编辑

在此示例中，索引my-index具有名为my-pipeline的默认管道和名为my-final-pipeline的最终管道。但在pipeline_substitutions中提供了my-pipeline的替换定义。替换的my-pipeline将用于代替系统中的my-pipeline，然后将执行系统中已定义的my-final-pipeline。

resp = client.simulate.ingest(
    body={
        "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"
                        }
                    }
                ]
            }
        }
    },
)
print(resp)

response = client.simulate.ingest(
  body: {
    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'
            }
          }
        ]
      }
    }
  }
)
puts response

const response = await client.simulate.ingest({
  body: {
    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",
            },
          },
        ],
      },
    },
  },
});
console.log(response);

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"
            ]
         }
      }
   ]
}

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

编辑

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

resp = client.simulate.ingest(
    body={
        "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"
                            }
                        }
                    }
                }
            }
        }
    },
)
print(resp)

const response = await client.simulate.ingest({
  body: {
    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",
              },
            },
          },
        },
      },
    },
  },
});
console.log(response);

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": []
         }
      }
   ]
}

« 模拟管道 API GeoIP 统计 API »