Browse Source

[DOCS] Document missing script APIs (#72175)

Documents the following APIs:

* [Delete stored script][0]
* [Get stored script][1]
* [Get script contexts][2]
* [Get script languages][3]

[0]: https://github.com/elastic/elasticsearch/blob/master/rest-api-spec/src/main/resources/rest-api-spec/api/delete_script.json
[1]: https://github.com/elastic/elasticsearch/blob/master/rest-api-spec/src/main/resources/rest-api-spec/api/get_script.json
[2]: https://github.com/elastic/elasticsearch/blob/master/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_context.json
[3]: https://github.com/elastic/elasticsearch/blob/master/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_languages.json
James Rodewig 4 years ago
parent
commit
0edb8f4708

+ 48 - 0
docs/reference/scripting/apis/delete-stored-script-api.asciidoc

@@ -0,0 +1,48 @@
+[[delete-stored-script-api]]
+=== Delete stored script API
+++++
+<titleabbrev>Delete stored script</titleabbrev>
+++++
+
+Deletes a <<script-stored-scripts,stored script>> or <<search-template,search
+template>>.
+
+////
+[source,console]
+----
+PUT _scripts/my-stored-script
+{
+  "script": {
+    "lang": "painless",
+    "source": """
+      TimestampHour date =  doc['@timestamp'].value; 
+      return date.getHour()
+    """
+  }
+}
+----
+////
+
+[source,console]
+----
+DELETE _scripts/my-stored-script
+----
+// TEST[continued]
+
+[[delete-stored-script-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-cluster,cluster privilege>> to use this API.
+
+[[delete-stored-script-api-path-params]]
+==== {api-path-parms-title}
+
+`<script-id>`::
+(Required, string)
+Identifier for the stored script or search template.
+
+[[delete-stored-script-api-query-params]]
+==== {api-query-parms-title}
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

+ 23 - 0
docs/reference/scripting/apis/get-script-contexts-api.asciidoc

@@ -0,0 +1,23 @@
+[[get-script-contexts-api]]
+=== Get script contexts API
+++++
+<titleabbrev>Get script contexts</titleabbrev>
+++++
+
+Retrieves a list of supported script contexts and their methods.
+
+[source,console]
+----
+GET _script_context
+----
+
+[[get-script-contexts-api-request]]
+==== {api-request-title}
+
+`GET _script_context`
+
+[[get-script-contexts-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-cluster,cluster privilege>> to use this API.

+ 24 - 0
docs/reference/scripting/apis/get-script-languages-api.asciidoc

@@ -0,0 +1,24 @@
+[[get-script-languages-api]]
+=== Get script languages API
+++++
+<titleabbrev>Get script languages</titleabbrev>
+++++
+
+Retrieves a list of supported <<scripting-available-languages,script languages>>
+and their contexts.
+
+[source,console]
+----
+GET _script_language
+----
+
+[[get-script-languages-api-request]]
+==== {api-request-title}
+
+`GET _script_language`
+
+[[get-script-languages-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-cluster,cluster privilege>> to use this API.

+ 53 - 0
docs/reference/scripting/apis/get-stored-script-api.asciidoc

@@ -0,0 +1,53 @@
+[[get-stored-script-api]]
+=== Get stored script API
+++++
+<titleabbrev>Get stored script</titleabbrev>
+++++
+
+Retrieves a <<script-stored-scripts,stored script>> or <<search-template,search
+template>>.
+
+////
+[source,console]
+----
+PUT _scripts/my-stored-script
+{
+  "script": {
+    "lang": "painless",
+    "source": """
+      TimestampHour date =  doc['@timestamp'].value; 
+      return date.getHour()
+    """
+  }
+}
+----
+////
+
+[source,console]
+----
+GET _scripts/my-stored-script
+----
+// TEST[continued]
+
+[[get-stored-script-api-request]]
+==== {api-request-title}
+
+`GET _script/<script-id>`
+
+[[get-stored-script-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-cluster,cluster privilege>> to use this API.
+
+[[get-stored-script-api-path-params]]
+==== {api-path-parms-title}
+
+`<script-id>`::
+(Required, string)
+Identifier for the stored script or search template.
+
+[[get-stored-script-api-query-params]]
+==== {api-query-parms-title}
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]

+ 21 - 16
docs/reference/scripting/apis/script-apis.asciidoc

@@ -1,35 +1,40 @@
 [[script-apis]]
 == Script APIs
 
-NOTE: This list of script APIs is incomplete. We're working on adding more.
-
-Use following APIs to manage, store, and test your
+Use the following APIs to manage, store, and test your
 <<modules-scripting,scripts>>.
 
+[discrete]
+[[script-support-apis]]
+=== Script support APIs
+
+Use the script support APIs to get a list of supported script contexts and
+languages.
+
+* <<get-script-contexts-api>>
+* <<get-script-languages-api>>
+
 [discrete]
 [[stored-script-apis]]
 === Stored script APIs
 
-Use stored script APIs to manage <<script-stored-scripts,stored scripts>> and
+Use the stored script APIs to manage <<script-stored-scripts,stored scripts>> and
 <<search-template,search templates>>.
 
 * <<create-stored-script-api>>
-
-////
-TODO: See https://github.com/elastic/elasticsearch/issues/71376
-
-[discrete]
-[[script-support-apis]]
-=== Script support API
-
-Use the script support APIs to get a list of supported script languages and
-contexts.
+* <<get-stored-script-api>>
+* <<delete-stored-script-api>>
 
 [discrete]
 [[painless-apis]]
 === Painless APIs
 
-Use the execute script API to safely test Painless scripts.
-////
+Use the {painless}/painless-execute-api.html[Painless execute API] to safely
+test Painless scripts before using them in production.
+
 
 include::create-stored-script-api.asciidoc[]
+include::delete-stored-script-api.asciidoc[]
+include::get-script-contexts-api.asciidoc[]
+include::get-script-languages-api.asciidoc[]
+include::get-stored-script-api.asciidoc[]

+ 5 - 5
docs/reference/search/search-template.asciidoc

@@ -151,7 +151,8 @@ created:
 //////////////////////////
 
 
-The template can be retrieved by calling
+To retrieve the template, use the <<get-stored-script-api,get stored script
+API>>.
 
 [source,console]
 ------------------------------------------
@@ -159,7 +160,7 @@ GET _scripts/<templateid>
 ------------------------------------------
 // TEST[continued]
 
-The API returns the following result:
+The API returns:
 
 [source,console-result]
 ------------------------------------------
@@ -176,8 +177,8 @@ The API returns the following result:
 }
 ------------------------------------------
 
-
-This template can be deleted by calling
+To delete the template, use the <<delete-stored-script-api,delete stored script
+API>>.
 
 [source,console]
 ------------------------------------------
@@ -185,7 +186,6 @@ DELETE _scripts/<templateid>
 ------------------------------------------
 // TEST[continued]
 
-
 [[use-registered-templates]]
 ===== Using a stored search template