你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

工作簿下拉列表参数

通过使用下拉列表参数，可以从已知集中收集一个或多个输入值。 例如，可以使用下拉列表参数来选择应用的一个请求。 下拉列表参数还提供向用户收集任意输入的用户友好方式。 在交互式报表中启用筛选功能时，下拉列表参数特别有用。

指定下拉列表参数的最简单方法是在参数设置中提供一个静态列表。 更有意思的方法是通过 KQL 查询动态获取列表。 还可以使用参数设置指定是单选还是多选。 如果是多选，可指定结果集的格式，例如作为分隔符或引号。

下拉列表参数组件

使用静态 JSON 内容或从查询获取动态值时，下拉列表参数最多允许四个信息字段，具体顺序为：

1. value（必需）：数据中的第一列/字段用作参数的文本值。 对于简单的静态 JSON 参数，它可以像 JSON 内容["dev", "test", "prod"]一样简单，这将创建三个项的下拉列表，这些值同时作为值和下拉列表中的标签。 此字段的名称不需要为 value，无论名称如何，下拉列表都将使用数据中的第一个字段。

2. label（可选）：数据中的第二列/字段用作下拉列表中参数的显示名称/标签。 如果未指定，该值将用作标签。 此字段的名称不需要为 label，无论名称如何，下拉列表都将使用数据中的第二个字段。

3. selected（可选）：数据中的第三列/字段用于指定默认应选择的值。 如果未指定，则默认情况下未选择任何项。 选择行为基于 JavaScript“假”概念，因此将 0、false、null 或空字符串等值视为未选中。 此字段的名称不需要为 selected，无论名称如何，下拉列表都将使用数据中的第三个字段。

   注意

   这仅控制默认选择，一旦用户在下拉列表中选择了值，将使用这些用户选定的值。 即使后续对参数的查询运行并返回新的默认值也是如此。 若要返回默认选择，可以使用下拉列表中的“默认项”选项，这将重新查询默认值并应用它们。

   仅当用户未选择任何项时，才应用默认值。

   如果后续查询返回不包含以前选择的值的项，则会从所选内容中删除缺失值。 下拉列表中的选定项将成为查询返回的项和先前选择的项的交集。

4. group（可选）：与其他字段不同，分组列必须命名为 group，并在 value、label 和 selected 之后显示。 数据中的此字段用于对下拉列表中的项进行分组。 如果未指定，则不使用分组。 如果不需要默认选择，数据/查询仍必须至少返回一个对象/行中的 selected 字段，即使所有值都为 false。

注意

下拉列表参数将忽略数据中的其他任何字段。 建议将内容限制为仅下拉列表使用的字段，以避免返回忽略的数据的复杂查询。

创建静态下拉列表参数

1. 从编辑模式下的空工作簿开始操作。

2. 选择“添加参数”>“添加参数”。

3. 在打开的新参数窗格中，输入：

   1. 参数名称：Environment

   2. 参数类型：Drop down

   3. 必需：checked

   4. 允许多选：unchecked

   5. 从以下途径获取数据：JSON，或者选择 Query，并选择 JSON 数据源。

      JSON 数据源允许 JSON 内容引用任何现有参数。

4. 在“JSON 输入”文本块中，插入以下 JSON 片段：

   [
       { "value":"dev", "label":"Development" },
       { "value":"ppe", "label":"Pre-production" },
       { "value":"prod", "label":"Production", "selected":true }
   ]
   

5. 选择“更新”。

6. 选择“保存”以创建参数。

7. Environment 参数是包含三个值的下拉列表。

   

创建包含项组的静态下拉列表

如果查询结果/JSON 包含 group 字段，则下拉列表会显示值组。 请按照前面的示例，但改用以下 JSON：

[
    { "value":"dev", "label":"Development", "group":"Development" },
    { "value":"dev-cloud", "label":"Development (Cloud)", "group":"Development" },
    { "value":"ppe", "label":"Pre-production", "group":"Test" },
    { "value":"ppe-test", "label":"Pre-production (Test)", "group":"Test" },
    { "value":"prod1", "label":"Prod 1", "selected":true, "group":"Production" },
    { "value":"prod2", "label":"Prod 2", "group":"Production" }
]

注意

在查询中使用 group 字段时，还必须提供 label 和 selected 字段的值。

创建动态下拉列表参数

1. 从编辑模式下的空工作簿开始操作。

2. 选择“添加参数”>“添加参数”。

3. 在打开的新参数窗格中，输入：

   1. 参数名称：RequestName
   2. 参数类型：Drop down
   3. 必需：checked
   4. 允许多选：unchecked
   5. 从以下位置获取数据：Query

4. 在“JSON 输入”文本块中，插入以下 JSON 片段：

       requests
       | summarize by name
       | order by name asc
   

5. 选择“运行查询”。

6. 选择“保存”以创建参数。

7. RequestName 参数将是包含应用中所有请求的名称的下拉列表。

   

示例：自定义标签，默认选择第一项，并按操作名称分组

上述动态下拉列表参数中使用的查询只返回下拉列表中呈现的值列表。 如果想要其他显示名称，或者允许用户选择显示名称，请使用值、标签、选择和组列。

以下示例演示如何获取不同 Application Insights 依赖项的列表。 显示名称采用表情符号样式，默认选择第一项，项目按操作名称分组：

dependencies
| summarize by operation_Name, name
| where name !contains ('.')
| order by name asc
| serialize Rank = row_number()
| project value = name, label = strcat('🌐 ', name), selected = iff(Rank == 1, true, false), group = operation_Name

引用下拉列表参数

可以在能使用参数的任何位置引用下拉列表参数，包括将参数值替换为查询、可视化设置、Markdown 文本内容，或可以选择参数作为选项的其他位置。

在 KQL 中

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

2. 在 KQL 编辑器中输入此片段：

       requests
       | where name == '{RequestName}'
       | summarize Requests = count() by bin(timestamp, 1h)
   
   

3. 此片段可根据查询评估时间扩展为：

       requests
       | where name == 'GET Home/Index'
       | summarize Requests = count() by bin(timestamp, 1h)
   

4. 选择“运行查询”以查看结果。 （可选）以图表形式呈现结果。

   

下拉列表参数选项

参数	说明	示例
{DependencyName}	选定值	GET fabrikamaccount
{DependencyName:value}	所选值（与上述值相同）	GET fabrikamaccount
{DependencyName:label}	选定标签	🌐 GET fabrikamaccount
{DependencyName:escape}	所选值，与格式化为查询时被替换的任何常用引号字符	GET fabrikamaccount

多重选择

目前为止，示例将参数显式设置为仅选择下拉列表中的一个值。 下拉列表参数还支持多选。 若要启用此选项，请选择“允许多选”复选框。

可以通过分隔符和引号设置指定结果集的格式。 默认情况下，,（逗号）用作分隔符，'（单引号）用作引号字符。 当格式化为查询时，默认值以 'a', 'b', 'c' 的形式返回值作为集合。 还可以限制最大选择数。

在查询中使用多个选择参数时，请确保引用该参数的 KQL 适用于结果的格式。 例如：

• 单个值参数在格式化为查询时不包含任何引号，因此请确保在查询本身中包含引号，例如：where name == '{parameter}'。
• 使用多个选择参数时，引号包含在带格式的参数中，因此请确保查询不包含引号。 例如，where name in ({parameter})。

请注意此示例如何也从 name == 切换到 name in。 == 运算符仅允许单个值，而 in 运算符允许多个值。

dependencies
| where name in ({DependencyName})
| summarize Requests = count() by bin(timestamp, 1h), name

此示例显示了多选下拉列表参数的实际运用：

下拉列表特殊选择

下拉列表参数还允许指定也会显示在下拉列表中的特殊值：

• 任何 1 个
• 任何 3 个
• ...
• 任何 100 2上
• 任何自定义限制
• 全部

选择这些特殊项后，参数值会自动设置为具体的项数量，或所有值。

特殊大小写 All（所有），并允许将空选择视为“所有”

选择“所有”时，将显示一个附加字段，该字段允许指定“所有”参数的特殊值。 当“所有”是一个较大的项数量并会生成非常大的查询时，其非常有用。

在这种具体情况下，使用的是字符串 [] 而不是一个值。 此字符串可用于在日志查询中生成空数组，例如：

let selection = dynamic([{Selection}]);
SomeQuery 
| where array_length(selection) == 0 or SomeField in (selection)

如果选择了所有项，则 Selection 的值是 []，会在查询中为 selection 变量生成一个空数组。 如果未选择任何值，则 Selection 的值的格式为空的字符串，也会生成空数组。 如果选择了任何值，则会在查询的动态部分中设置这些值的格式，让数组中具有这些值。 然后，可以测试具有 0 的 array_length 是否拥有未应用的筛选器，或使用 in 运算符筛选数组中的值。

其他常见示例在需要参数时使用“*”作为特殊标记值，然后使用以下命令进行测试：

| where "*" in ({Selection}) or SomeField in ({Selection})

后续步骤

了解可用于通过 Azure 工作簿创建丰富视觉报表的可视化效果类型。