github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 17:59:23 -04:00
Code Issues Projects Releases Packages Wiki Activity

[Docs/Reporting] More information about HTTP / script stuff (#41200) (#41523)

Browse source 
* [Docs/Reporting] More information about HTTP / script stuff

* "post url" formatting consistency

* consistent wording from 1 paragraph to another

* Update docs/reporting/response-codes.asciidoc

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>

* pr feedback

* subs=attributes, version in command example

* "Retry-After" content

* another feedback
This commit is contained in:
Tim Sullivan 2019-07-18 15:01:41 -07:00 • committed by GitHub
parent ce3c46584b
commit 7995d77f49
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 40 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

7
docs/reporting/automating-report-generation.asciidoc
View file

@ -2,7 +2,7 @@
[[automating-report-generation]]
== Automating Report Generation
You can automatically generate reports with {watcher}, or by submitting
HTTP POST requests from a script.
HTTP `POST` requests from a script.
include::report-intervals.asciidoc[]
@ -38,6 +38,11 @@ include::watch-example.asciidoc[]
include::script-example.asciidoc[]
[float]
=== HTTP Response Codes
include::response-codes.asciidoc[]
[float]
== Deprecated Report URLs

23
docs/reporting/response-codes.asciidoc Normal file
View file

@ -0,0 +1,23 @@
The Reporting APIs use HTTP response codes to give feedback. In automation,
this helps external systems track the various possible job states:
- **`200` (OK)**: As expected, Kibana returns `200` status in the response for
successful requests to queue or download reports.
+
NOTE: Kibana will send a `200` response status for successfully queuing a Reporting job via
the POST URL. This is true even if the job somehow fails later, since report
generation happens asynchronously from queuing.
- **`400` (Bad Request)**: When sending requests to the POST URL, if you don't use
`POST` as the HTTP method, or if your request is missing the `kbn-version` header,
Kibana will return a code `400` status response for the request.
- **`503` (Service Unavailable)**: When using the `path` to request the download, you
will get a `503` status response if report generation hasn't completed yet. The
response will include a `Retry-After` header. You can set the script to wait the
number of seconds in the `Retry-After` header, and then repeat if needed, until the
report is complete.
- **`500` (Internal Server Error)**: When using the `path` to request the download, you
will get a `500` status response if the report isn't available due to an error when
generating the report. More information is available at **Management > Kibana > Reporting**.

33
docs/reporting/script-example.asciidoc
View file

@ -1,28 +1,30 @@
To automatically generate reports from a script, you'll make a request to the POST URL.
To automatically generate reports from a script, you'll make a request to the `POST` URL.
The response from this request will be JSON, and will contain a `path` property with a
URL to use to download the generated report when it is complete.
URL to use to download the generated report. Use the `GET` method in the HTTP request to
download the report.
The request method must be POST and it must include a `kbn-version` header for Kibana
The request method must be `POST` and it must include a `kbn-version` header for Kibana
to allow the request.
The following example queues CSV report generation using the POST URL with cURL:
The following example queues CSV report generation using the `POST` URL with cURL:
[source,shell]
["source","sh",subs="attributes"]
---------------------------------------------------------
curl \
-XPOST \ <1>
-u elastic \ <2>
-H 'kbn-version: 8.0.0' \ <3>
-H 'kbn-version: {version}' \ <3>
'http://0.0.0.0:5601/api/reporting/generate/csv?jobParams=...' <4>
---------------------------------------------------------
// CONSOLE
<1> POST method is required.
<1> `POST` method is required.
<2> Provide user credentials for a user with permission to access Kibana and X-Pack reporting.
<3> The `kbn-version` header is required for all POST requests to Kibana.
<3> The `kbn-version` header is required for all `POST` requests to Kibana.
**The value must match the dotted-numeral version of the Kibana instance.**
<4> The POST URL. You can copy and paste the URL for any report from the Kibana UI.
Here is an example response:
Here is an example response for a successfully queued report:
[source,json]
---------------------------------------------------------
@ -45,16 +47,3 @@ Here is an example response:
<1> The relative path on the Kibana host for downloading the report.
<2> (Not included in the example) Internal representation of the reporting job, as
found in the `.reporting-*` index.
[IMPORTANT]
===================
When using the `path` to request the download, you will get a 503 (Service Unavailable)
response if report generation hasn't completed yet. In that case, retry after the
number of seconds in the `Retry-After` header in the download API response until the
report is complete.
If there was an error in generating the report, the download URL will return a 500
(Internal Server Error) response. More information is available in the
Reporting management page in Kibana: *Management > Kibana > Reporting*
===================