跳到主要内容

将插件从 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 中指定的页面名称渲染页面标题。

对于未在 plugin.json 中定义的页面，请使用 PluginPage​

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;
}

需要一个额外的步骤（和一个 if 块），以根据 config.features.topnav 是否为 true 来隐藏或显示选项卡。您的插件需要在 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 身份、为已登录用户转发 Cookie 或 为已登录用户转发用户标头。

技术细节​

Grafana Go 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 标头名称> 发送。

我们建议使用 ForwardHTTPHeaders 方法，以便保证您能够操作 HTTP 标头而无需使用前缀。也就是说，您可以操作 X-Grafana-User、X-Panel-Id、X-Dashboard-Uid、X-Datasource-Uid 和 X-Grafana-Org-Id。