变量

变量用于参数化场景。它们是值的占位符，可以在查询、面板标题甚至自定义场景对象中使用。在官方 Grafana 文档中了解有关 Grafana 模板变量的更多信息。

支持的变量类型

Scenes 支持以下变量类型

查询变量 (QueryVariable) - 查询生成的数值列表，例如指标名称、服务器名称、传感器 ID、数据中心等。
数据源变量 (DataSourceVariable) - 定义给定类型的数据源列表。
自定义变量 (CustomVariable) - 手动定义变量选项，使用逗号分隔的列表。
常量变量 (ConstantVariable) - 定义一个常量值变量。
文本框变量 (TextBoxVariable) - 显示一个自由文本输入字段，带有可选的默认值。

向场景添加变量

按照以下步骤向场景添加变量。

步骤 1. 创建和自定义变量对象

从变量定义开始。以下代码创建一个变量，该变量从 Prometheus 数据源检索 prometheus_http_requests_total 指标的所有 handler 标签值

const handlers = new QueryVariable({
  name: 'handler',
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  query: {
    query: 'label_values(prometheus_http_requests_total,handler)',
  },
});

注意

上述代码块中使用的 datasource 指的是核心 Grafana Prometheus 数据源插件。请确保您的 Grafana 堆栈已安装并配置了此插件。query 属性与您在仪表板设置中查看仪表板 JSON 时在典型仪表板模板变量中看到的属性相同。

步骤 2. 配置场景以使用变量

使用 SceneVariableSet 对象为您的场景定义 $variables 属性

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  body: new SceneFlexLayout({
    children: [],
  }),
});

步骤 3. 在场景中显示变量选择器

使用 EmbeddedScene 的 controls 属性在场景顶部显示变量值选择器

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  body: new SceneFlexLayout({
    children: [],
  }),
  controls: [new VariableValueSelectors({})],
});

现在，场景顶部显示一个允许您更改变量值的选择器。

步骤 4. 在查询中使用变量

创建 SceneQueryRunner，它将查询 Prometheus 数据源并在查询中使用配置的变量

const queryRunner = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  queries: [
    {
      refId: 'A',
      range: true,
      format: 'time_series',
      expr: 'rate(prometheus_http_requests_total{handler="$handler"}[5m])',
    },
  ],
});

注意，Prometheus 查询的 expr 属性使用 $handler 变量。在官方 Grafana 文档中了解有关 Grafana 变量语法的更多信息。

步骤 5. 向场景添加数据

将上一步创建的 queryRunner 与场景连接

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  $data: queryRunner,
  body: new SceneFlexLayout({
    children: [],
  }),
  controls: [new VariableValueSelectors({})],
});

步骤 6. 向场景添加可视化

要使用 handler 变量显示查询结果，请使用 VizPanel 类向场景添加时间序列可视化

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  $data: queryRunner,
  body: new SceneFlexLayout({
    children: [
      new SceneFlexItem({
        body: PanelBuilders.timeseries().build(),
      }),
    ],
  }),
  controls: [new VariableValueSelectors({})],
});

使用场景顶部的选择器更改变量值，以查看可视化中更新的数据。

接下来，您将找到使用 QueryVariable 的场景的完整代码

const handlers = new QueryVariable({
  name: 'handler',
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  query: {
    query: 'label_values(prometheus_http_requests_total,handler)',
  },
});

const queryRunner = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  queries: [
    {
      refId: 'A',
      range: true,
      format: 'time_series',
      expr: 'rate(prometheus_http_requests_total{handler="$handler"}[5m])',
    },
  ],
});

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({
    variables: [handlers],
  }),
  $data: queryRunner,
  body: new SceneFlexLayout({
    children: [
      new SceneFlexItem({
        body: PanelBuilders.timeseries().build(),
      }),
    ],
  }),
  controls: [new VariableValueSelectors({})],
});

宏

变量系统支持各种内置宏，这些宏是变量表达式，无需包含任何其他变量即可使用。

全局宏

语法	描述
`${___url}`	当前 URL
`${__url.path}`	当前 URL，不带查询参数
`${__url.params}`	当前 URL 查询参数
`${__url.params:exclude:var-handler}`	当前 URL 查询参数，不带 `var-handler`
`${__url.params:include:var-handler,var-instance}`	当前 URL 查询参数，仅包含 `var-handler` 和 `var-instance`

使用类似于以下的字符串从表格创建到另一个页面的数据链接，并保留所有查询参数

/scene-x/my-drilldown-view/${__value.raw}${__url.params}

使用类似于以下的字符串使用新的查询参数更新当前场景 URL，或者在查询参数已存在时更新它

/my-scene-url${__url.params:exclude:drilldown-id}&drilldown-id=${__value.raw}

这将生成一个 URL，其中保留了 url 状态，但 drilldown-id 查询参数已更新为此特定数据链接的插值。

字段/系列宏

以下宏在数据链接和字段覆盖属性（如 displayName）中起作用。

语法	描述
`${__field.name}`	将插值到字段/系列名称
`${__field.labels.cluster}`	将插值到集群标签的值

值/行宏

以下宏在基于行和值的数据链接中起作用。

语法	描述
`${__value.text}`	适用于表格和其他呈现行/值的可视化中的数据链接
`${__value.raw}`	未格式化的值
`${__data.fields[0].text}`	将插值到同一行上第一个字段/列的值

源代码

查看示例源代码

支持的变量类型​

向场景添加变量​

步骤 1. 创建和自定义变量对象​

步骤 2. 配置场景以使用变量​

步骤 3. 在场景中显示变量选择器​

步骤 4. 在查询中使用变量​

步骤 5. 向场景添加数据​

步骤 6. 向场景添加可视化​

宏​

全局宏​

字段/系列宏​

值/行宏​

源代码​