388 lines
13 KiB
Plaintext
388 lines
13 KiB
Plaintext
[role="xpack"]
|
|
[[watcher-api-execute-watch]]
|
|
=== Execute Watch API
|
|
|
|
The execute watch API forces the execution of a stored watch. It can be used to
|
|
force execution of the watch outside of its triggering logic, or to simulate the
|
|
watch execution for debugging purposes.
|
|
|
|
[float]
|
|
==== Request
|
|
|
|
`POST _xpack/watcher/watch/<watch_id>/_execute` +
|
|
|
|
`POST _xpack/watcher/watch/_execute`
|
|
|
|
[float]
|
|
==== Description
|
|
|
|
For testing and debugging purposes, you also have fine-grained control on how
|
|
the watch runs. You can execute the watch without executing all of its actions
|
|
or alternatively by simulating them. You can also force execution by ignoring
|
|
the watch condition and control whether a watch record would be written to the
|
|
watch history after execution.
|
|
|
|
[float]
|
|
[[watcher-api-execute-inline-watch]]
|
|
===== Inline Watch Execution
|
|
|
|
You can use the Execute API to execute watches that are not yet registered by
|
|
specifying the watch definition inline. This serves as great tool for testing
|
|
and debugging your watches prior to adding them to {watcher}.
|
|
|
|
[float]
|
|
==== Path Parameters
|
|
|
|
`watch_id`::
|
|
(string) Identifier for the watch.
|
|
|
|
[float]
|
|
==== Query Parameters
|
|
|
|
`debug`::
|
|
(boolean) Defines whether the watch runs in debug mode. The default value is
|
|
`false`.
|
|
|
|
[float]
|
|
==== Request Body
|
|
|
|
This API supports the following fields:
|
|
|
|
[cols=",^,^,", options="header"]
|
|
|======
|
|
| Name | Required | Default | Description
|
|
|
|
| `trigger_data` | no | | This structure is parsed as the data of the trigger event
|
|
that will be used during the watch execution
|
|
|
|
| `ignore_condition` | no | false | When set to `true`, the watch execution uses the
|
|
{xpack-ref}/condition-always.html[Always Condition].
|
|
This can also be specified as a HTTP parameter.
|
|
|
|
| `alternative_input` | no | null | When present, the watch uses this object as a payload
|
|
instead of executing its own input.
|
|
|
|
| `action_modes` | no | null | Determines how to handle the watch actions as part of the
|
|
watch execution. See <<watcher-api-execute-watch-action-mode, Action Execution Modes>>
|
|
for more information.
|
|
|
|
| `record_execution` | no | false | When set to `true`, the watch record representing the watch
|
|
execution result is persisted to the `.watcher-history`
|
|
index for the current time. In addition, the status of the
|
|
watch is updated, possibly throttling subsequent executions.
|
|
This can also be specified as a HTTP parameter.
|
|
|
|
| `watch` | no | null | When present, this
|
|
{xpack-ref}/how-watcher-works.html#watch-definition[watch] is used
|
|
instead of the one specified in the request. This watch is
|
|
not persisted to the index and record_execution cannot be set.
|
|
|======
|
|
|
|
[float]
|
|
[[watcher-api-execute-watch-action-mode]]
|
|
===== Action Execution Modes
|
|
|
|
Action modes define how actions are handled during the watch execution. There
|
|
are five possible modes an action can be associated with:
|
|
|
|
[options="header"]
|
|
|======
|
|
| Name | Description
|
|
|
|
| `simulate` | The action execution is simulated. Each action type
|
|
define its own simulation operation mode. For example, the
|
|
{xpack-ref}/actions-email.html[email] action creates
|
|
the email that would have been sent but does not actually
|
|
send it. In this mode, the action might be throttled if the
|
|
current state of the watch indicates it should be.
|
|
|
|
| `force_simulate` | Similar to the the `simulate` mode, except the action is
|
|
not be throttled even if the current state of the watch
|
|
indicates it should be.
|
|
|
|
| `execute` | Executes the action as it would have been executed if the
|
|
watch would have been triggered by its own trigger. The
|
|
execution might be throttled if the current state of the
|
|
watch indicates it should be.
|
|
|
|
| `force_execute` | Similar to the `execute` mode, except the action is not
|
|
throttled even if the current state of the watch indicates
|
|
it should be.
|
|
|
|
| `skip` | The action is skipped and is not executed or simulated.
|
|
Effectively forces the action to be throttled.
|
|
|======
|
|
|
|
[float]
|
|
==== Authorization
|
|
You must have `manage_watcher` cluster privileges to use this API. For more
|
|
information, see {xpack-ref}/security-privileges.html[Security Privileges].
|
|
|
|
[float]
|
|
==== Security Integration
|
|
|
|
When {security} is enabled on your Elasticsearch cluster, then watches will be
|
|
executed with the privileges of the user that stored the watches. If your user
|
|
is allowed to read index `a`, but not index `b`, then the exact same set of
|
|
rules will apply during execution of a watch.
|
|
|
|
When using the execute watch API, the authorization data of the user that
|
|
called the API will be used as a base, instead of of the information who stored
|
|
the watch.
|
|
|
|
[float]
|
|
==== Examples
|
|
|
|
The following example executes the `my_watch` watch:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
|
|
The following example shows a comprehensive example of executing the `my-watch` watch:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
{
|
|
"trigger_data" : { <1>
|
|
"triggered_time" : "now",
|
|
"scheduled_time" : "now"
|
|
},
|
|
"alternative_input" : { <2>
|
|
"foo" : "bar"
|
|
},
|
|
"ignore_condition" : true, <3>
|
|
"action_modes" : {
|
|
"my-action" : "force_simulate" <4>
|
|
},
|
|
"record_execution" : true <5>
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
<1> The triggered and schedule times are provided.
|
|
<2> The input as defined by the watch is ignored and instead the provided input
|
|
is used as the execution payload.
|
|
<3> The condition as defined by the watch is ignored and is assumed to
|
|
evaluate to `true`.
|
|
<4> Forces the simulation of `my-action`. Forcing the simulation means that
|
|
throttling is ignored and the watch is simulated by {watcher} instead of
|
|
being executed normally.
|
|
<5> The execution of the watch creates a watch record in the watch history,
|
|
and the throttling state of the watch is potentially updated accordingly.
|
|
|
|
This is an example of the output:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"_id": "my_watch_0-2015-06-02T23:17:55.124Z", <1>
|
|
"watch_record": { <2>
|
|
"watch_id": "my_watch",
|
|
"node": "my_node",
|
|
"messages": [],
|
|
"trigger_event": {
|
|
"type": "manual",
|
|
"triggered_time": "2015-06-02T23:17:55.124Z",
|
|
"manual": {
|
|
"schedule": {
|
|
"scheduled_time": "2015-06-02T23:17:55.124Z"
|
|
}
|
|
}
|
|
},
|
|
"state": "executed",
|
|
"status": {
|
|
"version": 1,
|
|
"execution_state": "executed",
|
|
"state": {
|
|
"active": true,
|
|
"timestamp": "2015-06-02T23:17:55.111Z"
|
|
},
|
|
"last_checked": "2015-06-02T23:17:55.124Z",
|
|
"last_met_condition": "2015-06-02T23:17:55.124Z",
|
|
"actions": {
|
|
"test_index": {
|
|
"ack": {
|
|
"timestamp": "2015-06-02T23:17:55.124Z",
|
|
"state": "ackable"
|
|
},
|
|
"last_execution": {
|
|
"timestamp": "2015-06-02T23:17:55.124Z",
|
|
"successful": true
|
|
},
|
|
"last_successful_execution": {
|
|
"timestamp": "2015-06-02T23:17:55.124Z",
|
|
"successful": true
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"input": {
|
|
"simple": {
|
|
"payload": {
|
|
"send": "yes"
|
|
}
|
|
}
|
|
},
|
|
"condition": {
|
|
"always": {}
|
|
},
|
|
"result": { <3>
|
|
"execution_time": "2015-06-02T23:17:55.124Z",
|
|
"execution_duration": 12608,
|
|
"input": {
|
|
"type": "simple",
|
|
"payload": {
|
|
"foo": "bar"
|
|
},
|
|
"status": "success"
|
|
},
|
|
"condition": {
|
|
"type": "always",
|
|
"met": true,
|
|
"status": "success"
|
|
},
|
|
"actions": [
|
|
{
|
|
"id": "test_index",
|
|
"index": {
|
|
"response": {
|
|
"index": "test",
|
|
"type": "test2",
|
|
"version": 1,
|
|
"created": true,
|
|
"result": "created",
|
|
"id": "AVSHKzPa9zx62AzUzFXY"
|
|
}
|
|
},
|
|
"status": "success",
|
|
"type": "index"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/my_watch_0-2015-06-02T23:17:55.124Z/$body._id/]
|
|
// TESTRESPONSE[s/"triggered_time": "2015-06-02T23:17:55.124Z"/"triggered_time": "$body.watch_record.trigger_event.triggered_time"/]
|
|
// TESTRESPONSE[s/"scheduled_time": "2015-06-02T23:17:55.124Z"/"scheduled_time": "$body.watch_record.trigger_event.manual.schedule.scheduled_time"/]
|
|
// TESTRESPONSE[s/"execution_time": "2015-06-02T23:17:55.124Z"/"execution_time": "$body.watch_record.result.execution_time"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.111Z"/"timestamp": "$body.watch_record.status.state.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.124Z"/"timestamp": "$body.watch_record.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"last_checked": "2015-06-02T23:17:55.124Z"/"last_checked": "$body.watch_record.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": "2015-06-02T23:17:55.124Z"/"last_met_condition": "$body.watch_record.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"execution_duration": 12608/"execution_duration": "$body.watch_record.result.execution_duration"/]
|
|
// TESTRESPONSE[s/"id": "AVSHKzPa9zx62AzUzFXY"/"id": "$body.watch_record.result.actions.0.index.response.id"/]
|
|
// TESTRESPONSE[s/"node": "my_node"/"node": "$body.watch_record.node"/]
|
|
<1> The id of the watch record as it would be stored in the `.watcher-history` index.
|
|
<2> The watch record document as it would be stored in the `.watcher-history` index.
|
|
<3> The watch execution results.
|
|
|
|
You can set a different execution mode for every action by associating the mode
|
|
name with the action id:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
{
|
|
"action_modes" : {
|
|
"action1" : "force_simulate",
|
|
"action2" : "skip"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
|
|
You can also associate a single execution mode with all the actions in the watch
|
|
using `_all` as the action id:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/my_watch/_execute
|
|
{
|
|
"action_modes" : {
|
|
"_all" : "force_execute"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:my_active_watch]
|
|
|
|
The following example shows how to execute a watch inline:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/_execute
|
|
{
|
|
"watch" : {
|
|
"trigger" : { "schedule" : { "interval" : "10s" } },
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"body" : {
|
|
"query" : {
|
|
"match" : { "message": "error" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"condition" : {
|
|
"compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
|
|
},
|
|
"actions" : {
|
|
"log_error" : {
|
|
"logging" : {
|
|
"text" : "Found {{ctx.payload.hits.total}} errors in the logs"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
All other settings for this API still apply when inlining a watch. In the
|
|
following snippet, while the inline watch defines a `compare` condition,
|
|
during the execution this condition will be ignored:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST _xpack/watcher/watch/_execute
|
|
{
|
|
"ignore_condition" : true,
|
|
"watch" : {
|
|
"trigger" : { "schedule" : { "interval" : "10s" } },
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"body" : {
|
|
"query" : {
|
|
"match" : { "message": "error" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"condition" : {
|
|
"compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
|
|
},
|
|
"actions" : {
|
|
"log_error" : {
|
|
"logging" : {
|
|
"text" : "Found {{ctx.payload.hits.total}} errors in the logs"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|