forked from elastic/kibana
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Actions][Docs] Actions and Connectors API Docs (elastic#90974)
* Stubbing out asciidocs * wip * Finishing connector API docs * Cleanup * Removing experimental label * PR fixes * PR fixes * PR fixes
- Loading branch information
Showing
18 changed files
with
455 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
[[actions-and-connectors-api]] | ||
== Action and connector APIs | ||
|
||
Manage Actions and Connectors. | ||
|
||
The following action APIs are available: | ||
|
||
* <<actions-and-connectors-api-get, Get action API>> to retrieve a single action by ID | ||
|
||
* <<actions-and-connectors-api-get-all, Get all actions API>> to retrieve all actions | ||
|
||
* <<actions-and-connectors-api-list, List all action types API>> to retrieve a list of all action types | ||
|
||
* <<actions-and-connectors-api-create, Create action API>> to create actions | ||
|
||
* <<actions-and-connectors-api-update, Update action API>> to update the attributes for an existing action | ||
|
||
* <<actions-and-connectors-api-execute, Execute action API>> to execute an action by ID | ||
|
||
* <<actions-and-connectors-api-delete, Delete action API>> to delete an action by ID | ||
|
||
For information about the actions and connectors that {kib} supports, refer to <<action-types,Action and connector types>>. | ||
|
||
include::actions-and-connectors/get.asciidoc[] | ||
include::actions-and-connectors/get_all.asciidoc[] | ||
include::actions-and-connectors/list.asciidoc[] | ||
include::actions-and-connectors/create.asciidoc[] | ||
include::actions-and-connectors/update.asciidoc[] | ||
include::actions-and-connectors/execute.asciidoc[] | ||
include::actions-and-connectors/delete.asciidoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
[[actions-and-connectors-api-create]] | ||
=== Create action API | ||
++++ | ||
<titleabbrev>Create action API</titleabbrev> | ||
++++ | ||
|
||
Creates an action. | ||
|
||
[[actions-and-connectors-api-create-request]] | ||
==== Request | ||
|
||
`POST <kibana host>:<port>/api/actions/action` | ||
|
||
[[actions-and-connectors-api-create-request-body]] | ||
==== Request body | ||
|
||
`name`:: | ||
(Required, string) The display name for the action. | ||
|
||
`actionTypeId`:: | ||
(Required, string) The action type ID for the action. | ||
|
||
`config`:: | ||
(Required, object) The configuration for the action. Configuration properties vary depending on | ||
the action type. For information about the configuration properties, refer to <<action-types,Action and connector types>>. | ||
|
||
`secrets`:: | ||
(Required, object) The secrets configuration for the action. Secrets configuration properties vary | ||
depending on the action type. For information about the secrets configuration properties, refer to <<action-types,Action and connector types>>. | ||
|
||
[[actions-and-connectors-api-create-request-codes]] | ||
==== Response code | ||
|
||
`200`:: | ||
Indicates a successful call. | ||
|
||
[[actions-and-connectors-api-create-example]] | ||
==== Example | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
$ curl -X POST api/actions/action -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' | ||
{ | ||
"name": "my-action", | ||
"actionTypeId": ".index", | ||
"config": { | ||
"index": "test-index" | ||
} | ||
}' | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
The API returns the following: | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
{ | ||
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad", | ||
"actionTypeId": ".index", | ||
"name": "my-action", | ||
"config": { | ||
"index": "test-index", | ||
"refresh": false, | ||
"executionTimeField": null | ||
}, | ||
"isPreconfigured": false | ||
} | ||
-------------------------------------------------- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
[[actions-and-connectors-api-delete]] | ||
=== Delete action API | ||
++++ | ||
<titleabbrev>Delete action API</titleabbrev> | ||
++++ | ||
|
||
Deletes an action by ID. | ||
|
||
WARNING: When you delete an action, _it cannot be recovered_. | ||
|
||
[[actions-and-connectors-api-delete-request]] | ||
==== Request | ||
|
||
`DELETE <kibana host>:<port>/api/actions/action/<id>` | ||
|
||
[[actions-and-connectors-api-delete-path-params]] | ||
==== Path parameters | ||
|
||
`id`:: | ||
(Required, string) The ID of the action. | ||
|
||
[[actions-and-connectors-api-delete-response-codes]] | ||
==== Response code | ||
|
||
`200`:: | ||
Indicates a successful call. | ||
|
||
==== Example | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
$ curl -X DELETE api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
[[actions-and-connectors-api-execute]] | ||
=== Execute action API | ||
++++ | ||
<titleabbrev>Execute action API</titleabbrev> | ||
++++ | ||
|
||
Executes an action by ID. | ||
|
||
[[actions-and-connectors-api-execute-request]] | ||
==== Request | ||
|
||
`POST <kibana host>:<port>/api/actions/action/<id>/_execute` | ||
|
||
[[actions-and-connectors-api-execute-params]] | ||
==== Path parameters | ||
|
||
`id`:: | ||
(Required, string) The ID of the action. | ||
|
||
[[actions-and-connectors-api-execute-request-body]] | ||
==== Request body | ||
|
||
`params`:: | ||
(Required, object) The parameters of the action. Parameter properties vary depending on | ||
the action type. For information about the parameter properties, refer to <<action-types,Action and connector types>>. | ||
|
||
[[actions-and-connectors-api-execute-codes]] | ||
==== Response code | ||
|
||
`200`:: | ||
Indicates a successful call. | ||
|
||
[[actions-and-connectors-api-execute-example]] | ||
==== Example | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
$ curl -X POST api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad/_execute -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' | ||
{ | ||
"params": { | ||
"documents": [ | ||
{ | ||
"id": "test_doc_id", | ||
"name": "test_doc_name", | ||
"message": "hello, world" | ||
} | ||
] | ||
} | ||
}' | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
The API returns the following: | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
{ | ||
"status": "ok", | ||
"data": { | ||
"took": 197, | ||
"errors": false, | ||
"items": [ | ||
{ | ||
"index": { | ||
"_index": "updated-index", | ||
"_id": "iKyijHcBKCsmXNFrQe3T", | ||
"_version": 1, | ||
"result": "created", | ||
"_shards": { | ||
"total": 2, | ||
"successful": 1, | ||
"failed": 0 | ||
}, | ||
"_seq_no": 0, | ||
"_primary_term": 1, | ||
"status": 201 | ||
} | ||
} | ||
] | ||
}, | ||
"actionId": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad" | ||
} | ||
-------------------------------------------------- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
[[actions-and-connectors-api-get]] | ||
=== Get action API | ||
++++ | ||
<titleabbrev>Get action API</titleabbrev> | ||
++++ | ||
|
||
Retrieves an action by ID. | ||
|
||
[[actions-and-connectors-api-get-request]] | ||
==== Request | ||
|
||
`GET <kibana host>:<port>/api/actions/action/<id>` | ||
|
||
[[actions-and-connectors-api-get-params]] | ||
==== Path parameters | ||
|
||
`id`:: | ||
(Required, string) The ID of the action. | ||
|
||
[[actions-and-connectors-api-get-codes]] | ||
==== Response code | ||
|
||
`200`:: | ||
Indicates a successful call. | ||
|
||
[[actions-and-connectors-api-get-example]] | ||
==== Example | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
$ curl -X GET api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
The API returns the following: | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
{ | ||
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad", | ||
"actionTypeId": ".index", | ||
"name": "my-action", | ||
"config": { | ||
"index": "test-index", | ||
"refresh": false, | ||
"executionTimeField": null | ||
}, | ||
"isPreconfigured": false | ||
} | ||
-------------------------------------------------- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
[[actions-and-connectors-api-get-all]] | ||
=== Get all actions API | ||
++++ | ||
<titleabbrev>Get all actions API</titleabbrev> | ||
++++ | ||
|
||
Retrieves all actions. | ||
|
||
[[actions-and-connectors-api-get-all-request]] | ||
==== Request | ||
|
||
`GET <kibana host>:<port>/api/actions` | ||
|
||
[[actions-and-connectors-api-get-all-codes]] | ||
==== Response code | ||
|
||
`200`:: | ||
Indicates a successful call. | ||
|
||
[[actions-and-connectors-api-get-all-example]] | ||
==== Example | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
$ curl -X GET api/actions | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
The API returns the following: | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
[ | ||
{ | ||
"id": "preconfigured-mail-action", | ||
"actionTypeId": ".email", | ||
"name": "email: preconfigured-mail-action", | ||
"isPreconfigured": true | ||
}, | ||
{ | ||
"id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad", | ||
"actionTypeId": ".index", | ||
"name": "my-action", | ||
"config": { | ||
"index": "test-index", | ||
"refresh": false, | ||
"executionTimeField": null | ||
}, | ||
"isPreconfigured": false | ||
} | ||
] | ||
-------------------------------------------------- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
[[actions-and-connectors-api-list]] | ||
=== List action types API | ||
++++ | ||
<titleabbrev>List all action types API</titleabbrev> | ||
++++ | ||
|
||
Retrieves a list of all action types. | ||
|
||
[[actions-and-connectors-api-list-request]] | ||
==== Request | ||
|
||
`GET <kibana host>:<port>/api/actions/list_action_types` | ||
|
||
[[actions-and-connectors-api-list-codes]] | ||
==== Response code | ||
|
||
`200`:: | ||
Indicates a successful call. | ||
|
||
[[actions-and-connectors-api-list-example]] | ||
==== Example | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
$ curl -X GET api/actions/list_action_types | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
The API returns the following: | ||
|
||
[source,sh] | ||
-------------------------------------------------- | ||
[ | ||
{ | ||
"id": ".email", <1> | ||
"name": "Email", <2> | ||
"minimumLicenseRequired": "gold", <3> | ||
"enabled": false, <4> | ||
"enabledInConfig": true, <5> | ||
"enabledInLicense": false <6> | ||
}, | ||
{ | ||
"id": ".index", | ||
"name": "Index", | ||
"minimumLicenseRequired": "basic", | ||
"enabled": true, | ||
"enabledInConfig": true, | ||
"enabledInLicense": true | ||
} | ||
] | ||
-------------------------------------------------- | ||
|
||
|
||
<1> `id` - The unique ID of the action type. | ||
<2> `name` - The name of the action type. | ||
<3> `minimumLicenseRequired` - The license required to use the action type. | ||
<4> `enabled` - Specifies if the action type is enabled or disabled in {kib}. | ||
<5> `enabledInConfig` - Specifies if the action type is enabled or enabled in the {kib} .yml file. | ||
<6> `enabledInLicense` - Specifies if the action type is enabled or disabled in the license. |
Oops, something went wrong.