From abdad5be158787134b33b33f6ad200d5c7c1ae08 Mon Sep 17 00:00:00 2001 From: Tim Sullivan Date: Thu, 18 Jul 2019 14:41:43 -0700 Subject: [PATCH] [Docs/Reporting] More information about HTTP / script stuff (#41200) * [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 --- .../automating-report-generation.asciidoc | 7 +++- docs/reporting/response-codes.asciidoc | 23 +++++++++++++ docs/reporting/script-example.asciidoc | 33 +++++++------------ 3 files changed, 40 insertions(+), 23 deletions(-) create mode 100644 docs/reporting/response-codes.asciidoc diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc index 194702c96afe6..01b3f80853ef8 100644 --- a/docs/reporting/automating-report-generation.asciidoc +++ b/docs/reporting/automating-report-generation.asciidoc @@ -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 diff --git a/docs/reporting/response-codes.asciidoc b/docs/reporting/response-codes.asciidoc new file mode 100644 index 0000000000000..5ec9bf5300124 --- /dev/null +++ b/docs/reporting/response-codes.asciidoc @@ -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**. diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc index 8682578735b66..88f48ad1d3182 100644 --- a/docs/reporting/script-example.asciidoc +++ b/docs/reporting/script-example.asciidoc @@ -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* -=================== -