299 lines
8.9 KiB
Plaintext
299 lines
8.9 KiB
Plaintext
[role="xpack"]
|
|
[[watcher-api-ack-watch]]
|
|
=== Ack watch API
|
|
++++
|
|
<titleabbrev>Ack watch</titleabbrev>
|
|
++++
|
|
|
|
<<actions-ack-throttle,Acknowledging a watch>> enables you
|
|
to manually throttle execution of the watch's actions.
|
|
|
|
[[watcher-api-ack-watch-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT _watcher/watch/<watch_id>/_ack` +
|
|
|
|
`PUT _watcher/watch/<watch_id>/_ack/<action_id>`
|
|
|
|
[[watcher-api-ack-watch-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* You must have `manage_watcher` cluster privileges to use this API. For more
|
|
information, see <<security-privileges>>.
|
|
|
|
[[watcher-api-ack-watch-desc]]
|
|
==== {api-description-title}
|
|
|
|
An action's _acknowledgement state_ is stored in the
|
|
`status.actions.<id>.ack.state` structure.
|
|
|
|
IMPORTANT: If the specified watch is currently being executed, this API will
|
|
return an error. The reason for this is to prevent overwriting of the watch
|
|
status from a watch execution.
|
|
|
|
[[watcher-api-ack-watch-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<action_id>`::
|
|
(Optional, list) A comma-separated list of the action IDs to acknowledge. If you omit
|
|
this parameter, all of the actions of the watch are acknowledged.
|
|
|
|
`<watch_id>`::
|
|
(Required, string) Identifier for the watch.
|
|
|
|
//[[watcher-api-ack-watch-query-params]]
|
|
//==== {api-query-parms-title}
|
|
|
|
//[[watcher-api-ack-watch-request-body]]
|
|
//==== {api-request-body-title}
|
|
|
|
//[[watcher-api-ack-watch-response-body]]
|
|
//==== {api-response-body-title}
|
|
|
|
//[[watcher-api-ack-watch-response-codes]]
|
|
//==== {api-response-codes-title}
|
|
|
|
[[watcher-api-ack-watch-example]]
|
|
==== {api-examples-title}
|
|
|
|
To demonstrate let's create a new watch:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my_watch
|
|
{
|
|
"trigger" : {
|
|
"schedule" : {
|
|
"yearly" : { "in" : "february", "on" : 29, "at" : "noon" }
|
|
}
|
|
},
|
|
"input": {
|
|
"simple": {
|
|
"payload": {
|
|
"send": "yes"
|
|
}
|
|
}
|
|
},
|
|
"condition": {
|
|
"always": {}
|
|
},
|
|
"actions": {
|
|
"test_index": {
|
|
"throttle_period": "15m",
|
|
"index": {
|
|
"index": "test"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
The current status of a watch and the state of its actions is returned with the
|
|
watch definition when you call the <<watcher-api-get-watch, Get Watch API>>:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _watcher/watch/my_watch
|
|
--------------------------------------------------
|
|
|
|
The action state of a newly-created watch is `awaits_successful_execution`:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"found": true,
|
|
"_seq_no": 0,
|
|
"_primary_term": 1,
|
|
"_version": 1,
|
|
"_id": "my_watch",
|
|
"status": {
|
|
"version": 1,
|
|
"actions": {
|
|
"test_index": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:04:27.723Z",
|
|
"state": "awaits_successful_execution"
|
|
}
|
|
}
|
|
},
|
|
"state": ...
|
|
},
|
|
"watch": ...
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
|
|
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
|
|
When the watch executes and the condition matches, the value of the `ack.state`
|
|
changes to `ackable`. Let's force execution of the watch and fetch it again to
|
|
check the status:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my_watch/_execute
|
|
{
|
|
"record_execution" : true
|
|
}
|
|
|
|
GET _watcher/watch/my_watch
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
and the action is now in `ackable` state:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"found": true,
|
|
"_id": "my_watch",
|
|
"_seq_no": 1,
|
|
"_primary_term": 1,
|
|
"_version": 2,
|
|
"status": {
|
|
"version": 2,
|
|
"actions": {
|
|
"test_index": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:04:27.723Z",
|
|
"state": "ackable"
|
|
},
|
|
"last_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
},
|
|
"last_successful_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
}
|
|
}
|
|
},
|
|
"state": ...,
|
|
"execution_state": "executed",
|
|
"last_checked": ...,
|
|
"last_met_condition": ...
|
|
},
|
|
"watch": ...
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
|
|
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
|
|
// TESTRESPONSE[s/"last_checked": \.\.\./"last_checked": "$body.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": \.\.\./"last_met_condition": "$body.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]
|
|
|
|
Now we can acknowledge it:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _watcher/watch/my_watch/_ack/test_index
|
|
GET _watcher/watch/my_watch
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"found": true,
|
|
"_id": "my_watch",
|
|
"_seq_no": 2,
|
|
"_primary_term": 1,
|
|
"_version": 3,
|
|
"status": {
|
|
"version": 3,
|
|
"actions": {
|
|
"test_index": {
|
|
"ack": {
|
|
"timestamp": "2015-05-26T18:04:27.723Z",
|
|
"state": "acked"
|
|
},
|
|
"last_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
},
|
|
"last_successful_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.723Z",
|
|
"successful": true
|
|
}
|
|
}
|
|
},
|
|
"state": ...,
|
|
"execution_state": "executed",
|
|
"last_checked": ...,
|
|
"last_met_condition": ...
|
|
},
|
|
"watch": ...
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
|
|
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
|
|
// TESTRESPONSE[s/"last_checked": \.\.\./"last_checked": "$body.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": \.\.\./"last_met_condition": "$body.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]
|
|
|
|
Acknowledging an action throttles further executions of that action until its
|
|
`ack.state` is reset to `awaits_successful_execution`. This happens when the
|
|
condition of the watch is not met (the condition evaluates to `false`).
|
|
|
|
You can acknowledge multiple actions by assigning the `actions` parameter a
|
|
comma-separated list of action ids:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my_watch/_ack/action1,action2
|
|
--------------------------------------------------
|
|
|
|
To acknowledge all of the actions of a watch, simply omit the `actions`
|
|
parameter:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _watcher/watch/my_watch/_ack
|
|
--------------------------------------------------
|
|
// TEST[s/^/POST _watcher\/watch\/my_watch\/_execute\n{ "record_execution" : true }\n/]
|
|
|
|
|
|
The response looks like a get watch response, but only contains the status:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"status": {
|
|
"state": {
|
|
"active": true,
|
|
"timestamp": "2015-05-26T18:04:27.723Z"
|
|
},
|
|
"last_checked": "2015-05-26T18:04:27.753Z",
|
|
"last_met_condition": "2015-05-26T18:04:27.763Z",
|
|
"actions": {
|
|
"test_index": {
|
|
"ack" : {
|
|
"timestamp": "2015-05-26T18:04:27.713Z",
|
|
"state": "acked"
|
|
},
|
|
"last_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.733Z",
|
|
"successful": true
|
|
},
|
|
"last_successful_execution" : {
|
|
"timestamp": "2015-05-25T18:04:27.773Z",
|
|
"successful": true
|
|
}
|
|
}
|
|
},
|
|
"execution_state": "executed",
|
|
"version": 2
|
|
}
|
|
}
|
|
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"last_checked": "2015-05-26T18:04:27.753Z"/"last_checked": "$body.status.last_checked"/]
|
|
// TESTRESPONSE[s/"last_met_condition": "2015-05-26T18:04:27.763Z"/"last_met_condition": "$body.status.last_met_condition"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.state.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.713Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.733Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]
|
|
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.773Z"/"timestamp": "$body.status.actions.test_index.last_successful_execution.timestamp"/]
|