Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建立及管理變數和固定篩選器

在 Cloud Monitoring 的自訂資訊主頁中，您可以透過工具列，使用固定的篩選器和變數，動態變更資訊主頁上顯示的資料，不必編輯個別小工具。固定的篩選器會套用至所有支援篩選器標籤的小工具，而變數則會套用至特定小工具，用於修改查詢或控制顯示設定。

本文說明如何在Google Cloud 控制台中，設定固定的篩選器和變數。如要使用 Cloud Monitoring API 設定篩選器，請參閱「使用 API 建立及管理資訊主頁：資訊主頁篩選器」。如要僅為目前的工作階段套用篩選條件或分組，請參閱「在自訂資訊主頁中新增臨時篩選條件」。

關於固定篩選器

固定的篩選器包含標籤、一或多個預設值，以及所有可能值的清單。所有可能值的清單會根據資訊主頁上顯示的時間序列資料動態衍生。

您無法將固定的篩選器套用至個別小工具。而是根據下列規則，判斷固定的篩選器是否能變更小工具顯示的資料：

如果小工具顯示的資料包含固定篩選器指定的標籤鍵，且小工具未指定該標籤鍵的值，則固定篩選器可以變更顯示的資料。

舉例來說，假設您新增了固定的篩選器 cluster_name: mycluster。接著，圖表會自動只顯示 cluster_name 標籤值為 mycluster 的時間序列。同樣地，記錄面板小工具的查詢會修改為 resource.labels."cluster_name"="mycluster"，圖表也會自動只顯示包含固定篩選器中標籤的時間序列。
如果小工具包含相同標籤鍵的篩選器，或小工具顯示的資料不含固定篩選器中指定的標籤鍵，小工具就會忽略固定篩選器。

在 API 中，固定篩選器是由 DashboardFilter 結構定義。舉例來說，下列結構定義了固定的篩選器。zone 標籤值為 us-central1-c 的時間序列符合固定的篩選器。

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL"
},

關於變數

與固定篩選器類似，變數有名稱和類型，以及一或多個預設值。不過，固定篩選器一律以標籤為依據，變數則不一定要依附標籤。

如要將變數套用至特定小工具，請修改小工具包含的查詢。

在資訊主頁工具列中，變數名稱前面會加上美元符號 $。如果同時看到「Visible」圖示，表示變數至少控制一個小工具的顯示設定。

使用者定義變數可以是標籤變數，也可以是僅包含值的變數：

標籤變數就像固定的篩選器。這些變數包含標籤鍵、一或多個預設標籤值，以及所有可能標籤值的清單。所有可能值的清單是根據資訊主頁上顯示的時間序列資料動態衍生。
僅限值的變數包含一或多個預設值，且可能會列出所有可能的值。如未指定預設值，系統會選取萬用字元運算子 (*) 做為預設值。如要定義所有可能值的組合，您可以提供值陣列，或編寫 SQL 查詢。

僅包含值的變數有三種：「Custom」(自訂)、「Text Input」(文字輸入) 和「SQL Query」(SQL 查詢)。
- 自訂：如要列舉所有可能值的清單，並設定一或多個預設值，請使用這個選項。舉例來說，您可以將所有可能值的清單設為 prod, staging, dev，並將預設值設為 prod。
- 文字輸入：如果不知道所有可能的值，請使用這個選項。建立這個變數時，您可以指定一或多個值。不過，您可以使用選單選項，新增適用於目前工作階段的新值。
- SQL 查詢：如要使用 SQL 查詢生成可能的值清單，請選取這個選項。這些變數適用於使用 Observability Analytics 建立的圖表。
  
  對於這些變數，請確保查詢結果是只有一欄的資料表，該欄的資料類型為字串，且資料表中的每一列都包含不重複的字串值：
```
SELECT log_name
FROM `VIEW`
GROUP BY log_name
```
  SQL 查詢不得依附變數。

系統定義的變數只有一個，即 @__project_id。這個變數只能用於 SQL 查詢的 FROM 子句。如要瞭解如何將這個變數套用至查詢，請參閱「使用 SQL 查詢的圖表」。

如要將變數套用至小工具，請更新小工具發出的查詢，或更新小工具的瀏覽權限。您隨時可以編輯小工具來更新查詢。不過，如果是標籤型變數和某些小工具類型，您可以透過選單選項更新查詢。如要控制顯示設定，請編輯小工具。詳情請參閱本文的下列章節：

更新小工具的查詢
設定小工具的顯示設定

在 API 中，變數是由 DashboardFilter 結構定義。舉例來說，下列結構定義了對 zone 資源標籤運作的變數 my_zone_variable。具有 zone 標籤且值為 us-central1-c 的時間序列會與變數相符。

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "templateVariable": "my_zone_variable",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL",
},

事前準備

在要設定固定篩選器和變數的 Google Cloud 專案中，完成下列步驟：

如要取得使用 Google Cloud 控制台新增或修改變數或固定篩選器所需的權限，請要求管理員授予您專案的「Monitoring 編輯者」(roles/monitoring.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如要進一步瞭解角色，請參閱「使用 Identity and Access Management 控管存取權」。

建立及固定篩選器

如要建立並固定篩選器，套用至所有支援篩選器的資訊主頁小工具，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁) 頁面：
前往「Dashboards」(資訊主頁)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要設定 App Hub，請選取 App Hub 主專案或管理專案。
選取資訊主頁，前往資訊主頁工具列，然後按一下「Settings」(設定)。
在「篩選器」部分，按一下「新增篩選器」。
按一下「標籤」圖示，然後選取標籤。例如，您可以選取 zone。
如要讓使用者從篩選器的值選單中選取多個值，請選取「複選」。如果未啟用「複選」，使用者只能從值選單中選取一個選項。
按一下「預設值」，然後選取標籤的預設值。如要比對所有值，請選取 *。

注意： 如果資訊主頁含有 PromQL 定義的圖表，篩選器的值選單可能不會載入，或選單可能不含正確的值。不過，您可以手動輸入篩選器值。

篩選器建立後，會新增至資訊主頁工具列。如要暫時變更篩選器值，請選取篩選器，然後從選單中選取所需項目。
依序點選「完成」和「套用」。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

建立變數

如要建立適用於特定資訊主頁小工具的變數，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁) 頁面：
前往「Dashboards」(資訊主頁)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要設定 App Hub，請選取 App Hub 主專案或管理專案。
選取資訊主頁，前往資訊主頁工具列，然後按一下「Settings」(設定)。
在「變數」部分，按一下「新增變數」。
選取變數類型，然後完成對話方塊。

注意： 如要讓使用者從變數的值選單中選取多個值，請選取「Multi-select」(多重選取)。如果未啟用「複選」，使用者只能從值選單中選取一個選項。

如要建立標籤式變數，請選取「標籤」。如要使用含有標籤鍵和標籤值的變數，且該變數可做為固定篩選器，請選取這個選項。所有可能值的清單會根據資訊主頁上顯示的時間序列資料動態衍生。在「Apply to charts」(套用至圖表) 選單中，您可以選取要由變數修改查詢的小工具。您也可以編輯小工具來更新查詢。

如果是僅限值的變數，您可以使用下列選項：
- SQL：如要使用 SQL 查詢結果產生所有可能值的清單，請選取這個選項。
  
  輸入一或多個預設值，並輸入 SQL 查詢，產生所有可能值的清單。請確認查詢結果是只有一欄的資料表，該欄的資料類型為字串，且資料表中的每一列都包含不重複的字串值。
- 自訂：如要同時指定可能值的清單和預設值，請使用這個選項。舉例來說，您可以將「Values」(值) 欄位設為 prod, staging, dev，並將「Default value」(預設值) 設為 prod。
- 文字輸入：如要指定預設套用的值清單，請使用這個選項。
依序點選「完成」和「套用」。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

Monitoring 會將變數新增至資訊主頁工具列。工具列上的名稱是美元符號 $，後面接著變數名稱。工具列包含一個選單，可讓您變更變數的值。
選用：將變數從資訊主頁工具列移至資訊主頁小工具。

您可以在資訊主頁中新增小工具，以便修改變數的值。如果進行這項變更，系統會移除工具列變數。不過，您可以將控制變數的小工具，放在受影響的小工具旁邊。如要瞭解如何進行這項變更，請參閱「新增小工具來管理變數值」。
將變數套用至小工具。如果您更新小工具的查詢，則變更變數值時，查詢會修改，小工具顯示的資料也會修改。您也可以使用變數控制是否顯示小工具。詳情請參閱本文的下列章節：
- 設定小工具的顯示設定
- 更新小工具的查詢

由於變數會套用至資訊主頁小工具的子集，因此您可能需要將變數的控制項和套用變數的小工具分組。例如，您可以建立可收合的群組，或在資訊主頁中建立變數選單和相關聯小工具的專屬區塊。這項策略也會移除不適用於所有小工具的變數，藉此簡化工具列。

如要使用資訊主頁小工具管理變數值，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁) 頁面：
前往「Dashboards」(資訊主頁)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要設定 App Hub，請選取 App Hub 主專案或管理專案。
在「Add widget」(新增小工具) 對話方塊中，前往「Layout」(版面配置) 區段，然後選取「Variable」(變數)。
填寫對話方塊，然後選取「儲存」。

資訊主頁會顯示小工具，讓您選取變數的值。您可以將這個小工具移至可收合群組，或重新調整小工具的位置。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

設定小工具的瀏覽權限

當小工具查詢資料時，您可以使用變數控制小工具是否顯示在資訊主頁上。舉例來說，假設資訊主頁包含一組顯示正式環境系統資料的小工具，以及另一組顯示測試環境系統資料的小工具。在開發期間偵錯時，您可能只想查看測試資料。只要使用變數設定資訊主頁小工具的瀏覽權限，即可在僅限正式環境資料、僅限測試環境資料和所有資料之間切換。

任何類型的變數都能控制小工具的顯示或隱藏狀態。

如要設定小工具的顯示設定，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁) 頁面：
前往「Dashboards」(資訊主頁)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
選取資訊主頁。
前往要設定顯示設定的小工具工具列，然後按一下「編輯」。
在「顯示」窗格中，展開「小工具顯示設定」。
選取變數並完成對話方塊。

注意： 「比較運算子」的值必須設為規則運算式。
依序點選「完成」和「套用」。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

資訊主頁會重新整理。如果資訊主頁上至少有一個小工具因顯示設定而隱藏，資訊主頁就會顯示橫幅。如要查看所有小工具，請按一下「顯示所有小工具」。

使用變數控制資訊主頁上至少一個小工具的顯示設定時，工具列中的變數名稱會加上「Visible」(顯示) 圖示。

限制

設定小工具的顯示設定時，請注意下列限制：

組織小工具 (例如可收合群組、區段標題和單一檢視畫面小工具) 一律會顯示。
您可以刪除小工具顯示設定控制項參照的變數。變數刪除動作也會移除對變數的所有參照。
並非所有資訊主頁都支援建立變數。不過，如果資訊主頁包含變數，您可以使用這些變數管理資訊主頁上小工具的顯示設定。

更新小工具的查詢

本節說明如何在小工具發出的查詢中加入變數。因此，當您變更變數的值時，查詢和小工具顯示的資料也會隨之修改：

如果圖表使用 SQL 或 PromQL 查詢，以及記錄面板小工具，則必須編輯小工具並修改查詢。本節將說明如何進行這些編輯。
如果圖表是透過選單或直接篩選器模式設定，當您使用「Apply to charts」(套用至圖表) 選單選取小工具時，Monitoring 會編輯查詢。或者，您也可以編輯小工具，前往「Filter」(篩選器) 欄位，然後選取變數。

如要瞭解如何使用標籤式變數或僅限值的變數更新小工具的查詢，請參閱下列各節：

參照變數的一般語法
「記錄」面板小工具
含有 PromQL 查詢的圖表
使用 SQL 查詢製作圖表
使用 Monitoring 篩選器查詢的圖表

使用選單型介面建立顯示時間序列資料的圖表時，系統會將您的選取項目轉換為 Monitoring 篩選器。

建立篩選器和變數

控制台

如要瞭解如何使用 Google Cloud 控制台建立固定的篩選器和變數，請參閱下列文件：

REST

如要定義固定的篩選器和變數，請使用 dashboardFilters 資料結構。

如要建立變數，請將 templateVariable 欄位的值設為變數名稱。如要建立固定篩選器，請省略這個欄位或將值設為空字串。
如要建立固定篩選器或標籤變數，您必須指定 labelKey 欄位。如要建立僅限值的變數，請省略這個欄位。
設定篩選器或變數的預設值。這個欄位的設定會決定使用者是否只能從值選單中選取一個選項，還是可以選取多個值。
如要設定單一預設值，並限制使用者只能在值選單中選取一個選項，請將 valueType 欄位設為 STRING，並設定 stringValue 欄位：
```
"valueType": "STRING",
"stringValue": "my-default-value",
```
如要設定至少一個預設值，並允許使用者在值選單中選取多個選項，請將 valueType 欄位設為 STRING_ARRAY，並設定 stringArrayValue 欄位。在以下範例中，有三個預設值。
```
"valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},
```
注意： 如未指定預設值，系統會自動選取萬用字元運算子 (*)。如要在記錄面板中使用變數，則必須使用規則運算式做為比較運算子。如果是 SQL 查詢，您必須使用 IF 陳述式。詳情請參閱「使用 SQL 查詢建立圖表」。
選用：如要指定僅限值變數的所有可能值清單，請設定 stringArray 欄位或 timeSeriesQuery 欄位。如果指定查詢，則必須是數據分析查詢。

注意： 建立固定篩選器或標籤式變數時，請勿設定 timeSeriesQuery 或 stringArray 欄位。所有可能值的組合會動態決定。

舉例來說，請參考以下 dashboardFilters 物件：

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

上述 JSON 定義了一個固定篩選器和兩個變數：

固定的篩選器具有 zone 標籤鍵，會顯示在工具列上。valueType 和 stringValue 欄位會指定單一預設值。詳情請參閱 dashboardFilters 資料結構的 API 參考資料頁面。
標籤變數的名稱為 my_label_based_variable，標籤鍵為 instance_id。這個變數的預設值會設為特定執行個體 ID。您也可以使用陣列設定預設值。工具列會顯示名稱為 my_label_based_variable 的篩選器。
僅限值的變數名稱為 my_value_only_variable。這個項目未指定預設值，因此系統會自動套用萬用字元運算子 (*)。此外，這個變數會使用 SQL 查詢，產生變數可能的值清單。

請注意，dashboardFilters 物件不會列出變數套用的小工具。而是更新小工具的查詢，使其依附於變數。

取消參照變數的一般語法

除了由 SQL 定義的小工具外，所有小工具都請使用下列語法，將變數套用至查詢：

如要套用標籤變數，並將標籤鍵和標籤值解析為查詢語言的有效篩選運算式，請使用 ${my_label_based_variable}。
如要僅套用標籤變數的值，請使用 ${my_label_based_variable.value}。比較時必須使用規則運算式。
如要僅套用僅限值變數的值，請使用 ${my_value_only_variable}。如果是僅包含值的變數，請勿加入 .value 子句。比較時必須使用規則運算式。

記錄面板小工具

如要將變數套用至記錄面板小工具，請更新查詢窗格。這些小工具的語法遵循「一般語法」中指定的語法。

控制台

舉例來說，下列查詢會使用規則運算式，將 jsonPayload.message 欄位的值與包含標籤變數值的字串值進行比較：

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"

再舉一個例子，假設有一個僅限值的變數 value_only_severity_variable，且在值選單中選取了三個值：ERROR、INFO 和 NOTICE。接著，在記錄面板小工具的查詢窗格中，新增下列內容：

severity =~ "${value_only_severity_variable}"

下圖顯示轉譯後的表單：

severity =~ "^(ERROR|INFO|NOTICE)$"

REST

舉例來說，下列 JSON 說明如何使用標籤變數更新記錄面板小工具的查詢：

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

舉例來說，下列查詢會使用規則運算式，將 jsonPayload.message 欄位的值與包含標籤變數值的字串值進行比較：

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
            resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

再舉一個例子，假設有一個僅限值的變數 value_only_severity_variable，且選單中選取了三個值：ERROR、INFO 和 NOTICE。接著，在記錄面板小工具的查詢窗格中，新增下列內容：

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

以下說明記錄面板小工具執行的查詢：

severity =~ "^(ERROR|INFO|NOTICE)$"

如果您已為記錄面板設定查詢，然後選取按鈕開啟 Logs Explorer，系統會在開啟 Logs Explorer 前解析變數。

下表說明記錄面板如何解析範例變數。如前所述，如果只使用變數的值，則必須使用規則運算式做為比較運算子：

語法	已選取值	已解析的記錄面板運算式
`${my_label_based_variable}`	`12345`	`resource.labels."instance_id"="12345"` 範例變數是以資源標籤 `instance_id` 為基礎。
`${my_label_based_variable}`	`*`	`""`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`12345`	`12345`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`*`	`.*`

含有 PromQL 查詢的圖表

如要更新含有 PromQL 查詢的圖表，使其依賴標籤式變數，請按照「一般語法」中的指引操作。

控制台

舉例來說，下列查詢會依賴標籤變數 my_label_based_variable，並解析為篩選運算式：

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

您也可以修改查詢，只解析變數的值。以下範例使用規則運算式，將標籤查詢的值與 instance_id 進行比較：

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${my_label_based_variable.value}"
}

如果只有值變數，請省略 .value 子句。舉例來說，如要使用僅包含值的變數依可用區篩選，查詢會包含類似下列內容：

zone=~"${my_value_only_variable}"

REST

舉例來說，下列 JSON 說明依賴標籤型變數 my_label_based_variable 的查詢，該變數會解析為篩選運算式：

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

您也可以修改查詢，只解析變數的值。以下範例使用規則運算式，將標籤查詢的值與 instance_id 進行比較：

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

如果只有值變數，請省略 .value 子句。舉例來說，如要使用僅包含值的變數依可用區篩選，查詢會包含類似下列內容：

zone=~\"${my_value_only_variable}\"

下表說明 PromQL 如何解析範例變數。如前所述，如果只使用變數的值，則必須使用規則運算式做為比較運算子：

語法	已選取值	已解析的 PromQL 運算式
`${my_label_based_variable}`	`12345`	`instance_id == '12345'` 範例變數是以資源標籤 `instance_id` 為基礎。
`${my_label_based_variable}`	`*`	`noop_filter=~".*"`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`12345`	`12345`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`*`	`.+`

使用 SQL 查詢的圖表

您可以在 SQL 查詢中的兩個位置使用變數：

FROM 子句可以依附於名為 @__project_id 的系統定義變數，該變數會解析為所選專案的值。
WHERE 子句可以依附於使用者定義變數。

更新 FROM 子句，使其依附於系統定義的變數

如果您建立資訊主頁範本，且這些範本會繪製 SQL 查詢結果，請將查詢中的專案 ID 替換為變數 @__project_id。在專案中安裝範本時，變數會自動解析為專案 ID。您不必手動編輯小工具和更新 FROM 子句。

以下說明依附於系統定義變數的 FROM 子句：

FROM `@__project_id.global._Default._Default`

FROM 子句不得依附於使用者定義變數。

更新 WHERE 子句，使其依附於使用者定義變數

本節說明如何更新 SQL 定義小工具的 WHERE 子句，使其依附於使用者定義變數。所有變數名稱的前面都要加上「at」符號，例如：@variable_name。如果是以標籤為基礎的變數，請在變數名稱 @my_label_based_variabe.value 後方加上 .value。

如果是 SQL 查詢，變數替換作業會依賴 BigQuery，且不會受到 SQL 注入攻擊。詳情請參閱「執行參數化查詢」。

控制台

由於 SQL 不會將萬用字元運算子解讀為「任何值」，因此建議您在 SQL 查詢中使用變數時，一律使用 IF 陳述式。以下範例說明資料類型為字串的純值變數用法：

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

如果變數的選單選項可讓使用者選取多個值，您必須使用 CAST 函式，將變數的值轉換為 GoogleSQL 資料類型。下列查詢說明瞭這個語法：

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

建議使用上述範例中的 IF 陳述式，因為 SQL 不會將萬用字元運算子解讀為「任何值」。因此，如果您省略 IF 陳述式並選取萬用字元運算子，查詢結果會是空白資料表。在第二個範例中，UNNEST 函式會將陣列轉換為資料表。

如要新增格式正確的 WHERE 子句，請按照下列步驟操作：

編輯小工具。
在工具列中，選取「Insert variable filter」(插入變數篩選器)，然後選取要更新 WHERE 子句的變數。
在隨即開啟的對話方塊中，查看產生的程式碼，然後按一下「Copy and close」(複製並關閉)。
將複製的程式碼貼到「Query」(查詢) 窗格中，並視需要進行編輯。

舉例來說，假設您建立名為 LogName 的變數，用於產生記錄檔名稱清單，並將結果輸出至含有單一 log_name 資料欄的資料表。接著，您建立圖表，選取「Insert variable filter」(插入變數篩選器)，然後選取變數 LogName。系統會產生下列程式碼：
```
WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
```
在這個範例中，您需要編輯生成的程式碼，並將 LogName = 替換為 log_name =，以便彙整資料表：
```
WHERE IF(@LogName = '*', TRUE, log_name = @LogName)
```
依序點選「執行」和「套用」。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

REST

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

舉例來說，下列部分 JSON 表示法代表顯示 SQL 查詢結果的圖表。為了支援依記錄名稱篩選結果，我們新增了 WHERE 子句，參照名為 LogName 的變數：

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

變數 LogName 也會發出查詢，判斷可能的記錄名稱清單：

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

如果變數的選單選項可讓使用者選取多個值，您必須使用 CAST 函式，將變數的值轉換為 GoogleSQL 資料類型。下列查詢說明瞭這個語法：

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

含有 Monitoring 篩選器查詢的圖表

如要更新以 Monitoring 篩選器形式呈現查詢的圖表，使其依賴標籤式變數，請按照「一般語法」一節的指引操作。

控制台

如果您使用 Google Cloud 控制台建立圖表，並使用選單導向介面，則可使用變數的「Apply to charts」(套用至圖表) 欄位，或編輯小工具並從「Filter」(篩選器) 選單中選取標籤式變數，更新圖表的查詢。「Filter」(篩選器) 選單會列出所有標籤變數和標籤鍵。

如要更新圖表的查詢，使其依據值變數，請按照下列步驟操作：

編輯圖表。
在查詢窗格中，按一下「Add filter」(新增篩選器)，然後選取標籤鍵。例如，您可以選取「zone」(可用區)。
在「值」選單中，選取僅限值的變數。
按一下「套用」。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

舉例來說，下列 JSON 說明依賴標籤變數 my_label_based_variable 的查詢，該變數會解析為篩選運算式：

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

如果小工具使用的查詢是 Monitoring 篩選器，就無法依標籤變數中的值篩選時間序列，但可以依僅包含值的變數篩選。舉例來說，下列查詢會根據僅包含值的變數值，顯示依 zone 篩選的查詢「Filters」欄位值：

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

REST

舉例來說，下列 JSON 說明依賴標籤變數 my_label_based_variable 的查詢，該變數會解析為篩選運算式：

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
              resource.type=\"gce_instance\"
              ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

如果小工具使用的查詢是 Monitoring 篩選器，就無法依標籤變數中的值篩選時間序列，但可以依僅包含值的變數篩選。舉例來說，下列查詢會根據僅限值的變數值，顯示依 zone 篩選的查詢 "filter" 欄位：

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

下表說明 Monitoring 篩選器如何解析範例變數。如前所述，如果只使用變數的值，則必須使用規則運算式做為比較運算子：

語法	已選取值	已解析的篩選運算式
`${my_label_based_variable}`	`12345`	`resource.instance_id == "12345"` 範例變數是以資源標籤 `instance_id` 為基礎。
`${my_label_based_variable}`	`*`	已省略
`${my_label_based_variable.value}`	`12345`	不支援
`${my_label_based_variable.value}`	`*`	不支援
`${my_value_based_variable}`	`12345`	`"12345"`
`${my_value_based_variable}`	`*`	`".*"`

修改固定的篩選器或變數

如要暫時變更資訊主頁工具列上顯示的任何固定篩選器或變數值，請按一下篩選器或變數的名稱，然後輸入值或從選單中選取。

如果資訊主頁包含顯示時間序列資料的表格，您可以使用儲存格的「Filter dashboard to this value」(依這個值篩選資訊主頁) 按鈕，新增暫時篩選器或修改永久篩選器和變數。選取這個按鈕後，系統會套用新的臨時篩選器，或更新現有篩選器或變數的值。如果資料表資料欄的標籤鍵與篩選器或變數的標籤鍵相符，現有的篩選器和變數就會更新。

如要變更固定篩選器或變數的設定，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁) 頁面：
前往「Dashboards」(資訊主頁)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要設定 App Hub，請選取 App Hub 主專案或管理專案。
在資訊主頁工具列中，按一下「設定」。
找出要修改的篩選器或變數，然後展開其定義。
完成修改後，按一下「套用」。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

刪除固定的篩選器或變數

如要刪除固定的篩選器或變數，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁) 頁面：
前往「Dashboards」(資訊主頁)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要設定 App Hub，請選取 App Hub 主專案或管理專案。
在資訊主頁工具列中，按一下「設定」。
找出要移除的篩選器或變數，然後按一下「Delete」(刪除)。
按一下「套用」。
如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

限制

資訊主頁層級篩選器會依據鍵/值組合篩選資料。如果資料不支援鍵/值組合或特定鍵，則不適用這些篩選器。舉例來說，您無法使用資訊主頁層級篩選器，修改追蹤記錄小工具顯示的資料。
如要將變數套用至小工具，您必須修改小工具的查詢。並非所有小工具都支援修改。

建立及管理變數和固定篩選器 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

關於固定篩選器

關於變數

事前準備

建立及固定篩選器

建立變數

新增小工具來管理變數值

設定小工具的瀏覽權限

限制

更新小工具的查詢

建立篩選器和變數

控制台

REST

取消參照變數的一般語法

記錄面板小工具

控制台

REST

含有 PromQL 查詢的圖表

控制台

REST

使用 SQL 查詢的圖表

控制台

REST

含有 Monitoring 篩選器查詢的圖表

控制台

REST

修改固定的篩選器或變數

刪除固定的篩選器或變數

限制

後續步驟

建立及管理變數和固定篩選器