工作簿参数
通过使用参数,可以从使用者收集输入,并在工作簿的其他部分引用该输入。 它通常用于限定结果集的范围或设置正确的视觉对象。 可以使用此关键功能生成交互式报表和体验。
使用工作簿时,可以控制参数控件呈现给使用者的方式。 它们可以是文本框与下拉列表、单选与多选,以及文本、JSON、KQL 或 Azure Resource Graph 中的值。
支持的参数类型包括:
- 时间:允许你从预填充的时间范围中进行选择,或选择自定义范围
- 下拉列表:允许你从一个值或一组值中进行选择
- 选项组:允许你从已知集中选择一个值
- 文本:允许你输入任意文本
- 条件:允许你根据先前指定的参数定义一组条件,从而对这些条件进行计算以提供动态值
- 资源:允许你选择一个或多个 Azure 资源
- 订阅:允许你选择一个或多个 Azure 订阅资源
- 多值:允许你设置一个或多个任意文本值
- 资源类型:允许你选择一个或多个 Azure 资源类型值
- 位置:允许你选择一个或多个 Azure 位置值
引用参数
可以使用绑定或值扩展在工作簿的其他部分引用参数值。
使用绑定引用参数
此示例演示如何通过绑定引用时间范围参数:
选择“添加查询”以添加查询控件,然后选择 Application Insights 资源。
打开“时间范围”下拉列表,然后从底部的“参数”部分选择“时间范围”选项:
- 此选项会将时间范围参数绑定到图表的时间范围。
- 现在示例查询的时间范围为“过去 24 小时”。
运行查询以查看结果。
使用 KQL 引用参数
此示例演示如何使用 KQL 引用时间范围参数:
选择“添加查询”以添加查询控件,然后选择 Application Insights 资源。
在 KQL 中,使用参数
| where timestamp {TimeRange}
输入时间范围筛选器:- 此参数可根据查询评估时间扩展为
| where timestamp > ago(1d)
。 - 此选项是参数的时间范围值。
- 此参数可根据查询评估时间扩展为
运行查询以查看结果。
使用文本引用参数
此示例演示如何使用文本引用时间范围参数:
- 向工作簿添加文件控件。
- 在 Markdown 中,输入
The chosen time range is {TimeRange:label}
。 - 选择“完成编辑”。
- 文本控件将显示文本:所选的时间范围为“过去 24 小时”。
参数格式设置选项
每个参数类型都有自己的格式设置选项。 使用“编辑参数”窗格的“预览”部分查看参数的格式设置扩展选项。
可使用这些选项设置除时间范围选取器之外的所有参数类型的格式。 有关设置时间格式的示例,请参阅时间参数选项。
其他参数类型包括:
- 资源选取器:设置资源 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,则格式的结果将为空值。
参数样式
以下样式可用于参数。
胶囊式
药丸样式是默认样式。 参数看起来像是文本,并要求用户选择参数一次才能进入编辑模式。
标准
在标准样式中,控件始终可见,并在控件上方有一个标签。
水平窗体
在水平样式窗体中,控件始终可见,并在控件左侧有标签。
垂直窗体
在垂直样式窗体中,控件始终可见,并在控件上方有标签。 与标准样式不同,它在一行中只有一个标签或控件。
注意
在标准布局、水平窗体布局和垂直窗体布局中,没有直接编辑的概念。 控件始终处于编辑模式。
全局参数
了解参数的工作原理以及有关只能使用其设置位置的“下游”参数的限制之后,接下来可了解用于更改这些规则的全局参数。
使用全局参数时,仍必须先声明该参数后才能使用。 但为该参数设置值的任何步骤都会影响工作簿中该参数的所有实例。
注意
由于更改全局参数具有此“全部更新”行为,因此应仅对需要此行为的参数启用全局设置。 相互依赖的全局参数的组合可以创建一个循环或振荡,其中竞争的全局参数一遍又一遍地相互改变。 为了避免循环,不能“重新声明”已声明为全局的参数。 具有相同名称的参数的任何后续声明都将创建一个只读参数,该只读参数不可在该位置编辑。
全局参数的常见用途:
同步多个图表之间的时间范围:
- 如果没有全局参数,任何图表中的时间范围刷都将仅在该图表之后导出。 因此,在第三个图表中选择时间范围只会更新第四个图表。
- 使用全局参数,可创建一个全局 timeRange 参数,为其提供默认值,并让所有其他图表都将其用作它们的绑定时间范围和时间刷输出。 此外,需设置“仅在刷出范围后导出参数”设置。 任何图表中时间范围的任何更改都将更新工作簿顶部的全局 timeRange 参数。 此功能可用于让工作簿成为仪表板。
可通过链接或按钮在链接步骤中更改所选选项卡:
- 如果没有全局参数,链接步骤仅输出所选选项卡的参数。
- 使用全局参数,可以创建全局 selectedTab 参数。 然后,可以在链接步骤的选项卡选择中使用该参数名称。 可以将该参数值从链接传递到工作簿中,或通过使用其他按钮或链接来更改所选选项卡。以这种方式使用链接步骤中的按钮可获得类似于向导的体验,其中步骤底部的按钮会影响其上方的可见部分。
创建全局参数
在参数步骤中创建参数时,请在“高级设置”中使用“将此参数视为全局”选项。 创建全局参数的唯一方法是使用参数步骤来声明它。 创建参数的其他方法(通过选择、刷、链接、按钮、选项卡)只能更新全局参数。 它们本身不能声明一个全局参数。
参数将可用,并可像正常参数一样运行。
更新现有全局参数的值
参照图表示例,更新全局参数的最常用方法是使用时间刷。
在此示例中,timeRange 参数被声明为全局。 在下面的查询步骤中,创建并运行在查询中使用该 timeRange 参数的查询并返回时间图表结果。 在查询步骤的“高级设置”中,启用时间范围刷设置。 使用与时间刷参数的输出相同的参数名称。 此外,需选择“仅在刷出范围后导出参数”选项。
每当在此图表中刷时间范围时,它也会更新此查询上方的 timeRange 参数和查询步骤本身(因为它也依赖于 timeRange)。
在刷之前:
- 时间范围显示为“过去一小时”。
- 图表显示过去一小时的数据。
在刷期间:
- 时间范围仍为过去一小时,并绘制刷轮廓。
- 未更改参数。 释放时间刷之后,时间范围将更新。
在刷后:
- 由时间刷指定的时间范围由此步骤设置。 它替代全局值。 timeRange 下拉列表现在显示自定义时间范围。
- 由于顶部的全局值已更改,并且此图表依赖于 timeRange 作为输入,因此图表中使用的查询的时间范围也会更新。 因此,查询和图表将更新。
- 工作簿中依赖于 timeRange 的任何其他步骤也将更新。
注意
如果不使用全局参数,则 timeRange 参数值将仅在此查询步骤下方更改。 此步骤上面的内容或此项本身不会更新。