mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 01:38:56 -04:00
[Reporting/Docs] Update Developer API docs (#179723)
## Summary Part of documentation updates required for https://github.com/elastic/kibana-team/issues/720 * Removes outdated info about Angular directives * Remove outdated info about the original CSV export type * Add explanation of what an Export Type is * More detail about the job parameters for each export type * Add tips to debug using POST URLs
This commit is contained in:
Tim Sullivan
GitHub
parent
13dfd58bd8
commit
d0419554d7
3 changed files with 117 additions and 91 deletions
|
|
@ -2,50 +2,43 @@
|
|||
=== CSV
|
||||
|
||||
[float]
|
||||
==== Job parameters
|
||||
If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to
|
||||
the aforementioned generate job url:
|
||||
==== Job parameters of CsvSearchSource
|
||||
The export type to generate CSV reports and is available in Discover uses "search source" objects. This export type is called
|
||||
`csv_searchsource` in the code. A configuration for a CSV report job is represented with an interface that includes the
|
||||
`BaseParams` and the following fields. To create a request for a CSV report, these required job parameters are Rison encoded into
|
||||
a query string variable of the report generation URL:
|
||||
|
||||
----
|
||||
interface jobParameters {
|
||||
type: string;
|
||||
title: string;
|
||||
searchRequest: {
|
||||
index: string;
|
||||
body: object;
|
||||
};
|
||||
fields: string[];
|
||||
metaFields: string[];
|
||||
conflictedTypesFields: string[];
|
||||
indexPatternId: string;
|
||||
}
|
||||
interface JobParamsCSV {
|
||||
searchSource: SerializedSearchSourceFields; <1>
|
||||
columns?: string[]; <2>
|
||||
};
|
||||
----
|
||||
|
||||
The `searchRequest.body` should abide by the {ref}/search-search.html[Elasticsearch Search Request Body] syntax
|
||||
<1> An object of serialized data that internally represents a search object in Kibana. It will contain a reference to a DataView
|
||||
saved object.
|
||||
<2> An array of field names to include as columns in the CSV report.
|
||||
|
||||
[float]
|
||||
==== `export-config` Directive
|
||||
If integrating with Reporting via the `export-config` directive, the AngularJS controller that contains the directive should expose
|
||||
the following methods and the `export-config` directive will POST them to the reporting API:
|
||||
==== Job parameters of CsvFromSavedObject
|
||||
A newer export type to generate CSV reports is available, currently only by API. This export type is called `csv_v2` in the code.
|
||||
|
||||
----
|
||||
interface sharingData {
|
||||
searchRequest: {
|
||||
index: string;
|
||||
body: object;
|
||||
};
|
||||
fields: string[];
|
||||
metaFields: string[];
|
||||
conflictedTypesFields: string[];
|
||||
indexPatternId: string;
|
||||
interface JobParamsCsvFromSavedObject {
|
||||
locatorParams: LocatorParams[]; <1>
|
||||
};
|
||||
----
|
||||
<1> The `locatorParams` value is controlled by the Discover application and identifies a search loaded in Discover, including the
|
||||
selection of DataView, columns and filters. Only a single value in the array is permitted in the `createJob` method.
|
||||
|
||||
[float]
|
||||
==== Job payload
|
||||
After the job parameters are received by the route handler for the report generation URL, an additional field is automatically
|
||||
added to the fields from job parameters:
|
||||
|
||||
----
|
||||
interface TaskPayloadCSV {
|
||||
pagingStrategy: 'scan' | 'pit' <1>
|
||||
}
|
||||
|
||||
function getSharingData(): sharingData;
|
||||
|
||||
function getSharingType(): string;
|
||||
|
||||
function getSharingTitle() string;
|
||||
|
||||
----
|
||||
|
||||
The `sharingData.searchRequest.body` should abide by the {ref}/search-search.html[{es} Search Request Body] syntax
|
||||
<1> The `pagingStrategy` value is taken from the value of the `xpack.reporting.csv.scroll.strategy` setting in kibana.yml and used
|
||||
to control how the `runTask` method pages through all of the data.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,8 @@
|
|||
[role="xpack"]
|
||||
[[reporting-integration]]
|
||||
== Reporting integration
|
||||
Integrating a {kib} application with the {report-features} requires a minimum
|
||||
amount of code, and the goal is to not have to modify the reporting code as we
|
||||
add additional applications. Instead, applications abide by a contract that
|
||||
{report-features} use to determine the information that is required to export
|
||||
CSVs and PDFs.
|
||||
Applications abide by a contract that {report-features} use to determine the information that is required to request exports of
|
||||
data from {kib}, and how to generate and store the reports.
|
||||
|
||||
[IMPORTANT]
|
||||
==============================================
|
||||
|
|
@ -14,16 +11,56 @@ However, these docs will be kept up-to-date to reflect the current implementatio
|
|||
==============================================
|
||||
|
||||
[float]
|
||||
[[reporting-nav-bar-extensions]]
|
||||
=== Share menu extensions
|
||||
X-Pack uses the `share` plugin of the Kibana platform to register actions in the share menu.
|
||||
=== Reporting Export Types
|
||||
"Export Types" are pieces of code that plug into the {kib} Reporting framework, and are responsible for exporting data on behalf
|
||||
of a {kib} application. These pieces of code are implemented as TypeScript classes that extend an abstract base class, and
|
||||
implement methods for controlling the creation of report jobs, and asynchronously generating report contents. Their `createJob`
|
||||
methods handle requests to create report jobs, by accepting jobParams objects and returning "task payload" objects. Their
|
||||
`runTask` methods generate the report contents by accepting the task payload object created from the `createJob` function, which
|
||||
is then stored in a system index in Elasticsearch.
|
||||
|
||||
[float]
|
||||
=== Generate job URL
|
||||
To generate a new reporting job, different export types require different `jobParams` that are Rison encoded into a URL
|
||||
that abide by the following convention: `/api/reporting/generate?jobParams=${rison.encode(jobParams)}`. If you use the
|
||||
aforementioned <<reporting-nav-bar-extensions, nav bar extensions>> then this detail will be abstracted away, but if you
|
||||
provide a custom UI for generating the report, you will have to generate the URL and create a POST request to the URL.
|
||||
[[reporting-share-service-registrations]]
|
||||
=== Share menu extensions
|
||||
X-Pack services, such as the {report-features}, register with the `share` plugin of the Kibana platform to register additional
|
||||
actions available to make content shareable.
|
||||
|
||||
[float]
|
||||
=== Generate a report job URL
|
||||
To generate a new reporting job, different export types require different `jobParams` objects, which are Rison-encoded and used as
|
||||
a `jobParams` query string variable in the Reporting generation endpoint URL. If you use the aforementioned
|
||||
<<reporting-share-service-registrations, Sharing plugin registrations>> then this detail will be abstracted away. If your
|
||||
application does not use the Share menu extensions, you will have to generate the URL and create a POST request to the URL.
|
||||
|
||||
[float]
|
||||
=== Basic job parameters
|
||||
Certain fields of Reporting job parameters are required for every type of export.
|
||||
|
||||
----
|
||||
interface BaseParams {
|
||||
title: string; <1>
|
||||
objectType: string; <2>
|
||||
browserTimezone: string; <3>
|
||||
version: string; <4>
|
||||
};
|
||||
----
|
||||
<1> The `title` for the report. This is shown in the listing of reports in **Stack Management > Alerts and
|
||||
Insights > Reporting** and used as the filename when the report is downloaded.
|
||||
<2> The `objectType` field is automatically added when using internal Reporting APIs. This value used for choosing an icon for the
|
||||
report job in the listing of reports in {kib}.
|
||||
<3> The `browserTimezone` field is automatically added when using internal Reporting APIs to craft the job parameters. This is
|
||||
used to correctly format time-based data in the user's desired timezone.
|
||||
<4> The `version` field is automatically added when using internal Reporting APIs. This is used in cases where job parameters are
|
||||
reused after an upgrade of Kibana, and a migration may be needed.
|
||||
|
||||
include::csv-integration.asciidoc[]
|
||||
include::pdf-integration.asciidoc[]
|
||||
|
||||
=== Using POST URLs for debugging
|
||||
Developers can capture a POST URL from a reporting-capable application to access the `jobParams` query string variable in the
|
||||
public API report generation endpoint. The query string variable can be passed through a URL de-encoder and then passed through a
|
||||
Rison-to-JSON converter to make the job parameters human-readable.
|
||||
|
||||
If attempting to send requests to the POST URL to test generating a report, use a shell script containing the curl command that
|
||||
POSTs the request. This will avoid any unintentional character escaping that can happen if running the curl command in an
|
||||
interactive shell.
|
||||
|
|
|
|||
|
|
@ -1,53 +1,47 @@
|
|||
[float]
|
||||
=== PDF
|
||||
=== PDF and PNG
|
||||
|
||||
[float]
|
||||
==== Job parameters
|
||||
If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to
|
||||
the aforementioned generate job url:
|
||||
A configuration for a PDF or PNG report job is represented with an interface that includes the `BaseParams` and the following
|
||||
fields. To create a request for one of these report types, these required job parameters are encoded into a query string variable
|
||||
of the report generation URL:
|
||||
|
||||
----
|
||||
interface jobParameters {
|
||||
objectType: string;
|
||||
title: string;
|
||||
browserTimezone: string;
|
||||
relativeUrls: string[];
|
||||
interface BaseParamsPDFV2 {
|
||||
layout: {
|
||||
id: string;
|
||||
id: string; <1>
|
||||
dimensions: {
|
||||
height: number;
|
||||
width: number;
|
||||
};
|
||||
};
|
||||
locatorParams: LocatorParams[]; <2>
|
||||
}
|
||||
|
||||
interface BaseParamsPNGV2 {
|
||||
layout: {
|
||||
id: string; <3>
|
||||
dimensions: {
|
||||
height: number;
|
||||
width: number;
|
||||
};
|
||||
};
|
||||
locatorParams: LocatorParams; <4>
|
||||
}
|
||||
----
|
||||
|
||||
`jobParameters.browserTimezone` is a string that appears in the tz database
|
||||
`jobParameters.layout.id` presently only accepts "print" and "preserve_layout"
|
||||
`jobParameters.layout.dimensions` is only currently used by "preserve_layout"
|
||||
<1> The available `layout.id` options for PDF exports are `preserve_layout`, `print`, and `canvas`. These control how dashboard
|
||||
panels are captured and positioned into pages in the PDF file.
|
||||
<2> The `locatorParams` value is controlled by the application loaded in the browser for which a screenshot will be captured. The
|
||||
parameters to generate a PDF report allow an array of `locatorParams` to support multi-page PDF reports.
|
||||
<3> The only available `layout.id` option for PNG exports is `preserve_layout`.
|
||||
<4> The parameters to generate a PNG report allow a single value for `locatorParams`.
|
||||
|
||||
[float]
|
||||
==== `export-config` directive
|
||||
If integrating with Reporting via the `export-config` directive, the AngularJS controller that contains
|
||||
the directive should expose the following methods and the `export-config` directive will POST them to the
|
||||
reporting API:
|
||||
|
||||
----
|
||||
|
||||
function getSharingType(): string;
|
||||
|
||||
function getSharingTitle(): string;
|
||||
|
||||
----
|
||||
|
||||
The `export-config` directive will use the browser's current URL and timezone when generating the job
|
||||
parameters automatically. The `export-config` directive will also grab the height/width of the element
|
||||
with the `data-shared-items-container` attribute and use this as the dimensions.
|
||||
|
||||
[float]
|
||||
==== Screenshot capturing attributes
|
||||
When generating the PDF, reporting looks for a number of attributes in the DOM to determine which elements
|
||||
should have their screenshot taken and when the Visualizations are done rendering.
|
||||
==== How applications make themselves screenshot-capable
|
||||
When generating the PDF, the headless browser launched by the Reporting export type runs a script that looks for a number of
|
||||
attributes in the DOM to determine which elements should have their screenshot taken and when the Visualizations are done
|
||||
rendering.
|
||||
|
||||
The print layout takes a screenshot of every element with the `data-shared-item` attribute and includes the
|
||||
individual screenshots in the PDF. The print layout also uses the `data-title` and `data-description`
|
||||
|
|
@ -58,10 +52,12 @@ reporting will resize the element with the `data-shared-items-container` to be t
|
|||
The preserve layout also uses the `data-title` and `data-description` attributes on the HTMLElement with the
|
||||
`data-shared-items-container` attribute to specify the title/description for the entire PDF.
|
||||
|
||||
Reporting needs to determine when all of the visualizations have completed rendering, so that it can begin taking screenshots.
|
||||
If there are multiple visualizations, the `data-shared-items-count` attribute should be specified to let Reporting know how
|
||||
many Visualizations to look for. Reporting will look at every element with the `data-shared-item` attribute and use the corresponding
|
||||
`data-render-complete` attribute and `renderComplete` events to listen for rendering to complete. When rendering is complete for a visualization
|
||||
the `data-render-complete` attribute should be set to "true" and it should dispatch a custom DOM `renderComplete` event.
|
||||
Reporting needs to determine when all of the visualizations have completed rendering, so that it can begin taking screenshots. If
|
||||
there are multiple visualizations, the `data-shared-items-count` attribute should be specified to let Reporting know how many
|
||||
Visualizations to look for. Reporting will look at every element with the `data-shared-item` attribute and use the corresponding
|
||||
`data-render-complete` attribute and `renderComplete` events to listen for rendering to complete. When rendering is complete for a
|
||||
visualization the `data-render-complete` attribute should be set to "true" and it should dispatch a custom DOM `renderComplete`
|
||||
event.
|
||||
|
||||
If the reporting job uses multiple URLs, before looking for any of the `data-shared-item` or `data-shared-items-count` attributes, it waits for a `data-shared-page` attribute that specifies which page is being loaded.
|
||||
If the reporting job uses multiple URLs, before looking for any of the `data-shared-item` or `data-shared-items-count` attributes,
|
||||
it waits for a `data-shared-page` attribute that specifies which page is being loaded.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue