共用方式為

活頁簿下拉式清單參數

  • 發行項

您可以使用下拉式清單參數，從已知集合收集一或多個輸入值。 例如，您可以使用下拉式清單參數來選取其中一個應用程式的要求。 下拉式清單參數提供使用者易記的方式，以收集使用者的任意輸入。 下拉式清單參數在互動式報告中啟用篩選特別實用。

指定下拉式清單參數最簡單的方式是在參數設定中提供靜態清單。 更有趣的方法是透過 KQL 查詢動態取得清單。 您也可以使用參數設定來指定其是單一或多重選取。 如果是多重選取，您可以指定結果集的格式，例如分隔符號或引號。

使用靜態 JSON 內容或從查詢取得動態值時，下拉式清單參數可依此特定順序允許最多四個資訊欄位：

  1. value (必要)：資料中的第一個資料行/欄位會用來做為參數的常值。 在簡單靜態 JSON 參數的情況下，其可與 JSON 內容 ["dev", "test", "prod"] 一樣簡單，這會建立三個項目的下拉式清單，其中的值會同時做為值和下拉式清單中的標籤。 此欄位的名稱不必為 value，無論名稱為何，下拉式清單都會使用資料中的第一個欄位。

  2. label (選擇性)：資料中的第二個資料行/欄位會用來做為下拉式清單中參數的顯示名稱/標籤。 如果未指定，則會使用值做為標籤。 此欄位的名稱不必為 label，無論名稱為何，下拉式清單都會使用資料中的第二個欄位。

  3. selected (選擇性)：資料中的第三個資料行/欄位是用來指定預設應選取的值。 如果未指定，預設不會選取任何項目。 選取行為是以 JavaScript "falsy" 概念為基礎，因此會將 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. [環境] 參數會是具有三個值的下拉式清單。

    顯示建立靜態下拉式清單參數的螢幕擷取畫面。

建立具有項目群組的靜態下拉式清單

如果您的查詢結果/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 相依性清單。 顯示名稱會以 emoji 設定樣式、預設會選取第一個項目，且項目會依作業名稱分組：

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. 選取 [執行查詢] 以查看結果。 選擇性地將其轉譯為圖表。

    顯示 KQL 中參考的下拉式清單參數的螢幕擷取畫面。

參數 描述 範例
{DependencyName} 選取的值 GET fabrikamaccount
{DependencyName:value} 選取的值 (與上述值相同) GET fabrikamaccount
{DependencyName:label} 選取的標籤 🌐 GET fabrikamaccount
{DependencyName:escape} 選取的值，在格式化為查詢時會取代任何通用引號字元 GET fabrikamaccount

多重選取

到目前為止，範例會明確設定參數，使其僅在下拉式清單中選取一個值。 下拉式清單參數也支援多重選取。 若要啟用此選項，選取 [允許多重選取] 核取方塊。

您可以透過 [分隔符號] 和 [引用] 設定來指定結果集的格式。 根據預設，會使用 , (逗號) 做為分隔符號，並使用 ' (單引號) 做為引號字元。 當格式化為查詢時，預設值會以 'a', 'b', 'c' 形式傳回值做為集合。 您也可以限制選取項目的數目上限。

在查詢中使用多個 select 參數時，請確定參考參數的 KQL 適用於結果的格式。 例如：

  • 單一值參數在格式化為查詢時，並不包含任何引號，因此請務必在查詢本身中包含引號，例如：where name == '{parameter}'。
  • 使用多個 select 參數時，引號會包含在格式化參數中，因此請確定查詢不包含引號。 例如： where name in ({parameter}) 。

另請注意此範例如何從 name == 切換為 name in。 == 運算子僅允許單一值，而 in 運算子則允許多個值。

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

此範例顯示工作的多重選取下拉式清單參數：

顯示多重選取下拉式清單參數的螢幕擷取畫面。

下拉式清單參數也可讓您指定也會出現在下拉式清單中的特殊值:

  • 任一個
  • 任三個
  • 任 100 個
  • 任何自訂限制
  • 全部

選取這些特殊項目時，參數值會自動設定為特定項目數目，或所有值。

特殊大小寫 All，並允許將空白選取項目視為 All

當您選取 [全部] 時，會出現額外的欄位，可讓您指定 [全部] 參數的特殊值。 這適用於「全部」可能是大量項目，而且可能會產生大量查詢的情況。

Azure 入口網站中 [新增參數] 視窗的螢幕擷取畫面。已選取 [全部] 選項，並醒目提示 [全部] 選項和 [全選] 值欄位。

在此特定案例中，會使用字串 [] 而不是值。 此字串可用來在記錄查詢中產生空陣列，例如:

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 活頁簿建立豐富視覺效果之報表的視覺效果類型。