工作簿文本参数

使用文本框参数可以方便地从工作簿用户那里收集文本输入。 当使用下拉列表收集输入不实际时(例如使用任意阈值或通用筛选器),就会使用它们。 通过使用工作簿,可以从查询中获取文本框的默认值。 此功能允许实现一些有意义的方案,例如根据指标的 p95 设置默认阈值。

文本框的常见用途是作为其他工作簿控件使用的内部变量。 使用查询来获取默认值,并使输入控件在读取模式下隐藏。 例如,你可能希望某个阈值来自公式(而不是来自用户),然后在后续查询中使用该阈值。

创建文本参数

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

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

  3. 在打开的新参数窗格中,输入:

    1. 参数名称:SlowRequestThreshold
    2. 参数类型:Text
    3. 必需:checked
    4. 从以下位置获取数据:None
  4. 选择“保存”以创建参数。

    Screenshot that shows the creation of a text parameter.

此屏幕截图显示了工作簿在读取模式下的外观:

Screenshot that shows a text parameter in read mode.

参数字段样式

文本参数支持以下字段样式:

  • 标准:单行文本字段。

    Screenshot that shows a standard text field.

  • 密码:单行密码字段。 密码值仅在键入时隐藏在 UI 中。 该值在引用时完全可以作为参数值访问。 当保存工作簿时,它以未加密的方式存储。

    Screenshot that shows a password field.

  • 多行:一个多行文本字段,支持以下语言的丰富 IntelliSense 和语法着色:

    • 文本
    • Markdown
    • JSON
    • SQL
    • TypeScript
    • KQL
    • TOML

    你还可以指定多行编辑器的高度。

    Screenshot that shows a multiline text field.

引用文本参数

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

  2. 在 KQL 框中添加以下片段:

    requests
    | summarize AllRequests = count(), SlowRequests = countif(duration >= {SlowRequestThreshold}) by name
    | extend SlowRequestPercent = 100.0 * SlowRequests / AllRequests
    | order by SlowRequests desc
    
  3. 结合查询控件使用值为 500 的文本参数有效运行以下查询:

    requests
    | summarize AllRequests = count(), SlowRequests = countif(duration >= 500) by name
    | extend SlowRequestPercent = 100.0 * SlowRequests / AllRequests
    | order by SlowRequests desc
    
  4. 运行查询以查看结果。

    Screenshot that shows a text parameter referenced in KQL.

注意

在前面的示例中,{SlowRequestThreshold} 表示一个整数值。 如果查询类似于 {ComputerName} 的字符串,则需要修改 Kusto 查询以添加引号 "{ComputerName}",使参数字段接受不带引号的输入。

使用查询设置默认值

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

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

  3. 在打开的新参数窗格中,输入:

    1. 参数名称:SlowRequestThreshold
    2. 参数类型:Text
    3. 必需:checked
    4. 从以下位置获取数据:Query
  4. 在 KQL 框中添加以下片段:

    requests
    | summarize round(percentile(duration, 95), 2)
    

    此查询将文本框的默认值设置为应用中所有请求的持续时间的 95%。

  5. 运行查询以查看结果。

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

    Screenshot that shows a text parameter with a default value from KQL.

注意

尽管此示例查询的是 Application Insights 数据,但该方法可用于任何基于日志的数据源,例如 Log Analytics 和 Azure Resource Graph。

添加验证

对于标准和密码文本参数,你可添加应用于文本字段的验证规则。 添加包含错误消息的有效正则表达式。 如果设置了消息,则当字段无效时,该消息将显示为错误。

如果选择了匹配项,则字段在值与正则表达式匹配时有效。 如果未选择匹配项,则字段在它与正则表达式不匹配时有效。

Screenshot that shows text validation settings.

设置 JSON 数据的格式

如果选择“JSON”作为多行文本字段的语言,则该字段将提供一个按钮用于设置其 JSON 数据的格式。 你也可以使用快捷方式“Ctrl + \”来设置 JSON 数据的格式。

如果数据来自某个查询,则你可以选择相应的选项来预先设置该查询返回的 JSON 数据的格式。

Screenshot that shows the option Pre-format JSON data.

后续步骤

Azure 工作簿入门