« 保存对象服务 模式 »
Elastic 文档 ›Kibana 指南 [8.17] ›开发者指南 ›架构

UI 设置服务

编辑

UI 设置服务

编辑

UI 设置服务在服务器端和客户端都可用。

概述

编辑

UI 设置可通过“管理”中的“高级设置”页面进行配置，并控制 Kibana 的行为。uiSettings 存储在配置保存对象中，因此与其他的保存对象遵循相同的条件。

有几种方法可以配置高级设置

请记住，一旦添加了新的高级设置，如果不在核心中注册迁移，就无法更改或删除它。

通过“高级设置”UI 配置

编辑

uiSettings 服务是 Kibana 的“高级设置”UI 的编程接口。Kibana 插件使用此服务来扩展 Kibana UI 设置管理，为它们的插件提供自定义设置。

通过“高级设置”UI 进行配置仅限于有权访问“高级设置”页面的用户。没有权限更改这些值的用户默认使用为他们所在空间配置的设置。配置保存的对象可以在空间之间共享。

通过 UI 设置覆盖进行配置

编辑

[预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 的约束。 当在 kibana.yml 中将设置配置为覆盖时，它将覆盖配置保存对象中存储的任何其他值。如果覆盖配置错误，将导致配置验证失败并阻止 Kibana 启动。覆盖适用于所有空间和用户，并且该选项将在“高级设置”页面中禁用。我们将其称为“全局”覆盖。

为此，请使用顶级 uiSettings 键，例如

# Display times in UTC
uiSettings:
  overrides:
    "dateFormat:tz": "UTC"

客户端使用

编辑

在客户端，uiSettings 服务直接从 core 公开，并且客户端允许插件访问 Elasticsearch 中存储的 config 条目。

为了提高性能，uiSettings 被缓存。任何需要刷新缓存的更改都应该注册一个指令，以便在使用 requiresPageReload 参数在“高级设置”中配置设置时重新加载页面。

import { CoreSetup, Plugin } from 'src/core/public';

export class MyPlugin implements Plugin<MyPluginSetup, MyPluginStart> {
  public setup(core: CoreSetup): MyPluginSetup {
    …
    core.uiSettings.getUpdate$().subscribe(({ key, newValue }) => {
      if (key === 'custom') {
        // do something with changes...
        myPluginService.register({
          …
        })
      }
    });
    …
  }

  public start(core: CoreStart): MyPluginStart {
    return {
      …
      settings: {
        getCustomValue: () => core.uiSettings.get('custom'),
        …
      },
    };
  }
}

服务器端使用

编辑

在服务器端，uiSettings 直接从 core 公开。

以下示例展示了如何注册一个新的 custom 设置，其默认值为 42。注册新设置时，必须提供一个架构，以便对读取和写入执行验证。所有其他参数是可选的。

import { schema } from '@kbn/config-schema';
import type { CoreSetup,Plugin } from '@kbn/core/server';

export class MyPlugin implements Plugin {
  public setup(core: CoreSetup) {
    core.uiSettings.register({
      custom: {
        value: '42',
        schema: schema.string(),
      },
    });
    const router = core.http.createRouter();
    router.get({
      path: 'my_plugin/{id}',
      validate: …,
    },
    async (context, request, response) => {
      const customSetting = await context.uiSettings.client.get('custom');
      …
    });
  }
}

迁移

编辑

当前不支持第三方插件高级设置的迁移。如果第三方插件注册了一个高级设置，该设置本质上是永久性的，如果没有人工干预则无法修复。

要更改或删除 uiSetting，需要迁移整个 config 保存的对象。

例如，如果我们想删除一个 custom 设置，或者将 my_setting:fourtyTwo 重命名为 my_other_setting:fourtyTwo，我们需要两个迁移条目，每个更改一个，针对应用这些更改的版本

export const migrations = {
  ...
  '8.1.0': (doc: SavedObjectUnsanitizedDoc<any>): SavedObjectSanitizedDoc<any> => ({
  ...doc,
  ...(doc.attributes && {
    attributes: Object.keys(doc.attributes).reduce(
      (acc, key) =>
        [
          // other settings to remove for 8.1.0...
          'custom',
        ].includes(key)
          ? {
              ...acc,
            }
          : {
              ...acc,
              [key]: doc.attributes[key],
            },
      {}
    ),
  }),
  references: doc.references || [],
  }),
  '8.2.0': (doc: SavedObjectUnsanitizedDoc<any>): SavedObjectSanitizedDoc<any> => ({
    ...doc,
    ...(doc.attributes && {
      attributes: Object.keys(doc.attributes).reduce(
        (acc, key) =>
          key.startsWith('my_setting:')
            ? {
                ...acc,
                [key.replace('my_setting', 'my_other_setting')]: doc.attributes[key],
              }
            : {
                ...acc,
                [key]: doc.attributes[key],
              },
        {}
      ),
    }),
    references: doc.references || [],
  }),
  …
}

插件可以利用注册时可选的弃用参数来处理弃用通知和重命名。弃用警告会在“高级设置”UI 中呈现，并且还应添加到配置 Kibana 指南中。

« 保存对象服务 模式 »