跳转到主要内容

将插件从 Grafana 9.3.x 迁移到 9.4.x

按照以下说明将 Grafana 9.3.x 迁移到 9.4.x。

支持新的导航布局​

首先，在 custom.ini 中启用 topnav 功能标志，以检查您的插件在新导航布局中的渲染情况

[feature_toggles]
enable = topnav

从 onNavChanged 迁移​

如果您的插件使用 onNavChanged 回调来通知 Grafana 其导航模型和子页面，您应该看到这会导致导航元素重复。如果您禁用 topnav，则应与之前一样。

如果启用 topnav，则需要更新插件以利用新的 PluginPage 组件。在这种情况下，我们不调用已弃用的 onNavChanged。

切换到 PluginPage 组件​

Grafana 现在从 @grafana/runtime 暴露了一个新的 PluginPage 组件，该组件可以挂钩到新的导航和页面布局。此新组件还支持在禁用 topnav 功能时使用旧页面布局。

新的 PluginPage 组件还将处理渲染部分导航。部分导航可以包括其他核心部分和其他插件。为了控制特定插件在部分导航中显示哪些页面，Grafana 使用在 plugin.json 中添加且将 addToNav 设置为 true 的页面。

要使用此组件，只需将其包装在页面内容周围即可

import { PluginPage } from '@grafana/runtime';

...

return (
  <PluginPage>
    {your page content here}
  </PluginPage>
);

Grafana 会查看 URL 以确定在部分导航中应激活哪些插件和页面。相应地，此组件仅适用于您在 plugin.json 中指定的页面。然后 PluginPage 将根据 plugin.json 中指定的页面名称渲染页面标题。

使用 PluginPage 为未在 plugin.json 中定义的页面​

PluginPage 组件还公开了一个 pageNav 属性，它是一个 NavModelItem。这个 pageNav 属性对于未在 plugin.json 中定义的页面非常有用（例如，单个项目页面）。你指定在 pageNav 模型中的 text 和 description 用于填充面包屑和页面标题。

示例

const pageNav = {
  text: 'Write errors cortex-prod-04',
  description: 'Incident timeline and details'
};

return (
  <PluginPage pageNav={pageNav}>
    {your page content here}
  </PluginPage>
);

在面包屑和部分导航中匹配活动页面的方式依赖于页面路由的层次结构。如果你有一个列表页面和一个项目页面，那么你需要将项目页面作为列表页面的子路由。此外，你还需要在 plugin.json 中指定列表页面 URL。

例如，你可能有一个在 /users 的用户列表。这意味着特定用户的页面需要位于 /users/:id。这可能需要对您的路由进行一些重构。

使用带选项卡的 PluginPage​

您还可以通过在 pageNav 模型中指定 children 来创建一个具有选项卡导航的页面，以创建更深层级的层次结构。

示例

const pageNav = {
  text: 'My page',
  description: 'Incident timeline and details',
  url: '/a/myorgid-pluginname-app',
  children: [
    {
      url: '/a/myorgid-pluginname-app/tab1',
      text: 'Tab1',
      active: true,
    },
    {
      url: '/a/myorgid-pluginname-app/tab2',
      text: 'Tab1',
    },
  ],
};

return (
  <PluginPage pageNav={pageNav}>
    {your page content here}
  </PluginPage>
);

以向后兼容的方式使用 PluginPage​

如果您想与 Grafana 的旧版本保持向后兼容，一种方法是实现一个 PluginPage 包装器。如果 PluginPage 可用且 topnav 功能已启用，则使用真实的 PluginPage。在其他场景中，回退到每个插件当前正在执行的操作（例如，调用 onNavChanged）。

示例

import { PluginPageProps, PluginPage as RealPluginPage, config } from '@grafana/runtime';

export const PluginPage = RealPluginPage && config.featureToggles.topnav ? RealPluginPage : PluginPageFallback;

function PluginPageFallback(props: PluginPageProps) {
  return props.children;
}

根据 config.features.topnav 是否为 true 来隐藏或显示选项卡需要额外的步骤（和 if 块）。您的插件需要在 useNavModel.ts 文件中包含这些更改

// useNavModel.ts

import { config } from '@grafana/runtime';

...

export function useNavModel({ meta, rootPath, onNavChanged }: Args) {
const { pathname, search } = useLocation();
useEffect(() => {
  if (config.featureToggles.topnav) {
    return;
  }
}, [config]);

...

Go 插件 SDK 中的转发 HTTP 头​

我们建议在检索转发 HTTP 头时使用 <request>.GetHTTPHeader 或 <request>.GetHTTPHeaders 方法。请参阅为登录用户转发 OAuth 身份、为登录用户转发 cookies 或 为登录用户转发用户头 的示例用法。

技术细节​

Go版本的Grafana SDK v0.147.0 引入了一个新的接口 ForwardHTTPHeaders，该接口由 QueryDataRequest、CheckHealthRequest 和 CallResourceRequest 实现。

在Grafana v9.4.0中引入的新转发HTTP头包括 X-Grafana-User、X-Panel-Id、X-Dashboard-Uid、X-Datasource-Uid 和 X-Grafana-Org-Id。在内部，我们使用前缀 http_ 来表示这些头，并在 CheckHealthRequest.Headers 和 QueryDataRequest.Headers 中发送为 http_<HTTP header name>。

我们建议使用 ForwardHTTPHeaders 方法，以确保您能够在不使用前缀的情况下操作HTTP头。也就是说，您可以操作 X-Grafana-User、X-Panel-Id、X-Dashboard-Uid、X-Datasource-Uid 和 X-Grafana-Org-Id。