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

UI 设置服务

编辑

UI 设置服务编辑

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

概述编辑

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

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

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

使用高级设置 UI 进行配置编辑

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

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

使用 UI 设置覆盖进行配置编辑

[预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将致力于解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 当在 kibana.yml 中将设置配置为覆盖时，它将覆盖配置保存对象中存储的任何其他值。如果覆盖配置错误，它将无法通过配置验证，并阻止 Kibana 启动。覆盖适用于所有空间和用户的整个 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 指南中。

« 保存对象服务 模式 »