› › ›

模拟摄取 API

模拟摄取 API编辑

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

response = 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'
            }
          }
        ]
      }
    }
  }
)
puts 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"
          }
        }
      ]
    }
  }
}

这将在本次请求期间将现有的 my-pipeline 管道替换为此处给出的内容。

请求编辑

POST /_ingest/_simulate

GET /_ingest/_simulate

POST /_ingest/<target>/_simulate

GET /_ingest/<target>/_simulate

先决条件编辑

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

模拟摄取 API 模拟将数据摄取到索引中。它针对请求正文中提供的一组文档执行该索引的默认和最终管道。如果管道包含重新路由处理器，它会跟随该重新路由处理器到新索引，并以与非模拟摄取相同的方式执行该索引的管道。没有数据被索引到 Elasticsearch 中。相反，返回转换后的文档，以及已执行的管道列表和如果这不是模拟则文档将被索引到的索引的名称。这与模拟管道 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 将发出弃用警告。

示例编辑

使用预先存在的管道定义编辑

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

response = client.simulate.ingest(
  body: {
    docs: [
      {
        _index: 'my-index',
        _id: '123',
        _source: {
          foo: 'bar'
        }
      },
      {
        _index: 'my-index',
        _id: '456',
        _source: {
          foo: 'rab'
        }
      }
    ]
  }
)
puts 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"
            ]
         }
      }
   ]
}

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

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

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

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

« 模拟管道 API 许可 API »

模拟摄取 API