mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 18:51:07 -04:00
167 lines
4.8 KiB
Text
167 lines
4.8 KiB
Text
[[find-rules-api]]
|
|
== Find rules API
|
|
++++
|
|
<titleabbrev>Find rules</titleabbrev>
|
|
++++
|
|
|
|
Retrieve a paginated set of rules based on condition.
|
|
|
|
[NOTE]
|
|
====
|
|
For the most up-to-date API details, refer to the
|
|
{kib-repo}/tree/{branch}/x-pack/plugins/alerting/docs/openapi[open API specification]. For a preview, check out <<rule-apis>>.
|
|
====
|
|
|
|
[[find-rules-api-request]]
|
|
=== {api-request-title}
|
|
|
|
`GET <kibana host>:<port>/api/alerting/rules/_find`
|
|
|
|
`GET <kibana host>:<port>/s/<space_id>/api/alerting/rules/_find`
|
|
|
|
=== {api-prereq-title}
|
|
|
|
You must have `read` privileges for the appropriate {kib} features, depending on
|
|
the `consumer` and `rule_type_id` of the rules you're seeking. For example, the
|
|
*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
|
|
features, *{observability}*, and *Security* features. To find rules associated
|
|
with the *{stack-monitor-app}* feature, use the `monitoring_user` built-in role.
|
|
|
|
For more details, refer to <<kibana-feature-privileges>>.
|
|
|
|
=== {api-description-title}
|
|
|
|
As rules change in {kib}, the results on each page of the response also change.
|
|
Use the find API for traditional paginated results, but avoid using it to export
|
|
large amounts of data.
|
|
|
|
NOTE: Rule `params` are stored as a {ref}/flattened.html[flattened field type]
|
|
and analyzed as keywords.
|
|
|
|
[[find-rules-api-path-params]]
|
|
=== {api-path-parms-title}
|
|
|
|
`space_id`::
|
|
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
|
the URL, the default space is used.
|
|
|
|
[[find-rules-api-query-params]]
|
|
=== {api-query-parms-title}
|
|
|
|
`default_search_operator`::
|
|
(Optional, string) The operator to use for the `simple_query_string`. The
|
|
default is 'OR'.
|
|
|
|
`fields`::
|
|
(Optional, array of strings) The fields to return in the `attributes` key of the
|
|
response.
|
|
|
|
`filter`::
|
|
(Optional, string) A <<kuery-query, KQL>> string that you filter with an
|
|
attribute from your saved object. It should look like
|
|
`savedObjectType.attributes.title: "myTitle"`. However, If you used a direct
|
|
attribute of a saved object, such as `updatedAt`, you will have to define your
|
|
filter, for example, `savedObjectType.updatedAt > 2018-12-22`.
|
|
|
|
`has_reference`::
|
|
(Optional, object) Filters the rules that have a relation with the reference
|
|
objects with the specific "type" and "ID".
|
|
|
|
`page`::
|
|
(Optional, number) The page number.
|
|
|
|
`per_page`::
|
|
(Optional, number) The number of rules to return per page.
|
|
|
|
`search`::
|
|
(Optional, string) An {es}
|
|
{ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that
|
|
filters the rules in the response.
|
|
|
|
`search_fields`::
|
|
(Optional, array or string) The fields to perform the `simple_query_string`
|
|
parsed query against.
|
|
|
|
`sort_field`::
|
|
(Optional, string) Sorts the response. Could be a rule field returned in the
|
|
`attributes` key of the response.
|
|
|
|
`sort_order`::
|
|
(Optional, string) Sort direction, either `asc` or `desc`.
|
|
|
|
[[find-rules-api-request-codes]]
|
|
=== {api-response-codes-title}
|
|
|
|
`200`::
|
|
Indicates a successful call.
|
|
|
|
=== {api-examples-title}
|
|
|
|
Find rules with names that start with `my`:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
GET api/alerting/rules/_find?search_fields=name&search=my*
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
The API returns the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{
|
|
"page": 1,
|
|
"total": 1,
|
|
"per_page": 10,
|
|
"data": [{
|
|
"id": "b530fed0-74f5-11ed-9801-35303b735aef",
|
|
"name": "cluster_health_rule",
|
|
"consumer": "alerts",
|
|
"enabled": true,
|
|
"tags": ["cluster","health"],
|
|
"throttle": null,
|
|
"schedule": {"interval":"1m"},
|
|
"params": {},
|
|
"rule_type_id": "monitoring_alert_cluster_health",
|
|
"created_by": "elastic",
|
|
"updated_by": "elastic",
|
|
"created_at": "2022-12-05T23:36:58.284Z",
|
|
"updated_at": "2022-12-05T23:36:58.284Z",
|
|
"api_key_owner": "elastic",
|
|
"notify_when": "onActiveAlert",
|
|
"mute_all": false,
|
|
"muted_alert_ids": [],
|
|
"scheduled_task_id": "b530fed0-74f5-11ed-9801-35303b735aef",
|
|
"execution_status": {
|
|
"status": "ok",
|
|
"last_execution_date": "2022-12-06T00:09:31.882Z",
|
|
"last_duration": 42
|
|
},
|
|
"actions": [{
|
|
"group": "default",
|
|
"id": "9dca3e00-74f5-11ed-9801-35303b735aef",
|
|
"params": {
|
|
"level": "info",
|
|
"message": "{{context.internalFullMessage}}"
|
|
},
|
|
"connector_type_id": ".server-log"
|
|
}],
|
|
"last_run":{
|
|
"alerts_count": {"new": 0,"ignored": 0,"recovered": 0,"active": 0},
|
|
"outcome_msg": null,
|
|
"warning": null,
|
|
"outcome": "succeeded"
|
|
},
|
|
"next_run": "2022-12-06T00:10:31.811Z"
|
|
}]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
For parameters that accept multiple values (such as `fields`), repeat the
|
|
query parameter for each value:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
GET api/alerting/rules/_find?fields=id&fields=name
|
|
--------------------------------------------------
|
|
// KIBANA
|