添加变量支持

变量是值的占位符，你可以使用它们来创建模板化查询以及仪表盘或面板链接。有关变量的更多信息，请参阅模板和变量。

在本指南中，你将了解如何将这样的查询字符串

SELECT * FROM services WHERE id = "$service"

转换为

SELECT * FROM services WHERE id = "auth-api"

Grafana 提供了几个帮助函数来在字符串模板中插值变量。让我们看看如何在你的插件中使用它们。

将变量添加到插件

在面板插件中插值变量

对于面板，replaceVariables 函数在 PanelProps 中可用。

将 replaceVariables 添加到参数列表中，并将用户定义的模板字符串传递给它

export function SimplePanel({ options, data, width, height, replaceVariables }: Props) {
  const query = replaceVariables('Now displaying $service');

  return <div>{query}</div>;
}

在数据源插件中插值变量

对于数据源，你需要使用 getTemplateSrv，它返回一个 TemplateSrv 实例。

从 runtime 包导入 getTemplateSrv

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

在你的 query 方法中，调用 replace 方法，传入用户定义的模板字符串

async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse> {
  const query = getTemplateSrv().replace('SELECT * FROM services WHERE id = "$service"', options.scopedVars);

  const data = makeDbQuery(query);

  return { data };
}

从插件设置变量

你不仅可以读取变量的值，还可以从插件更新变量。使用 locationService.partial(query, replace)。

以下示例展示了如何更新名为 service 的变量。

query 包含你想要更新的查询参数。控制变量的查询参数以 var- 为前缀。
replace: true 告诉 Grafana 更新当前 URL 状态，而不是创建新的历史记录条目。

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

locationService.partial({ 'var-service': 'billing' }, true);

注意

每当你更新变量时，Grafana 都会查询你的数据源。过度更新变量可能会降低 Grafana 的速度并导致糟糕的用户体验。

为数据源添加查询变量支持

查询变量是一种允许你查询数据源以获取值的变量类型。通过为你的数据源插件添加查询变量支持，用户可以根据来自你的数据源的数据创建动态仪表盘。

让我们首先为变量查询定义一个查询模型

export interface MyVariableQuery {
  namespace: string;
  rawQuery: string;
}

要使数据源支持查询变量，请覆盖你的 DataSourceApi 类中的 metricFindQuery。metricFindQuery 函数返回一个 MetricFindValue 数组，该数组具有一个属性 text

async metricFindQuery(query: MyVariableQuery, options?: any) {
  // Retrieve DataQueryResponse based on query.
  const response = await this.fetchMetricNames(query.namespace, query.rawQuery);

  // Convert query results to a MetricFindValue[]
  const values = response.data.map(frame => ({ text: frame.name }));

  return values;
}

注意

默认情况下，Grafana 为简单的文本查询提供了一个基本的查询模型和编辑器。如果这已足够，则将查询类型保留为 string

async metricFindQuery(query: string, options?: any)

让我们创建一个自定义查询编辑器，允许用户编辑查询模型。

创建 VariableQueryEditor 组件

src/VariableQueryEditor.tsx
import React, { useState } from 'react';
import { MyVariableQuery } from './types';

interface VariableQueryProps {
  query: MyVariableQuery;
  onChange: (query: MyVariableQuery, definition: string) => void;
}

export const VariableQueryEditor = ({ onChange, query }: VariableQueryProps) => {
  const [state, setState] = useState(query);

  const saveQuery = () => {
    onChange(state, `${state.query} (${state.namespace})`);
  };

  const handleChange = (event: React.FormEvent<HTMLInputElement>) =>
    setState({
      ...state,
      [event.currentTarget.name]: event.currentTarget.value,
    });

  return (
    <>
      <div className="gf-form">
        <span className="gf-form-label width-10">Namespace</span>
        <input
          name="namespace"
          className="gf-form-input"
          onBlur={saveQuery}
          onChange={handleChange}
          value={state.namespace}
        />
      </div>
      <div className="gf-form">
        <span className="gf-form-label width-10">Query</span>
        <input
          name="rawQuery"
          className="gf-form-input"
          onBlur={saveQuery}
          onChange={handleChange}
          value={state.rawQuery}
        />
      </div>
    </>
  );
};

当任何文本字段失去焦点 (onBlur) 时，Grafana 会保存查询模型，然后预览由 metricFindQuery 返回的值。

onChange 的第二个参数允许你设置查询的文本表示，该文本将出现在变量列表中的变量名称旁边。

配置你的插件以使用查询编辑器

import { VariableQueryEditor } from './VariableQueryEditor';

export const plugin = new DataSourcePlugin<DataSource, MyQuery, MyDataSourceOptions>(DataSource)
  .setQueryEditor(QueryEditor)
  .setVariableQueryEditor(VariableQueryEditor);

就是这样！你现在可以通过向仪表盘添加查询变量来试用该插件。

使用模板变量

模板变量使用户能够创建根据用户输入动态更改的仪表盘。由于变量在 Grafana 中已经存在了很长时间，许多用户期望他们安装的任何数据源都支持变量。

插值模板变量

要插值模板变量，你需要从 @grafana/runtime 包导入 getTemplateSrv() 函数

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

getTemplateSrv() 函数返回一个 TemplateSrv 实例，该实例提供了处理模板变量的方法。其中最重要的是 replace()，它接受包含变量的字符串作为输入，并返回一个插值字符串，其中变量已替换为用户选择的值。

例如，如果你有一个名为 instance 的变量，以下代码将用其相应的值替换该变量

getTemplateSrv().replace("I'd like $instance, please!");

// I'd like server-1, please!

replace() 甚至可以处理内置变量，例如 $__from 和 $__to。

就是这样！对于大多数用例，这是你在数据源中添加模板变量支持所需做的全部工作。请注意，由你决定哪些字段将支持模板变量。例如，要在查询中插值单个属性 rawQuery，请添加以下内容

const interpolatedQuery: MyQuery = {
  ...query,
  rawQuery: getTemplateSrv().replace(query.rawQuery),
};

格式化多值变量

在上一个示例中，变量只有一个值 server-1。然而，如果用户创建的是多值变量，它可以同时包含多个值。多值变量带来了一个新的挑战：如何决定如何格式化一组值？

例如，以下哪种不同的格式适合你的用例？

{server-1, server-2, server-3} (Graphite)
["server-1", "server-2", "server-3"] (JSON)
("server-1" OR "server-2" OR "server-3") (Lucene)

幸运的是，replace() 方法允许你传递第三个参数，以便你可以从一组预定义格式中选择，例如 CSV 格式

getTemplateSrv().replace("I'd like $instance, please!", {}, 'csv');

// I'd like server-1, server-2, server-3, please!

注意

replace() 方法的第二个参数允许你配置一组自定义变量或作用域变量，以便在插值字符串时包含它们。如果你对此不感兴趣，可以传递一个空对象 {}。

Grafana 支持一系列格式选项。要浏览可用格式，请查看高级变量格式选项。

使用插值函数格式化变量

查看高级变量格式选项后，你可能会发现你想要支持一种不可用的格式选项。幸运的是，Grafana 允许你通过使用插值函数完全控制 replace() 如何格式化变量。

你可以将插值函数作为第三个参数传递给 replace()，而不是字符串。以下示例使用自定义格式化函数在最后一个元素之前添加 and

const formatter = (value: string | string[]): string => {
  if (typeof value == 'string') {
    return value;
  }

  // Add 'and' before the last element.
  if (value.length > 1) {
    return value.slice(0, -1).join(', ') + ' and ' + value[value.length - 1];
  }

  return value[0];
};

getTemplateSrv().replace("I'd like $instance, please!", {}, formatter);

// I'd like server-1, server-2, and server-3, please!

函数的参数可以是字符串或字符串数组（例如 (string | string[])），具体取决于变量是否支持多个值，因此在使用值之前务必检查类型。

在模板外部使用变量

有时你可能想在模板外部使用变量。例如，如果你想验证选定值的数量或将它们添加到下拉菜单中。

这个帮助函数使用 replace() 方法将值作为数组返回

function getValuesForVariable(name: string): string[] {
  const values: string[] = [];

  // Collects the values in an array.
  getTemplateSrv().replace(`$${name}`, {}, (value: string | string[]) => {
    if (Array.isArray(value)) {
      values.push(...value);
    } else {
      values.push(value);
    }

    // We don't really care about the string here.
    return '';
  });

  return values;
}
const instances = getValuesForVariable('instance');

for (var instance of instances) {
  console.log(instance);
}

// server-1
// server-2
// server-3

你甚至可以更进一步，创建一个整洁地包含所有变量及其值的对象

function getAllVariables(): Record<string, string[]> {
  const entries = getTemplateSrv()
    .getVariables()
    .map((v) => [v.name, getValuesForVariable(v.name)]);

  return Object.fromEntries(entries);
}
const vars = getAllVariables();

console.log(vars.instance);

// ["server-1", "server-2", "server-3"]

在此示例中，使用 getTemplateSrv().getVariables() 列出当前仪表盘配置的所有变量。

注意

你还可以根据可预测的分隔符分割插值字符串。请根据你的实际情况自由调整这些代码片段。

将变量添加到插件​

在面板插件中插值变量​

在数据源插件中插值变量​

从插件设置变量​

为数据源添加查询变量支持​

使用模板变量​

插值模板变量​

格式化多值变量​

使用插值函数格式化变量​

在模板外部使用变量​