Module: Elasticsearch::API::Watcher::Actions

Defined in:
lib/elasticsearch/api/actions/watcher/stop.rb,
lib/elasticsearch/api/actions/watcher/start.rb,
lib/elasticsearch/api/actions/watcher/stats.rb,
lib/elasticsearch/api/actions/watcher/ack_watch.rb,
lib/elasticsearch/api/actions/watcher/get_watch.rb,
lib/elasticsearch/api/actions/watcher/put_watch.rb,
lib/elasticsearch/api/actions/watcher/delete_watch.rb,
lib/elasticsearch/api/actions/watcher/get_settings.rb,
lib/elasticsearch/api/actions/watcher/execute_watch.rb,
lib/elasticsearch/api/actions/watcher/query_watches.rb,
lib/elasticsearch/api/actions/watcher/activate_watch.rb,
lib/elasticsearch/api/actions/watcher/update_settings.rb,
lib/elasticsearch/api/actions/watcher/deactivate_watch.rb

Instance Method Summary collapse

Instance Method Details

#ack_watch(arguments = {}) ⇒ Object

Acknowledge a watch. Acknowledging a watch enables you to manually throttle the execution of the watch’s actions. The acknowledgement state of an action 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 behavior is to prevent overwriting the watch status from a watch execution. 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).

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :watch_id (String) —

    The watch identifier. (Required)

  • :action_id (String, Array<String>) —

    A comma-separated list of the action identifiers to acknowledge. If you omit this parameter, all of the actions of the watch are acknowledged.

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/elasticsearch/api/actions/watcher/ack_watch.rb', line 40

def ack_watch(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.ack_watch' }

  defined_params = [:watch_id, :action_id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'watch_id' missing" unless arguments[:watch_id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _watch_id = arguments.delete(:watch_id)

  _action_id = arguments.delete(:action_id)

  method = Elasticsearch::API::HTTP_PUT
  path   = if _watch_id && _action_id
             "_watcher/watch/#{Utils.listify(_watch_id)}/_ack/#{Utils.listify(_action_id)}"
           else
             "_watcher/watch/#{Utils.listify(_watch_id)}/_ack"
           end
  params = {}

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#activate_watch(arguments = {}) ⇒ Object

Activate a watch. A watch can be either active or inactive.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :watch_id (String) —

    The watch identifier. (Required)

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/elasticsearch/api/actions/watcher/activate_watch.rb', line 33

def activate_watch(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.activate_watch' }

  defined_params = [:watch_id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'watch_id' missing" unless arguments[:watch_id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _watch_id = arguments.delete(:watch_id)

  method = Elasticsearch::API::HTTP_PUT
  path   = "_watcher/watch/#{Utils.listify(_watch_id)}/_activate"
  params = {}

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#deactivate_watch(arguments = {}) ⇒ Object

Deactivate a watch. A watch can be either active or inactive.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :watch_id (String) —

    The watch identifier. (Required)

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/elasticsearch/api/actions/watcher/deactivate_watch.rb', line 33

def deactivate_watch(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.deactivate_watch' }

  defined_params = [:watch_id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'watch_id' missing" unless arguments[:watch_id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _watch_id = arguments.delete(:watch_id)

  method = Elasticsearch::API::HTTP_PUT
  path   = "_watcher/watch/#{Utils.listify(_watch_id)}/_deactivate"
  params = {}

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#delete_watch(arguments = {}) ⇒ Object

Delete a watch. When the watch is removed, the document representing the watch in the .watches index is gone and it will never be run again. Deleting a watch does not delete any watch execution records related to this watch from the watch history. IMPORTANT: Deleting a watch must be done by using only this API. Do not delete the watch directly from the .watches index using the Elasticsearch delete document API When Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the .watches index.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The watch identifier. (Required)

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/elasticsearch/api/actions/watcher/delete_watch.rb', line 37

def delete_watch(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.delete_watch' }

  defined_params = [:id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _id = arguments.delete(:id)

  method = Elasticsearch::API::HTTP_DELETE
  path   = "_watcher/watch/#{Utils.listify(_id)}"
  params = Utils.process_params(arguments)

  if Array(arguments[:ignore]).include?(404)
    Utils.rescue_from_not_found do
      Elasticsearch::API::Response.new(
        perform_request(method, path, params, body, headers, request_opts)
      )
    end
  else
    Elasticsearch::API::Response.new(
      perform_request(method, path, params, body, headers, request_opts)
    )
  end
end

#execute_watch(arguments = {}) ⇒ Object

Run a watch. This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes. For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running 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 it runs. You can use the run watch API to run 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. When Elasticsearch security features are enabled on your cluster, watches are run 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 run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The watch identifier.

  • :debug (Boolean) —

    Defines whether the watch runs in debug mode.

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

See Also:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/elasticsearch/api/actions/watcher/execute_watch.rb', line 43

def execute_watch(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.execute_watch' }

  defined_params = [:id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  _id = arguments.delete(:id)

  method = Elasticsearch::API::HTTP_PUT
  path   = if _id
             "_watcher/watch/#{Utils.listify(_id)}/_execute"
           else
             '_watcher/watch/_execute'
           end
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#get_settings(arguments = {}) ⇒ Object

Get Watcher index settings. Get settings for the Watcher internal index (.watches). Only a subset of settings are shown, for example index.auto_expand_replicas and index.number_of_replicas.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :master_timeout (Time) —

    The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • :headers (Hash) —

    Custom HTTP headers

See Also:



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/elasticsearch/api/actions/watcher/get_settings.rb', line 35

def get_settings(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.get_settings' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  method = Elasticsearch::API::HTTP_GET
  path   = '_watcher/settings'
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#get_watch(arguments = {}) ⇒ Object

Get a watch.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The watch identifier. (Required)

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/elasticsearch/api/actions/watcher/get_watch.rb', line 32

def get_watch(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.get_watch' }

  defined_params = [:id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _id = arguments.delete(:id)

  method = Elasticsearch::API::HTTP_GET
  path   = "_watcher/watch/#{Utils.listify(_id)}"
  params = {}

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#put_watch(arguments = {}) ⇒ Object

Create or update a watch. When a watch is registered, a new document that represents the watch is added to the .watches index and its trigger is immediately registered with the relevant trigger engine. Typically for the schedule trigger, the scheduler is the trigger engine. IMPORTANT: You must use Kibana or this API to create a watch. Do not add a watch directly to the .watches index by using the Elasticsearch index API. If Elasticsearch security features are enabled, do not give users write privileges on the .watches index. When you add a watch you can also define its initial active state by setting the active parameter. When Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges. If the user is able to read index a, but not index b, the same will apply when the watch runs.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The identifier for the watch. (Required)

  • :active (Boolean) —

    The initial state of the watch. The default value is true, which means the watch is active by default. Server default: true.

  • :if_primary_term (Integer) —

    only update the watch if the last operation that has changed the watch has the specified primary term

  • :if_seq_no (Integer) —

    only update the watch if the last operation that has changed the watch has the specified sequence number

  • :version (Integer) —

    Explicit version number for concurrency control

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/elasticsearch/api/actions/watcher/put_watch.rb', line 46

def put_watch(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.put_watch' }

  defined_params = [:id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  _id = arguments.delete(:id)

  method = Elasticsearch::API::HTTP_PUT
  path   = "_watcher/watch/#{Utils.listify(_id)}"
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#query_watches(arguments = {}) ⇒ Object

Query watches. Get all registered watches in a paginated manner and optionally filter watches by a query. Note that only the _id and metadata.* fields are queryable or sortable.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

See Also:



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/elasticsearch/api/actions/watcher/query_watches.rb', line 34

def query_watches(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.query_watches' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  method = if body
             Elasticsearch::API::HTTP_POST
           else
             Elasticsearch::API::HTTP_GET
           end

  path   = '_watcher/_query/watches'
  params = {}

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#start(arguments = {}) ⇒ Object

Start the watch service. Start the Watcher service if it is not already running.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :master_timeout (Time) —

    Period to wait for a connection to the master node. Server default: 30s.

  • :headers (Hash) —

    Custom HTTP headers

See Also:



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/elasticsearch/api/actions/watcher/start.rb', line 33

def start(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.start' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  method = Elasticsearch::API::HTTP_POST
  path   = '_watcher/_start'
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#stats(arguments = {}) ⇒ Object

Get Watcher statistics. This API always returns basic metrics. You retrieve more metrics by using the metric parameter.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :metric (Watchermetric) —

    Defines which additional metrics are included in the response.

  • :emit_stacktraces (Boolean) —

    Defines whether stack traces are generated for each watch that is running.

  • :headers (Hash) —

    Custom HTTP headers

See Also:



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/elasticsearch/api/actions/watcher/stats.rb', line 35

def stats(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.stats' }

  defined_params = [:metric].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _metric = arguments.delete(:metric)

  method = Elasticsearch::API::HTTP_GET
  path   = if _metric
             "_watcher/stats/#{Utils.listify(_metric)}"
           else
             '_watcher/stats'
           end
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#stop(arguments = {}) ⇒ Object

Stop the watch service. Stop the Watcher service if it is running.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :master_timeout (Time) —

    The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1. Server default: 30s.

  • :headers (Hash) —

    Custom HTTP headers

See Also:



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/elasticsearch/api/actions/watcher/stop.rb', line 35

def stop(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.stop' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  method = Elasticsearch::API::HTTP_POST
  path   = '_watcher/_stop'
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#update_settings(arguments = {}) ⇒ Object

Update Watcher index settings. Update settings for the Watcher internal index (.watches). Only a subset of settings can be modified. This includes index.auto_expand_replicas, index.number_of_replicas, index.routing.allocation.exclude.*, index.routing.allocation.include.* and index.routing.allocation.require.*. Modification of index.routing.allocation.include._tier_preference is an exception and is not allowed as the Watcher shards must always be in the data_content tier.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :master_timeout (Time) —

    The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • :timeout (Time) —

    The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/elasticsearch/api/actions/watcher/update_settings.rb', line 42

def update_settings(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'watcher.update_settings' }

  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  method = Elasticsearch::API::HTTP_PUT
  path   = '_watcher/settings'
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end