工作簿参数

通过使用参数,可以从使用者收集输入,并在工作簿的其他部分引用该输入。 它通常用于限定结果集的范围或设置正确的视觉对象。 可以使用此关键功能生成交互式报表和体验。

使用工作簿时,可以控制参数控件呈现给使用者的方式。 它们可以是文本框与下拉列表、单选与多选,以及文本、JSON、KQL 或 Azure Resource Graph 中的值。

支持的参数类型包括:

  • 时间:允许你从预填充的时间范围中进行选择,或选择自定义范围
  • 下拉列表:允许你从一个值或一组值中进行选择
  • 选项组:允许你从已知集中选择一个值
  • 文本:允许你输入任意文本
  • 条件:允许你根据先前指定的参数定义一组条件,从而对这些条件进行计算以提供动态值
  • 资源:允许你选择一个或多个 Azure 资源
  • 订阅:允许你选择一个或多个 Azure 订阅资源
  • 多值:允许你设置一个或多个任意文本值
  • 资源类型:允许你选择一个或多个 Azure 资源类型值
  • 位置:允许你选择一个或多个 Azure 位置值

引用参数

可以使用绑定或值扩展在工作簿的其他部分引用参数值。

使用绑定引用参数

此示例演示如何通过绑定引用时间范围参数:

  1. 选择“添加查询”以添加查询控件,然后选择 Application Insights 资源。

  2. 打开“时间范围”下拉列表,然后从底部的“参数”部分选择“时间范围”选项:

    • 此选项会将时间范围参数绑定到图表的时间范围。
    • 现在示例查询的时间范围为“过去 24 小时”。
  3. 运行查询以查看结果。

    Screenshot that shows a time range parameter referenced via bindings.

使用 KQL 引用参数

此示例演示如何使用 KQL 引用时间范围参数:

  1. 选择“添加查询”以添加查询控件,然后选择 Application Insights 资源。

  2. 在 KQL 中,使用参数 | where timestamp {TimeRange} 输入时间范围筛选器:

    • 此参数可根据查询评估时间扩展为 | where timestamp > ago(1d)
    • 此选项是参数的时间范围值。
  3. 运行查询以查看结果。

    Screenshot that shows a time range referenced in the KQL query.

使用文本引用参数

此示例演示如何使用文本引用时间范围参数:

  1. 向工作簿添加文件控件。
  2. 在 Markdown 中,输入 The chosen time range is {TimeRange:label}
  3. 选择“完成编辑”。
  4. 文本控件将显示文本:所选的时间范围为“过去 24 小时”。

参数格式设置选项

每个参数类型都有自己的格式设置选项。 使用“编辑参数”窗格的“预览”部分查看参数的格式设置扩展选项。

Screenshot that shows time range parameter options.

可使用这些选项设置除时间范围选取器之外的所有参数类型的格式。 有关设置时间格式的示例,请参阅时间参数选项

其他参数类型包括:

  • 资源选取器:设置资源 ID 的格式。
  • 订阅选取器:设置订阅值的格式。

将 toml 转换为 json

语法{param:tomltojson}

原始值:

name = "Sam Green"

[address]
state = "New York"
country = "USA"

已设置格式的值:

{
  "name": "Sam Green",
  "address": {
    "state": "New York",
    "country": "USA"
  }
}

转义 JSON

语法{param:escapejson}

原始值:

{
	"name": "Sam Green",
	"address": {
		"state": "New York",
		"country": "USA"
  }
}

已设置格式的值:

{\r\n\t\"name\": \"Sam Green\",\r\n\t\"address\": {\r\n\t\t\"state\": \"New York\",\r\n\t\t\"country\": \"USA\"\r\n  }\r\n}

将文本编码为 base64

语法{param:base64}

原始值:

Sample text to test base64 encoding

已设置格式的值:

U2FtcGxlIHRleHQgdG8gdGVzdCBiYXNlNjQgZW5jb2Rpbmc=

使用 JSONPath 设置参数格式

对于作为 JSON 内容的字符串参数,可使用参数格式字符串中的 JSONPath

例如,你可能有一个名为 selection 的字符串参数,该参数是具有以下值的可视化效果中的查询或选择的结果:

{ "series":"Failures", "x": 5, "y": 10 }

通过使用 JSONPath,可从对象中获取单个值:

格式 结果
{selection:$.series} Failures
{selection:$.x} 5
{selection:$.y} 10

注意

如果参数值为无效 JSON,则格式的结果将为空值。

参数样式

以下样式可用于参数。

胶囊式

药丸样式是默认样式。 参数看起来像是文本,并要求用户选择参数一次才能进入编辑模式。

Screenshot that shows Azure Workbooks pills-style read mode.

Screenshot that shows Azure Workbooks pills-style edit mode.

标准

在标准样式中,控件始终可见,并在控件上方有一个标签。

Screenshot that shows Azure Workbooks standard style.

水平窗体

在水平样式窗体中,控件始终可见,并在控件左侧有标签。

Screenshot that shows Azure Workbooks form horizontal style.

垂直窗体

在垂直样式窗体中,控件始终可见,并在控件上方有标签。 与标准样式不同,它在一行中只有一个标签或控件。

Screenshot that shows Azure Workbooks form vertical style.

注意

在标准布局、水平窗体布局和垂直窗体布局中,没有直接编辑的概念。 控件始终处于编辑模式。

全局参数

了解参数的工作原理以及有关只能使用其设置位置的“下游”参数的限制之后,接下来可了解用于更改这些规则的全局参数。

使用全局参数时,仍必须先声明该参数后才能使用。 但为该参数设置值的任何步骤都会影响工作簿中该参数的所有实例。

注意

由于更改全局参数具有此“全部更新”行为,因此应仅对需要此行为的参数启用全局设置。 相互依赖的全局参数的组合可以创建一个循环或振荡,其中竞争的全局参数一遍又一遍地相互改变。 为了避免循环,不能“重新声明”已声明为全局的参数。 具有相同名称的参数的任何后续声明都将创建一个只读参数,该只读参数不可在该位置编辑。

全局参数的常见用途:

  1. 同步多个图表之间的时间范围:

    • 如果没有全局参数,任何图表中的时间范围刷都将仅在该图表之后导出。 因此,在第三个图表中选择时间范围只会更新第四个图表。
    • 使用全局参数,可创建一个全局 timeRange 参数,为其提供默认值,并让所有其他图表都将其用作它们的绑定时间范围和时间刷输出。 此外,需设置“仅在刷出范围后导出参数”设置。 任何图表中时间范围的任何更改都将更新工作簿顶部的全局 timeRange 参数。 此功能可用于让工作簿成为仪表板。
  2. 可通过链接或按钮在链接步骤中更改所选选项卡:

    • 如果没有全局参数,链接步骤仅输出所选选项卡的参数。
    • 使用全局参数,可以创建全局 selectedTab 参数。 然后,可以在链接步骤的选项卡选择中使用该参数名称。 可以将该参数值从链接传递到工作簿中,或通过使用其他按钮或链接来更改所选选项卡。以这种方式使用链接步骤中的按钮可获得类似于向导的体验,其中步骤底部的按钮会影响其上方的可见部分。

创建全局参数

在参数步骤中创建参数时,请在“高级设置”中使用“将此参数视为全局”选项。 创建全局参数的唯一方法是使用参数步骤来声明它。 创建参数的其他方法(通过选择、刷、链接、按钮、选项卡)只能更新全局参数。 它们本身不能声明一个全局参数。

Screenshot that shows setting global parameters in a workbook.

参数将可用,并可像正常参数一样运行。

更新现有全局参数的值

参照图表示例,更新全局参数的最常用方法是使用时间刷。

在此示例中,timeRange 参数被声明为全局。 在下面的查询步骤中,创建并运行在查询中使用该 timeRange 参数的查询并返回时间图表结果。 在查询步骤的“高级设置”中,启用时间范围刷设置。 使用与时间刷参数的输出相同的参数名称。 此外,需选择“仅在刷出范围后导出参数”选项。

Screenshot that shows the global time brush setting in a workbook.

每当在此图表中刷时间范围时,它也会更新此查询上方的 timeRange 参数和查询步骤本身(因为它也依赖于 timeRange)。

  1. 在刷之前:

    • 时间范围显示为“过去一小时”。
    • 图表显示过去一小时的数据。

    Screenshot that shows setting global parameters before brushing.

  2. 在刷期间:

    • 时间范围仍为过去一小时,并绘制刷轮廓。
    • 未更改参数。 释放时间刷之后,时间范围将更新。

    Screenshot that shows setting global parameters during brushing.

  3. 在刷后:

    • 由时间刷指定的时间范围由此步骤设置。 它替代全局值。 timeRange 下拉列表现在显示自定义时间范围。
    • 由于顶部的全局值已更改,并且此图表依赖于 timeRange 作为输入,因此图表中使用的查询的时间范围也会更新。 因此,查询和图表将更新。
    • 工作簿中依赖于 timeRange 的任何其他步骤也将更新。

    Screenshot that shows setting global parameters after brushing.

    注意

    如果不使用全局参数,则 timeRange 参数值将仅在此查询步骤下方更改。 此步骤上面的内容或此项本身不会更新。