Ack watch API
editAck watch API
editAcknowledging a watch enables you
to manually throttle execution of the watch’s actions. An action’s
acknowledgement state is stored in the status.actions.<id>.ack.state
structure.
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.
Request
editPUT _watcher/watch/<watch_id>/_ack
PUT _watcher/watch/<watch_id>/_ack/<action_id>
Path Parameters
edit-
action_id
- (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.
Authorization
editYou must have manage_watcher
cluster privileges to use this API. For more
information, see Security privileges.
Examples
editTo demonstrate let’s create a new watch:
PUT _watcher/watch/my_watch { "trigger": { "schedule": { "hourly": { "minute": [ 0, 5 ] } } }, "input": { "simple": { "payload": { "send": "yes" } } }, "condition": { "always": {} }, "actions": { "test_index": { "throttle_period": "15m", "index": { "index": "test" } } } }
The current status of a watch and the state of its actions is returned with the watch definition when you call the Get Watch API:
GET _watcher/watch/my_watch
The action state of a newly-created watch is awaits_successful_execution
:
{ "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": ... }
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:
POST _watcher/watch/my_watch/_execute { "record_execution" : true } GET _watcher/watch/my_watch
and the action is now in ackable
state:
{ "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": ... }
Now we can acknowledge it:
PUT _watcher/watch/my_watch/_ack/test_index GET _watcher/watch/my_watch
{ "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": ... }
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:
POST _watcher/watch/my_watch/_ack/action1,action2
To acknowledge all of the actions of a watch, simply omit the actions
parameter:
POST _watcher/watch/my_watch/_ack
The response looks like a get watch response, but only contains the status:
{ "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 } }