工作簿文本参数Workbook text parameters

使用文本框参数可以方便地从工作簿用户那里收集文本输入。Textbox parameters provide a simple way to collect text input from workbook users. 无法使用下拉列表收集输入(例如任意阈值或常规筛选器)时,可以使用文本框参数。They are used when it is not practical to use a drop-down to collect the input (for example, an arbitrary threshold or generic filters). 工作簿允许作者从查询中获取文本框的默认值。Workbooks allow authors to get the default value of the textbox from a query. 这样,就可以实现一些有意义的方案,例如,根据指标的 p95 设置默认阈值。This allows interesting scenarios like setting the default threshold based on the p95 of the metric.

文本框的常见用途是可以充当其他工作簿控件使用的内部变量。A common use of textboxes is as internal variables used by other workbook controls. 若要起到这种效果,可以利用查询来获取默认值,并使输入控件在读取模式下隐藏。This is done by leveraging a query for default values, and making the input control invisible in read-mode. 例如,用户可能希望某个阈值来自公式(而不是来自用户),然后在后续查询中使用该阈值。For example, a user may want a threshold to come from a formula (not a user) and then use the threshold in subsequent queries.

创建文本参数Creating a text parameter

  1. 从编辑模式下的空工作簿开始操作。Start with an empty workbook in edit mode.

  2. 从工作簿内的链接中选择“添加参数”。Choose Add parameters from the links within the workbook.

  3. 单击蓝色的“添加参数”按钮。Click on the blue Add Parameter button.

  4. 在弹出的“新建参数”窗格中,输入:In the new parameter pane that pops up enter:

    1. 参数名称:SlowRequestThresholdParameter name: SlowRequestThreshold
    2. 参数类型:TextParameter type: Text
    3. 必需:checkedRequired: checked
    4. 从查询中获取默认值:uncheckedGet default value from query: unchecked
  5. 从工具栏中选择“保存”以创建参数。Choose 'Save' from the toolbar to create the parameter.

    显示如何创建文本参数的插图

这就是工作簿在读取模式下的外观。This is how the workbook will look like in read-mode.

显示处于读取模式的文本参数的插图

引用文本参数Referencing a text parameter

  1. 选择蓝色的 Add query 链接将查询控件添加到工作簿,然后选择 Application Insights 资源。Add a query control to the workbook by selecting the blue Add query link and select an Application Insights resource.

  2. 在 KQL 框中添加以下片段:In the KQL box, add this snippet:

    requests
    | summarize AllRequests = count(), SlowRequests = countif(duration >= {SlowRequestThreshold}) by name
    | extend SlowRequestPercent = 100.0 * SlowRequests / AllRequests
    | order by SlowRequests desc
    
  3. 结合查询控件使用值为 500 的文本参数有效运行以下查询:By using the text parameter with a value of 500 coupled with the query control you effectively running the query below:

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

    显示 KQL 中引用的文本参数的插图

备注

在以上示例中,{SlowRequestThreshold} 表示一个整数值。In the example above, {SlowRequestThreshold} represents an integer value. 如果查询类似于 {ComputerName} 的字符串,则需要修改 Kusto 查询以添加引号 "{ComputerName}",使参数字段接受不带引号的输入。If you were querying for a string like {ComputerName} you would need to modify your Kusto query to add quotes "{ComputerName}" in order for the parameter field to an accept input without quotes.

设置默认值Setting default values

  1. 从编辑模式下的空工作簿开始操作。Start with an empty workbook in edit mode.

  2. 从工作簿内的链接中选择“添加参数”。Choose Add parameters from the links within the workbook.

  3. 单击蓝色的“添加参数”按钮。Click on the blue Add Parameter button.

  4. 在弹出的“新建参数”窗格中,输入:In the new parameter pane that pops up enter:

    1. 参数名称:SlowRequestThresholdParameter name: SlowRequestThreshold
    2. 参数类型:TextParameter type: Text
    3. 必需:checkedRequired: checked
    4. 从查询中获取默认值:checkedGet default value from query: checked
  5. 在 KQL 框中添加以下片段:In the KQL box, add this snippet:

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

    此查询将文本框的默认值设置为应用中所有请求的持续时间的 95%。This query sets the default value of the text box to the 95th percentile duration for all requests in the app.

  6. 运行查询以查看结果Run query to see the result

  7. 从工具栏中选择“保存”以创建参数。Choose 'Save' from the toolbar to create the parameter.

    显示包含 KQL 中的默认值的文本参数的插图

备注

尽管此示例查询的是 Application Insights 数据,但该方法可用于任何基于日志的数据源 - Log Analytics、Azure Resource Graph 等。While this example queries Application Insights data, the approach can be used for any log based data source - Log Analytics, Azure Resource Graph, etc.

后续步骤Next steps

  • 开始详细了解工作簿丰富的可视化效果选项。Get started learning more about workbooks many rich visualizations options.
  • 控制并共享对工作簿资源的访问权限。Control and share access to your workbook resources.