工作簿参数Workbook parameters

工作簿作者可以使用参数从使用者收集输入,并在工作簿的其他部分引用该输入 - 目的通常是限定结果集的范围或设置正确的视觉对象。Parameters allow workbook authors to collect input from the consumers and reference it in other parts of the workbook - usually to scope the result set or setting the right visual. 参数是一项重要功能,可让作者生成交互式报表和体验。It is a key capability that allows authors to build interactive reports and experiences.

使用工作簿可以控制如何向使用者呈现参数控件 - 文本框与下拉列表、单选与多选、文本中的值、JSON、KQL 或 Azure Resource Graph 等。Workbooks allow you to control how your parameter controls are presented to consumers - text box vs. drop down, single- vs. multi-select, values from text, JSON, KQL, or Azure Resource Graph, etc.

支持的参数类型包括:Supported parameter types include:

  • 时间 - 可让用户从预填充的时间范围中进行选择,或选择自定义范围Time - allows a user to select from prepopulated time ranges or select a custom range
  • 下拉列表 - 可让用户从一个值或一组值中进行选择Drop down - allows a user to select from a value or set of values
  • 文本 - 可让用户输入任意文本Text - allows a user to enter arbitrary text
  • 资源 - 可让用户选择一个或多个 Azure 资源Resource - allows a user to select one or more Azure resources
  • 订阅 - 可让用户选择一个或多个 Azure 订阅资源Subscription - allows a user to select one or more Azure subscription resources
  • 资源类型 - 可让用户选择一个或多个 Azure 资源类型值Resource Type - allows a user to select one or more Azure resource type values
  • 位置 - 可让用户选择一个或多个 Azure 位置值Location - allows a user to select one or more Azure location values

可以通过绑定或值扩展在工作簿的其他部分引用这些参数值。These parameter values can be referenced in other parts of workbooks either via bindings or value expansions.

创建参数Creating a 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. 参数名称:TimeRange(请注意,参数 名称不能 包含空格或特殊字符)Parameter name: TimeRange (note that parameter names cannot include spaces or special characters)
    2. 显示名称:Time Range(但是,显示名称 可以包括空格、特殊字符、表情符号等)Display name: Time Range (however, display names can include spaces, special characters, emoji, etc.)
    3. 参数类型:Time range pickerParameter type: Time range picker
    4. 必需:checkedRequired: checked
    5. 可用时间范围:过去 1 小时、过去 12 小时、过去 24 小时、过去 48 小时、过去 3 天、过去 7 天,以及允许自定义时间范围选择Available time ranges: Last hour, Last 12 hours, Last 24 hours, Last 48 hours, Last 3 days, Last 7 days and Allow custom time range selection
  5. 从工具栏中选择“保存”以创建参数。Choose 'Save' from the toolbar to create the parameter.

    显示创建时间范围参数的图像

这就是工作簿在读取模式下的“胶囊”式外观。This is how the workbook will look like in read-mode, in the "Pills" style.

在读取模式下显示时间范围参数的图像

引用参数Referencing a parameter

通过绑定的方式Via Bindings

  1. 在工作簿中添加查询控件,然后选择 Application Insights 资源。Add a query control to the workbook and select an Application Insights resource.

  2. 打开“时间范围”下拉列表,然后从底部的“参数”部分选择 Time Range 选项。Open the Time Range drop down and select the Time Range option from the Parameters section at the bottom.

  3. 这会将时间范围参数绑定到图表的时间范围。This binds the time range parameter to the time range of the chart. 现在示例查询的时间范围为“过去 24 小时”。The time scope of the sample query is now Last 24 hours.

  4. 运行查询以查看结果Run query to see the results

    显示通过绑定引用时间范围参数的图像

在 KQL 中In KQL

  1. 在工作簿中添加查询控件,然后选择 Application Insights 资源。Add a query control to the workbook and select an Application Insights resource.

  2. 在 KQL 中,输入使用以下参数的时间范围筛选器:| where timestamp {TimeRange}In the KQL, enter a time scope filter using the parameter: | where timestamp {TimeRange}

  3. 这会将查询计算时间扩大到 | where timestamp > ago(1d),这就是参数的时间范围值。This expands on query evaluation time to | where timestamp > ago(1d), which is the time range value of the parameter.

  4. 运行查询以查看结果Run query to see the results

    显示在 KQL 中引用时间范围的图像

在文本中In Text

  1. 向工作簿添加文件控件。Add a text control to the workbook.
  2. 在 Markdown 中,输入 The chosen time range is {TimeRange:label}In the markdown, enter The chosen time range is {TimeRange:label}
  3. 选择“完成编辑”Choose Done Editing
  4. 文本控件将显示文本:所选的时间范围为“过去 24 小时”The text control will show text: The chosen time range is Last 24 hours

参数选项Parameter options

“在文本中”部分使用了参数的 label 而不是其值。The In Text section used the label of the parameter instead of its value. 参数会根据其类型公开各种此类选项 - 例如,时间范围选取器允许值、标签、查询、开始时间、结束时间和粒度。Parameters expose various such options depending on its type - e.g. time range pickers allow value, label, query, start, end, and grain.

使用“编辑参数”窗格的 Previews 部分查看参数的扩展选项:Use the Previews section of the Edit Parameter pane to see the expansion options for your parameter:

显示时间范围参数选项的图像

后续步骤Next steps

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