使用 API 建立及管理資訊主頁

Cloud Monitoring API 中的 Dashboard 資源可讓您以程式輔助方式，大規模建立及管理自訂資訊主頁和其小工具。您可以使用 Google Cloud CLI、Terraform 或 REST 呼叫 create、list、get、patch 和 delete 方法，管理自訂資訊主頁。

您無法使用 API 擷取、編輯或刪除預先定義的資訊主頁。如要瞭解如何使用 Google Cloud 控制台建立及管理自訂資訊主頁，請參閱「建立及管理自訂資訊主頁」。

關於資訊主頁

建立資訊主頁時，您必須指定要顯示的元件或「小工具」，以及這些小工具的「版面配置」。您也可以在資訊主頁中新增標籤和篩選器。標籤可協助您找到資訊主頁，或指出資訊主頁上的內容類型。

資訊主頁版面配置

版面配置定義資訊主頁元件的排序方式。API 提供下列版面配置：

  • GridLayout：將可用空間劃分為寬度相等的垂直欄，並使用資料列優先策略排列一組小工具。

  • MosaicLayout：將可用空間劃分為格線。每個小工具可佔用一或多個格線區塊。

  • RowLayout：將可用空間分成多列，並在每列中水平排列一組小工具。

  • ColumnLayout：將可用空間分成垂直欄，並在各欄中垂直排列一組小工具。

舉例來說，以下是 RowLayout 中資訊主頁的 JSON 表示法，其中包含三個 Text 小工具：

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

資訊主頁小工具

小工具包含單一資訊主頁元件，以及如何在資訊主頁中呈現元件的設定。一個資訊主頁可以有多個小工具。Widget 物件有多種類型：

  • XyChart 小工具：在 X 軸和 Y 軸上顯示資料。

    這個小工具會顯示資料集，可能是時間序列資料，也可能是由 SQL 查詢生成。這個小工具可讓您將圖表資料與左側或右側 Y 軸建立關聯。如果圖表有多個指標類型，則可同時使用兩個 Y 軸。XyChart 小工具支援下列顯示樣式：

    • 折線圖
    • 長條圖
    • 堆疊面積圖
    • 熱視圖

    您可以指定 XyChart 個小工具的時間範圍。這項設定會覆寫資訊主頁層級的設定。如果您希望某個圖表顯示的時間範圍比其他資訊主頁小工具更長或更短，可以設定圖表的時間範圍覆寫。如需範例，請參閱「含有設定時間範圍覆寫的 XyChart 小工具的資訊主頁」。

  • 顯示單一維度的小工具，例如最新值：

    • PieChart：顯示一組時間序列的最新值，其中每個時間序列都會在圓餅圖中占有一塊。

    • Scorecard：顯示一個時間序列的最新值，以及這個值與一或多個門檻的關係。

    • TimeSeriesTable：顯示每個時間序列的最新值或匯總值。表格支援自訂功能。例如，您可以為儲存格設定顏色代碼，以及設定資料欄名稱和資料對齊方式。

  • 顯示警告政策或警告資訊的小工具：

    • AlertChart：顯示單一條件警告政策的摘要。這個小工具會以折線圖顯示資料、門檻，以及待處理警告的數量。

    • IncidentList：顯示快訊清單。您可以設定小工具，顯示特定警告政策或特定資源類型的警告。

  • 顯示記錄項目和錯誤的小工具：

  • 顯示追蹤記錄資料的小工具：

    • XyChart 小工具：在 X 軸和 Y 軸上顯示資料。

    • TimeSeriesTable：顯示最新值或匯總值。表格支援自訂功能。

  • 文字和組織小工具：

    • CollapsibleGroup：顯示小工具集合。您可以收合群組檢視畫面。

    • SingleViewGroup：在小工具集合中顯示一個小工具。你可以選取要顯示的小工具。

    • SectionHeader：在資訊主頁中建立水平分隔線，並在資訊主頁的目錄中建立項目。

    • Text：以原始文字或 Markdown 字串的形式顯示文字內容。

    如要在資訊主頁中加入文字和組織小工具，資訊主頁必須有 MosaicLayout。

除了這些物件外，您也可以在資訊主頁中新增空白預留位置。

舉例來說，以下是已設定右 Y 軸的 XyChart 小工具 JSON 表示法：

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

資訊主頁標籤

標籤可協助您管理及整理資訊主頁。舉例來說，您可以新增名為 prod 的標籤，指出資訊主頁會顯示正式版資源的時間序列資料和記錄資料。或者，您也可以新增 playbook 標籤，表示資訊主頁包含可協助您排解故障的資訊。

您可以選擇是否要為資訊主頁新增標籤。

舉例來說，下列 Dashboard 物件指定了名為 playbook 的標籤。

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

如前一個範例所示，labels 欄位是以 map 實作，其中 key 和 value 欄位都是字串。在資訊主頁中新增標籤時，請將 key 設為標籤名稱，並將 value 欄位設為空字串。

資訊主頁篩選器和變數

設計資訊主頁時，您可能會發現有多種方式可以查看資訊主頁顯示的資料。舉例來說，假設資訊主頁顯示虛擬機器 (VM) 執行個體的時序資料。您可能想查看所有 VM 的時間序列資料，也可能只想查看特定可用區中的資料。在這種情況下，建議您建立固定篩選器或變數，然後將該篩選器的預設值設為最常查看的可用區。

固定的篩選器會套用至所有支援篩選器指定標籤的資訊主頁小工具，除非小工具包含具有相同標籤鍵的篩選器。舉例來說，如果圖表包含篩選器 zone = us-central1-a，則該圖表會忽略標籤鍵為 zone 的固定篩選器。同樣地，如果圖表沒有標籤，且標籤的鍵為 zone，則系統會忽略這個篩選器。

變數類似於固定的篩選器，但只適用於特定小工具。變數可以根據標籤，也可以只有值。僅限值的變數包含一或多個預設值，以及所有可能值的清單。如未指定預設值，則預設值會設為萬用字元運算子 (*)。如要定義所有可能值的組合，您可以提供值陣列，或編寫 SQL 查詢。

如果您建立固定的篩選器或變數，Monitoring 會更新自訂資訊主頁的工具列，顯示篩選器。如果是固定的篩選器，工具列篩選器的名稱就是固定篩選器的名稱。如果是變數，工具列篩選器的名稱是貨幣符號 $，後面加上變數名稱。每個工具列篩選器都包含一個選單，可讓您變更相關聯固定篩選器或變數的值。如果是變數，您可以使用資訊主頁小工具取代工具列篩選器。詳情請參閱「包含 FilterControl 小工具的資訊主頁」。

如果是查詢資料的小工具，您可以在小工具的查詢中加入變數，並使用變數控制小工具的顯示設定。如果查詢取決於變數，則變更變數值時，小工具要求的資料也會隨之變更。因此顯示的資料也會隨之變更。使用變數控制小工具的顯示設定時，工具列會顯示 「Visible」(顯示) 圖示。如要瞭解瀏覽權限相關限制，請參閱「設定小工具的瀏覽權限」。

固定篩選器和變數會使用相同的資料結構。詳情請參閱「DashboardFilter」。

如需透過範例瞭解如何使用變數控管小工具的顯示設定，請參閱「已設定小工具顯示設定的資訊主頁」。

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

建立篩選器和變數

控制台

如要瞭解如何使用 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" ]
},

  • 選用：如要指定僅限值變數的所有可能值清單，請設定 stringArray 欄位或 timeSeriesQuery 欄位。如果指定查詢，則必須是數據分析查詢。

舉例來說，請參考以下 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 子句，請按照下列步驟操作：

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

  4. 將複製的程式碼貼到「Query」(查詢) 窗格中，並視需要進行編輯。

    舉例來說，假設您建立名為 LogName 的變數，用於產生記錄檔名稱清單，並將結果輸出至含有單一 log_name 資料欄的資料表。接著，您建立圖表，選取「Insert variable filter」(插入變數篩選器)，然後選取變數 LogName。系統會產生下列程式碼：

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    在這個範例中，您需要編輯生成的程式碼，並將 LogName = 替換為 log_name =，以便彙整資料表：

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. 依序點選「執行」和「套用」。

  6. 如要儲存修改後的資訊主頁，請按一下工具列中的「Save」(儲存)。

REST

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

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))

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

含有 Monitoring 篩選器查詢的圖表

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

控制台

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

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

  1. 編輯圖表。
  2. 在查詢窗格中，按一下「Add filter」(新增篩選器)，然後選取標籤鍵。例如，您可以選取「zone」(可用區)。
  3. 在「值」選單中，選取僅限值的變數。
  4. 按一下「套用」。
  5. 如要儲存修改後的資訊主頁，請按一下工具列中的「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} * ".*"

事前準備

在要建立或管理資訊主頁的 Google Cloud 專案中，完成下列操作：

gcloud

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

Terraform

如要在本機開發環境中使用本頁的 Terraform 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

  1. 安裝 Google Cloud CLI。

  2. 若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  3. 如果您使用的是本機殼層，請為使用者帳戶建立本機驗證憑證： 

    gcloud auth application-default login

    如果您使用的是 Cloud Shell，則不必執行這項操作。

    如果系統傳回驗證錯誤，且您使用的是外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「 為本機開發環境設定 ADC」。

REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

    安裝 Google Cloud CLI。

    若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。

建立資訊主頁

如要建立新的自訂資訊主頁，請叫用 dashboards.create 方法，並提供要在資訊主頁中顯示的版面配置和小工具。

name 欄位為選填。name 欄位的值具有下列結構：

"name": "projects/PROJECT_ID_OR_NUMBER/dashboards/DASHBOARD_ID"

建立資訊主頁時，API 會自動產生 DASHBOARD_ID 元件。如要指定自訂 DASHBOARD_ID，可以指定 Dashboard 物件的 name 欄位。

gcloud

如要在專案中建立資訊主頁，請使用 gcloud monitoring dashboards create 指令。

gcloud monitoring dashboards create --config-from-file=my-dashboard.json --project=PROJECT_ID

執行上述指令前，請先替換下列項目：

  • PROJECT_ID：專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

舉例來說，如要複製資訊主頁，請按照下列步驟操作：

  1. 完成「取得資訊主頁」中的步驟，下載原始資訊主頁的定義。
  2. 編輯傳回的 JSON，移除 etag 和 name 欄位，並變更 displayName 欄位的值。
  3. 執行指令來建立資訊主頁。

詳情請參閱 gcloud monitoring dashboards create 參考資料。

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。詳情請參閱 Terraform 供應商參考文件。

如要使用 Terraform 建立資訊主頁，請按照下列步驟操作：

  1. 為專案安裝及設定 Terraform。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

  2. 使用 Terraform 資源 google_monitoring_dashboard。

    在指令中設定下列欄位：

    • dashboard_json：資訊主頁的 JSON 表示法，使用 Dashboard 格式。

      如需這種格式的範例，您可以使用 APIs Explorer 列出資訊主頁，也可以在 Google Cloud 控制台中開啟資訊主頁，並查看 JSON 表示法。

    • parent：專案的完整名稱。舉例來說，您可以將這個欄位設為 "projects/PROJECT_ID"，其中 PROJECT_ID 是 Google Cloud 專案的 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

REST

如要建立新的資訊主頁，請將 POST 要求傳送至 Dashboard 端點。

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

執行上述指令前，請先完成下列設定：

  • ${PROJECT_ID}：環境變數，用於儲存要建立資訊主頁的專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

這些範例會使用 my-dashboard.json 檔案建立範例資訊主頁。您可以透過Google Cloud 控制台管理資訊主頁。

如需其他資訊主頁設定，請參閱「資訊主頁和版面配置範例」。

刪除資訊主頁

如要刪除自訂資訊主頁，請叫用 dashboards.delete 方法，並指定要刪除的資訊主頁。

gcloud

如要刪除自訂資訊主頁，請使用 gcloud monitoring dashboards delete，並指定要刪除的資訊主頁完整 ID：

gcloud monitoring dashboards delete DASHBOARD_ID --project=PROJECT_ID

執行上述指令前，請先替換下列項目：

  • PROJECT_ID：專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
  • DASHBOARD_ID：資訊主頁的 ID。

詳情請參閱 gcloud monitoring dashboards delete 參考資料。

Terraform

您可以使用 Terraform 刪除資源。如要瞭解如何刪除資源，請參閱 Terraform 指令 destroy。

REST

如要刪除自訂資訊主頁，請將 DELETE 要求傳送至 Dashboard 端點，並指定要刪除的資訊主頁 ID。

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

執行上述指令前，請先完成下列設定：

  • ${PROJECT_ID}：環境變數，用於儲存要建立資訊主頁的專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
  • ${DASHBOARD_ID}：儲存資訊主頁 ID 的環境變數。

如果成功，方法會傳回空白回應。否則會傳回錯誤。

列出資訊主頁

如要列出專案中的所有自訂資訊主頁，請叫用 dashboards.list 方法並指定專案 ID。

gcloud

如要列出專案的所有自訂資訊主頁，請使用 gcloud monitoring dashboards list 指令：

gcloud monitoring dashboards list --project=PROJECT_ID

執行上述指令前，請先替換下列項目：

  • PROJECT_ID：專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

詳情請參閱 gcloud monitoring dashboards list 參考資料。

Terraform

您無法使用 Terraform 向專案傳送查詢，並取得資訊主頁清單做為回應。不過，您可以使用 Google Cloud 控制台查看這些資訊主頁。

REST

如要列出專案的所有自訂資訊主頁，請將專案 ID 傳送至 Dashboard 端點。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

執行上述指令前，請先完成下列設定：

  • ${PROJECT_ID}：環境變數，用於儲存要建立資訊主頁的專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

範例會傳回與專案相關聯的自訂資訊主頁。

將清單回應分頁

dashboards.list 方法支援分頁功能，可讓您一次取得一頁結果，而非一次取得所有結果。

gcloud

如要指定每頁的資源數量，請在指令中傳遞 --page-size 旗標。例如：

gcloud monitoring dashboards list --page-size=1 --project=PROJECT_ID

執行上述指令前，請先替換下列項目：

  • PROJECT_ID：專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

Terraform

您無法使用 Terraform 將查詢傳送至專案，並以分頁資訊主頁清單的形式傳回回應。不過，您可以使用 Google Cloud 控制台查看這些資訊主頁。

REST

如要取得結果清單的第一頁，請在要求中指定 pageSize 查詢參數：

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

執行上述指令前，請先完成下列設定：

  • ${PROJECT_ID}：環境變數，用於儲存要建立資訊主頁的專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

這個方法會傳回清單的第一頁和 nextPageToken。例如：

{
  "dashboards" : [
    {
      "displayName" : "Grid Layout Example",
      "gridLayout" : {
        "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
      }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

對於其餘的每個頁面，您必須在要求中加入對應的 nextPageToken。

取得資訊主頁

如要取得專案的特定自訂資訊主頁，請叫用 dashboards.get 方法，並指定資訊主頁 ID。

gcloud

如要取得特定自訂資訊主頁，請使用 gcloud monitoring dashboards describe 指令並指定資訊主頁 ID：

gcloud monitoring dashboards describe DASHBOARD_ID --format=json --project=PROJECT_ID

執行上述指令前，請先替換下列項目：

  • PROJECT_ID：專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
  • DASHBOARD_ID：資訊主頁的 ID。

指令會傳回要求的資訊主頁：

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

詳情請參閱 gcloud monitoring dashboards describe 參考資料。

Terraform

您無法使用 Terraform 將查詢傳送至專案，並以個別資訊主頁的形式接收回應。不過，您可以使用 Google Cloud 控制台查看這些資訊主頁。

REST

如要取得特定自訂資訊主頁，請將資訊主頁 ID 傳送至 Dashboard 端點。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

執行上述指令前，請先完成下列設定：

  • ${PROJECT_ID}：環境變數，用於儲存要建立資訊主頁的專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
  • ${DASHBOARD_ID}：儲存資訊主頁 ID 的環境變數。

在上述運算式中，${DASHBOARD_ID} 是儲存資訊主頁完整名稱的環境變數。

這個方法會傳回類似以下範例的回應：

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

更新資訊主頁

如要更新現有的自訂資訊主頁，請叫用 dashboards.patch 方法。如要取得目前的 etag 值，您可以叫用 dashboards.get 方法，並在回應中找到該值。

gcloud

如要更新自訂資訊主頁，請使用 gcloud monitoring dashboards update，指定要更新的資訊主頁 ID，並提供要對資訊主頁進行的變更。

gcloud monitoring dashboards update DASHBOARD_ID --config-from-file=my-updated-dashboard.json --project=PROJECT_ID

執行上述指令前，請先替換下列項目：

  • PROJECT_ID：專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
  • DASHBOARD_ID：資訊主頁的 ID。

詳情請參閱 gcloud monitoring dashboards update 參考資料。

上述範例會使用 my-updated-dashboard.json 檔案更新現有的自訂資訊主頁。回應包含新的 etag 值，是更新後的資訊主頁清單副本。

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。詳情請參閱 Terraform 供應商參考文件。

如要使用 Terraform 更新資訊主頁，請執行下列操作：

  1. 為專案安裝及設定 Terraform。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

  2. 使用 Terraform 資源 google_monitoring_dashboard。

    在指令中設定下列欄位：

    • dashboard_json：資訊主頁的 JSON 表示法，使用 Dashboard 格式。

    • parent：專案的完整名稱。舉例來說，您可以將這個欄位設為 "projects/PROJECT_ID"，其中 PROJECT_ID 是 Google Cloud 專案的 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。

REST

如要更新自訂資訊主頁，請傳送 PATCH 要求至 Dashboard 端點，並提供修訂後的 Dashboard 物件和最新 dashboards.get 回應中的 etag 值。

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

執行上述指令前，請先完成下列設定：

  • ${PROJECT_ID}：環境變數，用於儲存要建立資訊主頁的專案 ID。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
  • ${DASHBOARD_ID}：儲存資訊主頁 ID 的環境變數。

上述範例會使用 my-updated-dashboard.json 檔案更新現有的自訂資訊主頁。回應包含新的 etag 值，是更新後的資訊主頁清單副本。

後續步驟