execute-watch.asciidoc 3.3 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788
  1. --
  2. :api: execute-watch
  3. :request: ExecuteWatchRequest
  4. :response: ExecuteWatchResponse
  5. --
  6. [id="{upid}-{api}"]
  7. === Execute Watch API
  8. The execute watch API allows clients to immediately execute a watch, either
  9. one that has been previously added via the
  10. {ref}/watcher-api-put-watch.html[Put Watch API] or inline as part of the request.
  11. [id="{upid}-{api}-request-by-id"]
  12. ==== Execute by id
  13. Submit the following request to execute a previously added watch:
  14. ["source","java",subs="attributes,callouts,macros"]
  15. ---------------------------------------------------
  16. include-tagged::{doc-tests-file}[x-pack-execute-watch-by-id]
  17. ---------------------------------------------------
  18. <1> Alternative input for the watch to use in json format
  19. <2> Set the mode for action "action1" to SIMULATE
  20. <3> Record this execution in watcher history
  21. <4> Execute the watch regardless of the watch's condition
  22. <5> Set the trigger data for the watch in json format
  23. <6> Enable debug mode
  24. [id="{upid}-{api}-response-by-id"]
  25. ==== Execute by id Response
  26. The returned `Response` contains details of the execution:
  27. ["source","java",subs="attributes,callouts,macros"]
  28. ---------------------------------------------------
  29. include-tagged::{doc-tests-file}[x-pack-execute-watch-by-id-response]
  30. ---------------------------------------------------
  31. <1> The record ID for this execution
  32. <2> The execution response as a java `Map`
  33. <3> Extract information from the response map using `ObjectPath`
  34. [id="{upid}-{api}-response-by-id-async"]
  35. ==== Asynchronous execution by id
  36. This request can be executed asynchronously:
  37. ["source","java",subs="attributes,callouts,macros"]
  38. --------------------------------------------------
  39. include-tagged::{doc-tests-file}[x-pack-execute-watch-by-id-execute-async]
  40. --------------------------------------------------
  41. <1> The `ExecuteWatchRequest` to execute and the `ActionListener` to use when
  42. the execution completes
  43. The asynchronous method does not block and returns immediately. Once it is
  44. completed the `ActionListener` is called back using the `onResponse` method
  45. if the execution successfully completed or using the `onFailure` method if
  46. it failed.
  47. A typical listener for `ExecuteWatchResponse` looks like:
  48. ["source","java",subs="attributes,callouts,macros"]
  49. --------------------------------------------------
  50. include-tagged::{doc-tests-file}[x-pack-execute-watch-by-id-execute-listener]
  51. --------------------------------------------------
  52. <1> Called when the execution is successfully completed. The response is
  53. provided as an argument
  54. <2> Called in case of failure. The raised exception is provided as an argument
  55. [id="{upid}-{api}-request-inline"]
  56. ==== Execute inline
  57. Submit the following request to execute a watch defined as part of the request:
  58. ["source","java",subs="attributes,callouts,macros"]
  59. ---------------------------------------------------
  60. include-tagged::{doc-tests-file}[x-pack-execute-watch-inline]
  61. ---------------------------------------------------
  62. <1> Alternative input for the watch to use in json format
  63. <2> Set the mode for action "action1" to SIMULATE
  64. <3> Execute the watch regardless of the watch's condition
  65. <4> Set the trigger data for the watch in json format
  66. <5> Enable debug mode
  67. Note that inline watches cannot be recorded.
  68. The response format and asynchronous execution methods are the same as for the
  69. Execute Watch by ID API.