工作簿参数
通过使用参数，可以从使用者收集输入，并在工作簿的其他部分引用该输入。 它通常用于限定结果集的范围或设置正确的视觉对象。 可以使用此关键功能生成交互式报表和体验。
使用工作簿时，可以控制参数控件呈现给使用者的方式。 它们可以是文本框与下拉列表、单选与多选，以及文本、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 参数值将仅在此查询步骤下方更改。 此步骤上面的内容或此项本身不会更新。