报告集成

应用程序遵循一个约定，该约定由报告功能使用，以确定从 Kibana 请求导出数据所需的信息，以及如何生成和存储报表。

“导出类型”是一些代码，它们插入到 Kibana 报告框架中，负责代表 Kibana 应用程序导出数据。 这些代码段以 TypeScript 类实现，这些类扩展了一个抽象基类，并实现了用于控制报表作业创建以及异步生成报表内容的方法。 它们的 createJob 方法通过接受 jobParams 对象并返回“任务负载”对象来处理创建报表作业的请求。 它们的 runTask 方法通过接受从 createJob 函数创建的任务负载对象来生成报表内容，然后将其存储在 Elasticsearch 的系统索引中。

X-Pack 服务（例如报告功能）向 Kibana 平台的 share 插件注册，以注册其他可用的操作，使内容可共享。

要生成新的报告作业，不同的导出类型需要不同的 jobParams 对象，这些对象经过 Rison 编码并用作 Reporting 生成端点 URL 中的 jobParams 查询字符串变量。 如果您使用上述 共享插件注册，则此细节将被抽象掉。 如果您的应用程序不使用“共享”菜单扩展，则必须生成 URL 并创建对该 URL 的 POST 请求。

每种类型的导出都需要报告作业参数的某些字段。

interface BaseParams {
  title: string;
  objectType: string;
  browserTimezone: string;
  version: string;
};

1. 报表的 title。 这显示在**堆栈管理 > 警报和见解 > 报告**中的报告列表中，并在下载报告时用作文件名。
2. 使用内部 Reporting API 时，会自动添加 objectType 字段。 此值用于在 Kibana 的报表列表中为报表作业选择图标。
3. 使用内部 Reporting API 来制作作业参数时，会自动添加 browserTimezone 字段。 这用于以用户所需的时区正确格式化基于时间的数据。
4. 使用内部 Reporting API 时，会自动添加 version 字段。 这用于在 Kibana 升级后重新使用作业参数并且可能需要迁移的情况下。

导出类型，用于生成 CSV 报表，并且在 Discover 中可用，它使用“搜索源”对象。 此导出类型在代码中称为 csv_searchsource。 CSV 报表作业的配置由包含 BaseParams 和以下字段的接口表示。 要创建 CSV 报表的请求，这些必需的作业参数经过 Rison 编码为报表生成 URL 的查询字符串变量

interface JobParamsCSV {
  searchSource: SerializedSearchSourceFields;
  columns?: string[];
};

1. 序列化数据的对象，内部表示 Kibana 中的搜索对象。 它将包含对 DataView 保存对象的引用。
2. 要作为 CSV 报表中的列包含的字段名称数组。

提供了一种更新的导出类型来生成 CSV 报表，当前仅通过 API 提供。 此导出类型在代码中称为 csv_v2。

interface JobParamsCsvFromSavedObject {
  locatorParams: LocatorParams[];
};

1. locatorParams 值由 Discover 应用程序控制，并标识在 Discover 中加载的搜索，包括 DataView、列和过滤器的选择。 在 createJob 方法中只允许一个数组值。

在报告生成 URL 的路由处理程序收到作业参数后，会自动将一个附加字段添加到作业参数中的字段

interface TaskPayloadCSV {
  pagingStrategy: 'scan' | 'pit'
}

1. pagingStrategy 值取自 kibana.yml 中 xpack.reporting.csv.scroll.strategy 设置的值，用于控制 runTask 方法如何分页浏览所有数据。

PDF 或 PNG 报告作业的配置由包含 BaseParams 和以下字段的接口表示。 要创建其中一种报告类型的请求，这些必需的作业参数被编码为报表生成 URL 的查询字符串变量

interface BaseParamsPDFV2 {
  layout: {
    id: string;
    dimensions: {
      height: number;
      width: number;
    };
  };
  locatorParams: LocatorParams[];
}

interface BaseParamsPNGV2 {
  layout: {
    id: string;
    dimensions: {
      height: number;
      width: number;
    };
  };
  locatorParams: LocatorParams;
}

1. PDF 导出的可用 layout.id 选项包括 preserve_layout、print 和 canvas。 这些选项控制如何捕获仪表板面板并将其放置到 PDF 文件中的页面中。
2. locatorParams 值由浏览器中加载的应用程序控制，将捕获该应用程序的屏幕截图。 生成 PDF 报告的参数允许使用 locatorParams 数组来支持多页 PDF 报告。
3. PNG 导出的唯一可用 layout.id 选项是 preserve_layout。
4. 生成 PNG 报告的参数只允许使用一个 locatorParams 值。

生成 PDF 时，Reporting 导出类型启动的无头浏览器运行一个脚本，该脚本在 DOM 中查找多个属性，以确定应截取哪些元素的屏幕截图以及何时完成可视化的渲染。

打印布局会截取每个带有 data-shared-item 属性的元素的屏幕截图，并将各个屏幕截图包含在 PDF 中。 打印布局还使用与 data-shared-item 相同的 HTMLElement 上的 data-title 和 data-description 属性来指定标题和描述。

保留布局会截取带有 data-shared-items-container 属性的元素的屏幕截图。 此外，报告将调整带有 data-shared-items-container 属性的元素的大小，使其成为布局尺寸中指定的大小。 保留布局还使用带有 data-shared-items-container 属性的 HTMLElement 上的 data-title 和 data-description 属性来指定整个 PDF 的标题/描述。

Reporting 需要确定何时所有可视化都已完成渲染，以便它可以开始截取屏幕截图。 如果有多个可视化，则应指定 data-shared-items-count 属性，以使 Reporting 知道要查找多少可视化。 Reporting 将查看每个带有 data-shared-item 属性的元素，并使用相应的 data-render-complete 属性和 renderComplete 事件来监听渲染完成。 当可视化的渲染完成时，应将 data-render-complete 属性设置为“true”，并且它应调度一个自定义 DOM renderComplete 事件。

如果报告作业使用多个 URL，在查找任何 data-shared-item 或 data-shared-items-count 属性之前，它会等待一个 data-shared-page 属性，该属性指定正在加载哪个页面。

开发人员可以从具备报告功能的应用程序捕获 POST URL，以访问公共 API 报表生成端点中的 jobParams 查询字符串变量。 可以通过 URL 解码器传递查询字符串变量，然后通过 Rison-to-JSON 转换器传递该变量，以使作业参数具有人类可读性。

如果尝试将请求发送到 POST URL 以测试生成报表，请使用包含 curl 命令的 shell 脚本，该命令 POST 请求。 这将避免在交互式 shell 中运行 curl 命令时可能发生的任何意外字符转义。