maxmustermann/kibana
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

[Console] Added information about autocomplete definitions (#105112) (#111830)

Browse source 
* [Console] Added information about autocomplete definitions to the README.md

* [Console] Updated README.md

* Added code review suggestions

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
# Conflicts:
#	packages/kbn-spec-to-console/README.md
This commit is contained in:
Yulia Čech 2021-09-10 12:28:04 +02:00 committed by GitHub
parent 78dc420f77
commit 98a390679c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 225 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
packages/kbn-spec-to-console/README.md
View file

@ -28,4 +28,9 @@ yarn spec_to_console -g "<ELASTICSEARCH-REPO-FOLDER>/rest-api-spec/src/main/reso
* Request bodies
* Data fetched at runtime: indices, fields, snapshots, etc
* Ad hoc additions
* Ad hoc additions
### Updating the script
When converting query params defined in the REST API specs to console autocompletion definitions, the script relies on a set of known conversion rules specified in [lib/convert/params.js](https://github.com/elastic/kibana/blob/master/packages/kbn-spec-to-console/lib/convert/params.js).
For example, `"keep_on_completion":{"type":"boolean"}` from REST API specs is converted to `"keep_on_completion": "__flag__"` in console autocomplete definitions.
When an unknown parameter type is encountered in REST API specs, the script will throw an `Unexpected type error` and the file [lib/convert/params.js](https://github.com/elastic/kibana/blob/master/packages/kbn-spec-to-console/lib/convert/params.js) needs to be updated by adding a new conversion rule.

220
src/plugins/console/README.md
View file

@ -8,7 +8,7 @@ Console provides the user with tools for storing and executing requests against
### `load_from` query parameter
The `load_from` query parameter enables opening Console with prepopulated reuqests in two ways: from the elastic.co docs and from within other parts of Kibana.
The `load_from` query parameter enables opening Console with prepopulated requests in two ways: from the elastic.co docs and from within other parts of Kibana.
Plugins can open requests in Kibana by assigning this parameter a `data:text/plain` [lz-string](https://pieroxy.net/blog/pages/lz-string/index.html) encoded value. For example, navigating to `/dev_tools#/console?load_from=data:text/plain,OIUQKgBA+gzgpgQwE4GMAWAoA3gIgI4CucSAnjgFy4C2CALulAgDZMVYC+nQA` will prepopulate Console with the following request:
@ -16,3 +16,221 @@ Plugins can open requests in Kibana by assigning this parameter a `data:text/pla
GET _search
{"query":{"match_all":{}}}
```
## Architecture
Console uses Ace editor that is wrapped with [`CoreEditor`](https://github.com/elastic/kibana/blob/master/src/plugins/console/public/types/core_editor.ts), so that if needed it can easily be replaced with another editor, for example Monaco.
The autocomplete logic is located in [`autocomplete`](https://github.com/elastic/kibana/blob/master/src/plugins/console/public/lib/autocomplete) folder. Autocomplete rules are computed by classes in `components` sub-folder.
## Autocomplete definitions
Kibana users benefit greatly from autocomplete suggestions since not all Elasticsearch APIs can be provided with a corresponding UI. Autocomplete suggestions improve usability of Console for any Elasticsearch API endpoint.
Autocomplete definitions are all created in the form of javascript objects loaded from `json` and `js` files.
### Creating definitions
The [`generated`](https://github.com/elastic/kibana/blob/master/src/plugins/console/server/lib/spec_definitions/json/generated) folder contains definitions created automatically from Elasticsearch REST API specifications. See this [README](https://github.com/elastic/kibana/blob/master/packages/kbn-spec-to-console/README.md) file for more information on the `spec-to-console` script.
Manually created override files in the [`overrides`](https://github.com/elastic/kibana/blob/master/src/plugins/console/server/lib/spec_definitions/json/overrides) folder contain fixes for generated files and additions for request body parameters.
### Top level keys
Use following top level keys in the definitions objects.
#### `documentation`
Url to Elasticsearch REST API documentation for the endpoint (If the url contains `master` or `current` strings in the path, Console automatically replaces them with the `docLinkVersion` to always redirect the user to the correct version of the documentation).
#### `methods`
Allowed http methods (`GET`, `POST` etc)
#### `patterns`
Array of API endpoints that contain variables like `{indices}` or `{fields}`. For example, `{indices}/_rollup/{rollup_index}`. See the [Variables](#variables) section below for more info.
#### `url_params`
Query url parameters and their values. See the [Query url parameters](#query-url-parameters) section below for more info. An example:
```json
{
"url_params": {
"format": "",
"local": "__flag__",
"h": [],
"expand_wildcards": [
"open",
"closed",
"hidden",
"none",
"all"
]
}
}
```
#### `priority`
Value for selecting one autocomplete definition, if several configurations are loaded from the files. The highest number takes precedence.
#### `data_autocomplete_rules`
Request body parameters and their values. Only used in `overrides` files because REST API specs don't contain any information about body request parameters.
Refer to Elasticsearch REST API documentation when configuring this object. See the [Request body parameters](#request-body-parameters) section below for more info. An example:
```json
{
"data_autocomplete_rules": {
"text": [],
"field": "{field}",
"analyzer": "",
"explain": { "__one_of": [false, true] }
}
}
```
### Query url parameters
Query url parameters are configured in form of an object, for example:
```json
{
"url_params": {
"local": "__flag__",
"scroll": "",
"expand_wildcards": [
"open",
"closed",
"hidden",
"none",
"all"
]
}
}
```
This object specifies 3 query parameters: `local` (boolean value), `scroll` (no default value) and `expand_wildcards` (with a list of accepted values).
When the user types in the url path into Console and at least 2 characters after `?`, all matching url parameters are displayed as autocomplete suggestions. In this example, after typing
```
GET /_some_endpoint?ca
```
"local" and "expand_wildcards" are displayed as suggestions.
When the user types at least 2 characters after `=`, all matching values for this parameter are displayed as autocomplete suggestions. In this example, after typing
```
GET /_some_endpoint?expand_wildcards=hi
```
"hidden" is displayed for autocompletion.
Variables such as `{indices}` or `{fields}` are accepted both as an url parameter and its value in the configuration object. See the [Variables](#variables) section below for more information.
### Request body parameters
Request body parameters are configured in form of an object, for example:
```json
{
"data_autocomplete_rules": {
"index_patterns": [],
"mappings": { "__scope_link": "put_mapping" },
"version": 0,
"aliases": {
"__template": {
"NAME": {}
}
}
}
}
```
Object's keys are parameters that will be displayed as autocomplete suggestions when the user starts typing request body. In this example, after typing
```
PUT /_some_endpoint
{
"
```
"index_patterns", "mappings", "version" and "aliases" are displayed as autocomplete suggestions.
Object's values provide default or accepted values of request body parameters. For example, if "version" is selected from the suggestions list, value `0` is automatically filled, resulting in the following request:
```
PUT /_some_endpoint
{
"version": 0
}
```
Object's values can contain objects for nested configuration because the engine can work recursively while searching for autocomplete suggestions.
Following values can be used in the configuration object:
#### One value from the list (`__one_of: [..., ...]`)
Use this configuration for a parameter with a list of allowed values, for example types of snapshot repository:
```
"type": {"__one_of": ["fs", "url", "s3", "hdfs", "azure"]}
```
The first value in the list will be automatically filled as parameter value. For example, when "type" is selected from the suggestions list, the request body is autofilled as following:
```
PUT /_some_endpoint
{
"type": "fs"
}
```
But if the value `fs` is deleted, all suggestions will be displayed: "fs", "url", "s3", "hdfs" and "azure".
Use `__one_of: [true, false]` for boolean values.
#### Array of values (`[..., ... ]` or `__any_of: [..., ...]`)
Use this configuration for parameters which accept an array of values, for example actions parameter:
```
"actions": { "__any_of": [ "add", "remove"]}
```
When "actions" is selected from the suggestions list, it will be autocompleted with an empty array:
```
POST /_some_endpoint
{
"actions": []
}
```
All values in the array are displayed as suggestions for parameter values inside the array.
#### Default object structure (`__template: {...}`)
Use this configuration to insert an object with default values into the request body when the corresponding key is typed in.
For example, in this configuration
```json
{
"terms": {
"__template": {
"field": "",
"size": 10
},
"field": "{field}",
"size": 10,
"shard_size": 10,
"min_doc_count": 10
}
}
```
the `terms` parameter has several properties, but only `field` and `size` are autocompleted in the request body when "terms" is selected from the suggestions list.
```
POST /_some_endpoint
{
terms: {
field: '',
size: 10,
}
}
```
The rest of the properties are displayed as autocomplete suggestions, when the `terms` object is being edited.
#### Scope link (`__scope_link`)
Use this type to copy a configuration object specified in a different endpoint definition. For example, the `put_settings` endpoint definition contains a configuration object that can be reused for `settings` parameter in a different endpoint:
```json
{
"data_autocomplete_rules": {
"settings": {
"__scope_link": "put_settings"
}
}
}
```
#### Global scope (`GLOBAL`)
Use `GLOBAL` keyword with `__scope_link` to refer to a reusable set of definitions created in the [`globals`](https://github.com/elastic/kibana/blob/master/src/plugins/console/server/lib/spec_definitions/js/globals.ts) file.
For example:
```json
{
"data_autocomplete_rules": {
"query": {
"__scope_link": "GLOBAL.query"
}
}
}
```
#### Conditional definition (`__condition: { lines_regex: ... }`)
To provide a different set of autocomplete suggestions based on the value configured in the request. For example, when creating a snapshot repository of different types (`fs`, `url` etc) different properties are displayed in the suggestions list based on the type. See [snapshot.create_repository.json](https://github.com/elastic/kibana/blob/master/src/plugins/console/server/lib/spec_definitions/json/overrides/snapshot.create_repository.json) for an example.
### Variables
Some autocomplete definitions need to be configured with dynamic values that can't be hard coded into a json or js file, for example a list of indices in the cluster.
A list of variables is defined in the `parametrizedComponentFactories` function in [`kb.js`](https://github.com/elastic/kibana/blob/master/src/plugins/console/public/lib/kb/kb.js) file. The values of these variables are assigned dynamically for every cluster.
Use these variables with curly braces, for example `{indices}`, `{types}`, `{id}`, `{username}`, `{template}`, `{nodes}` etc.