インジェストAPI - インジェストをシミュレート（Simulate ingest）

シミュレートインジェストAPI
リクエスト
前提条件
説明
パスパラメータ
クエリパラメータ
リクエストボディ
例
- 既存のパイプライン定義を使用する
- リクエストボディにパイプラインの置き換えを指定する

シミュレートインジェストAPI

提供されたドキュメントのセットに対してインジェストパイプラインを実行し、オプションで代替パイプライン定義を使用します。このAPIは、実際にデータをElasticsearchにインデックスしないため、トラブルシューティングやパイプライン開発に使用されることを意図しています。

Python

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"
   }
   }
   ]
   }
   }
   },
)
print(resp)

Ruby

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のセキュリティ機能が有効になっている場合、このAPIを使用するには index または create インデックス権限が必要です。

説明

シミュレートインジェストAPIは、インデックスへのデータのインジェストをシミュレートします。リクエストのボディに提供されたドキュメントのセットに対して、そのインデックスのデフォルトおよび最終パイプラインを実行します。パイプラインにリルートプロセッサが含まれている場合、そのリルートプロセッサに従って新しいインデックスに移動し、非シミュレートインジェストと同様にそのインデックスのパイプラインを実行します。データはElasticsearchにインデックスされません。代わりに、変換されたドキュメントが返され、実行されたパイプラインのリストと、シミュレーションでなければインデックスされていたであろうインデックスの名前が返されます。これは、シミュレートパイプラインAPIとは異なり、そのAPIには単一のパイプラインを指定し、その1つのパイプラインのみを実行します。シミュレートパイプラインAPIは単一のパイプラインの開発により便利であり、シミュレートインジェストAPIはインデックスへのインジェスト時に適用されるさまざまなパイプラインの相互作用のトラブルシューティングにより便利です。

デフォルトでは、システム内に現在存在するパイプライン定義が使用されます。ただし、リクエストのボディに代替パイプライン定義を提供することもできます。これにより、システム内に既に存在するパイプライン定義を置き換えたり、新しいものを作成したりできます。パイプラインの置き換えは、このリクエスト内でのみ使用されます。

パスパラメータ

<target>
(オプション、文字列) インジェスト先のインデックス。このインデックスは、各ドキュメントでインデックスを指定することで上書きできます。リクエストパスに \ を提供すると、明示的にインデックス引数を指定していないドキュメントに使用されます。
\u003c/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は非推奨警告を発します。

例

既存のパイプライン定義を使用する

この例では、インデックス index に my-pipeline というデフォルトパイプラインと my-final-pipeline という最終パイプラインがあります。両方のドキュメントが index にインジェストされるため、両方のパイプラインがシステム内に既に存在するパイプライン定義を使用して実行されます。

Python

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

Ruby

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

Js

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

リクエストボディにパイプラインの置き換えを指定する

この例では、インデックス index に my-pipeline というデフォルトパイプラインと my-final-pipeline という最終パイプラインがあります。しかし、my-pipeline の代替定義が pipeline_substitutions に提供されています。代替 my-pipeline は、システム内の my-pipeline の代わりに使用され、その後、システム内に既に定義されている my-final-pipeline が実行されます。

Python

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)

Ruby

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

Js

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