From 6f48b39ac57dbcc65335eb00020f32e2a30ba9a8 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 24 Sep 2019 16:46:32 -0400 Subject: [PATCH 1/2] [DOCS] Reformat get pipeline API --- .../ingest/apis/get-pipeline.asciidoc | 132 ++++++++++-------- .../ingest/apis/put-pipeline.asciidoc | 45 ++++++ docs/reference/rest-api/common-parms.asciidoc | 6 + 3 files changed, 126 insertions(+), 57 deletions(-) diff --git a/docs/reference/ingest/apis/get-pipeline.asciidoc b/docs/reference/ingest/apis/get-pipeline.asciidoc index 887ae870f5257..70cb6a4c91d39 100644 --- a/docs/reference/ingest/apis/get-pipeline.asciidoc +++ b/docs/reference/ingest/apis/get-pipeline.asciidoc @@ -1,15 +1,19 @@ [[get-pipeline-api]] -=== Get Pipeline API +=== Get pipeline API +++++ +Get pipeline +++++ -The get pipeline API returns pipelines based on ID. This API always returns a local reference of the pipeline. - -////////////////////////// +Returns information about one or more ingest pipelines. +This API returns a local reference of the pipeline. +//// [source,console] --------------------------------------------------- -PUT _ingest/pipeline/my-pipeline-id +---- +PUT /_ingest/pipeline/my-pipeline-id { "description" : "describe pipeline", + "version" : 123, "processors" : [ { "set" : { @@ -19,23 +23,59 @@ PUT _ingest/pipeline/my-pipeline-id } ] } --------------------------------------------------- +---- +//// + +[source,console] +---- +GET /_ingest/pipeline/my-pipeline-id +---- +// TEST[continued] + + + +[[get-pipeline-api-request]] +==== {api-request-title} + +`GET /_ingest/pipeline/` + +`GET /_ingest/pipeline` + + +[[get-pipeline-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=path-pipeline] + + + +[[get-pipeline-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] + -////////////////////////// +[[get-pipeline-api-api-example]] +==== {api-examples-title} + + +[[get-pipeline-api-specific-ex]] +===== Get information for a specific ingest pipeline [source,console] --------------------------------------------------- -GET _ingest/pipeline/my-pipeline-id --------------------------------------------------- +---- +GET /_ingest/pipeline/my-pipeline-id +---- // TEST[continued] -Example response: +The API returns the following response: [source,console-result] --------------------------------------------------- +---- { "my-pipeline-id" : { "description" : "describe pipeline", + "version" : 123, "processors" : [ { "set" : { @@ -46,73 +86,51 @@ Example response: ] } } --------------------------------------------------- +---- -For each returned pipeline, the source and the version are returned. -The version is useful for knowing which version of the pipeline the node has. -You can specify multiple IDs to return more than one pipeline. Wildcards are also supported. -[float] -[[versioning-pipelines]] -==== Pipeline Versioning +[[get-pipeline-api-version-ex]] +===== Get the version of an ingest pipeline -Pipelines can optionally add a `version` number, which can be any integer value, -in order to simplify pipeline management by external systems. The `version` -field is completely optional and it is meant solely for external management of -pipelines. To unset a `version`, simply replace the pipeline without specifying -one. +When creating an ingest pipeline, +you can specify an optional `version` parameter. +The version is useful for managing changes to pipeline +and viewing the current pipeline for an ingest node. -[source,console] --------------------------------------------------- -PUT _ingest/pipeline/my-pipeline-id -{ - "description" : "describe pipeline", - "version" : 123, - "processors" : [ - { - "set" : { - "field": "foo", - "value": "bar" - } - } - ] -} --------------------------------------------------- -To check for the `version`, you can -<> -using `filter_path` to limit the response to just the `version`: +To check the pipeline version, +use the `filter_path` query parameter +to <> +to only the version. [source,console] --------------------------------------------------- +---- GET /_ingest/pipeline/my-pipeline-id?filter_path=*.version --------------------------------------------------- +---- // TEST[continued] -This should give a small response that makes it both easy and inexpensive to parse: +The API returns the following response: [source,console-result] --------------------------------------------------- +---- { "my-pipeline-id" : { "version" : 123 } } --------------------------------------------------- - -////////////////////////// +---- +//// [source,console] --------------------------------------------------- +---- DELETE /_ingest/pipeline/my-pipeline-id --------------------------------------------------- +---- // TEST[continued] [source,console-result] --------------------------------------------------- +---- { "acknowledged": true } --------------------------------------------------- - -////////////////////////// +---- +//// diff --git a/docs/reference/ingest/apis/put-pipeline.asciidoc b/docs/reference/ingest/apis/put-pipeline.asciidoc index fe7b388b9ab6c..fd42b3c97c8aa 100644 --- a/docs/reference/ingest/apis/put-pipeline.asciidoc +++ b/docs/reference/ingest/apis/put-pipeline.asciidoc @@ -19,6 +19,51 @@ PUT _ingest/pipeline/my-pipeline-id } -------------------------------------------------- +[float] +[[versioning-pipelines]] +==== Pipeline versioning + +Pipelines can optionally add a `version` number, which can be any integer value, +in order to simplify pipeline management by external systems. The `version` +field is completely optional and it is meant solely for external management of +pipelines. + +[source,console] +-------------------------------------------------- +PUT /_ingest/pipeline/my-pipeline-id +{ + "description" : "describe pipeline", + "version" : 123, + "processors" : [ + { + "set" : { + "field": "foo", + "value": "bar" + } + } + ] +} +-------------------------------------------------- + +To unset a `version`, simply replace the pipeline without specifying +one. + +[source,console] +-------------------------------------------------- +PUT /_ingest/pipeline/my-pipeline-id +{ + "description" : "describe pipeline", + "processors" : [ + { + "set" : { + "field": "foo", + "value": "bar" + } + } + ] +} +-------------------------------------------------- + ////////////////////////// [source,console] diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 91ea92de02609..074881be2931a 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -378,6 +378,12 @@ tag::pipeline[] (Optional, string) ID of the pipeline to use to preprocess incoming documents. end::pipeline[] +tag::path-pipeline[] +``:: +(Optional, string) Comma-separated list or wildcard expression of pipeline IDs +used to limit the request. +end::path-pipeline[] + tag::preference[] `preference`:: (Optional, string) Specifies the node or shard the operation should be From d39b014073f60eeb60ac02f0d25fd9b7b28d7fe3 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 25 Sep 2019 15:39:35 -0400 Subject: [PATCH 2/2] iter --- docs/reference/ingest/apis/get-pipeline.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/ingest/apis/get-pipeline.asciidoc b/docs/reference/ingest/apis/get-pipeline.asciidoc index 70cb6a4c91d39..b046b7886683a 100644 --- a/docs/reference/ingest/apis/get-pipeline.asciidoc +++ b/docs/reference/ingest/apis/get-pipeline.asciidoc @@ -92,7 +92,7 @@ The API returns the following response: [[get-pipeline-api-version-ex]] ===== Get the version of an ingest pipeline -When creating an ingest pipeline, +When you create or update an ingest pipeline, you can specify an optional `version` parameter. The version is useful for managing changes to pipeline and viewing the current pipeline for an ingest node.