正在加载

UI 设置服务

注意

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

概述

UI 设置可以在管理中的高级设置页面进行配置，并控制 Kibana 的行为。 uiSettings 存储在 config saved object 中，因此，与其他 Saved Objects 一样，符合相同的条件。

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

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

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

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

[预览] 当一个设置在 kibana.yml 中配置为覆盖时，它将覆盖 config saved object 中存储的任何其他值。 如果覆盖配置错误，将导致配置验证失败并阻止 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 Saved Object。

例如，如果我们想删除 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指南中。

© . All rights reserved.