New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 模拟管道 API GeoIP 统计 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›摄取 API

模拟摄取 API

编辑

模拟摄取 API

编辑

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

resp = client.simulate.ingest(
    body={
        "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"
                ]
            }
        },
        "mapping_addition": {
            "dynamic": "strict",
            "properties": {
                "foo": {
                    "type": "keyword"
                }
            }
        }
    },
)
print(resp)
const response = await client.simulate.ingest({
  body: {
    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"],
      },
    },
    mapping_addition: {
      dynamic: "strict",
      properties: {
        foo: {
          type: "keyword",
        },
      },
    },
  },
});
console.log(response);
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"]
    }
  },
  "mapping_addition": { 
    "dynamic": "strict",
    "properties": {
      "foo": {
        "type": "keyword"
      }
    }
  }
}
Copy as curlTry in Elastic 

这会在本次请求期间将现有的 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

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

有关如何使用 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（时间序列数据流）和 logsdb（日志数据流）。

模板的 index_mode 设置后备索引的 index.mode。

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 将发出弃用警告。
mapping_addition
（可选，映射对象）将合并到索引映射中的映射定义，以便在此请求过程中进行验证。

示例

编辑

使用预先存在的管道定义

编辑

在此示例中，索引 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"
      }
    }
  ]
}
Copy as curlTry in Elastic 

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"
          }
        }
      ]
    }
  }
}
Copy as curlTry in Elastic 

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"
            }
          }
        }
      }
    }
  }
}
Copy as curlTry in Elastic 

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 »