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

本文說明如何使用 Cloud Monitoring API 中的 Dashboard 資源，建立及管理自訂資訊主頁和這些資訊主頁上的小工具。以下範例說明如何使用 curl 叫用 API 來管理資訊主頁，以及如何使用 Google Cloud CLI。您也可以透過Google Cloud 控制台管理自訂資訊主頁，但 API 提供以程式輔助的方式，同時管理多個資訊主頁。

這個端點支援下列方法，可管理及設定資訊主頁：

您可以透過 curl 公用程式或 Google Cloud CLI 直接叫用 API。

您無法擷取、編輯或刪除預先定義的資訊主頁。

這項功能僅支援 Google Cloud 專案。 如要進行 App Hub 設定，請選取 App Hub 主專案或啟用應用程式的資料夾管理專案。

關於資訊主頁

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

資訊主頁版面配置

版面配置會定義資訊主頁元件的排列順序。這項 API 提供下列版面配置：

  • GridLayout：將可用空間劃分為等寬的直向欄，並使用「先列後行」策略排列一組小工具。

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

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

  • ColumnLayout：將可用空間劃分為直向欄，並在每個欄中直向排列一組小工具。

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

{
  "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 小工具支援下列顯示樣式：

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

  • 顯示單一維度的資訊，例如最新值的資訊方塊：

    • PieChart：顯示時間序列集合的最新值，每個時間序列都會提供一個圓餅圖切片。

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

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

  • 顯示快訊政策或事件資訊的小工具：

    • AlertChart：顯示單一條件警報政策的摘要。這項小工具會以折線圖顯示資料、顯示門檻，並列出未結事件數。

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

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

  • 文字和機構小工具：

    • 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 查詢。

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

無論是釘選的篩選器或變數，資訊主頁工具列都會顯示每個變數和選單，方便您暫時變更變數值。系統會使用相同的資料結構來表示已釘選的篩選條件和變數。為協助您區分篩選器和變數，變數名稱會在資訊主頁工具列中加上美元符號 $ 前置字元。詳情請參閱 DashboardFilter。

如要查看如何使用變數控管小工具的顯示設定，請參閱已設定小工具顯示設定的資訊主頁。

如要瞭解如何使用以標籤為準的變數或僅含值的變數更新小工具的查詢，請參閱下列章節：

建立篩選器和變數

控制台

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

API

如要定義已釘選的篩選器和變數，請使用 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 欄位。如果您指定查詢，則必須是 Analytics 查詢。

舉例來說，請考量下列 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)$"

API

舉例來說，下列 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)$"

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

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

語法 選取的值
 已解析的記錄面板運算式
${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}"

API

舉例來說，下列 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 定義的小工具，使其依附於變數，請更新 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. 在工具列中選取「插入變數篩選器」，然後選取要更新 WHERE 子句的變數。
  3. 在隨即開啟的對話方塊中，查看產生的程式碼，然後按一下「複製並關閉」。

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

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

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

    在本例中，您需要編輯產生的程式碼，並將 LogName = 替換為 log_name =，才能進行資料表聯結：

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

  5. 依序按一下「執行」和「套用」。

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

API

由於 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 函式會將陣列轉換為表格。

含有 MQL 查詢的圖表

如要為含有 MQL 查詢的圖表使用以標籤為基礎的變數，請附加管道 (|)，然後按照一般語法中列出的指引操作。

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

控制台

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${my_label_based_variable}

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~'${my_label_based_variable.value}'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

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

resource.zone=~'${my_value_only_variable}'

API

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

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

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

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

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

resource.zone=~'${my_value_only_variable}'

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

語法 選取的值
 已解析的 MQL 運算式
${my_label_based_variable} 12345 filter (resource.instance_id == '12345')

範例變數是以資源標籤 instance_id 為依據。
${my_label_based_variable} * filter (true)
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

使用 Monitoring 篩選查詢的圖表

如要更新圖表，讓以監控篩選器形式的查詢依附於以標籤為準的變數，請按照「一般語法」一節的指引操作。

控制台

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

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

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

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

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

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

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

API

舉例來說，下列 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
},

使用監控篩選器形式查詢的小工具，無法依據標籤變數中的值篩選時間序列，但可以依據僅包含值的變數篩選。舉例來說，下列查詢會顯示依 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})"

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

語法 選取的值
 已解決的篩選運算式
${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 專案中，完成下列步驟：

  • Select the tab for how you plan to use the samples on this page:

    gcloud

      In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

      Terraform

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

      1. Install the Google Cloud CLI.

      2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      3. To initialize the gcloud CLI, run the following command: 

        gcloud init

      4. If you're using a local shell, then create local authentication credentials for your user account: 

        gcloud auth application-default login

        You don't need to do this if you're using Cloud Shell.

        If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

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

      REST

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

        After installing the Google Cloud CLI, initialize it by running the following command: 

        gcloud init

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。

建立資訊主頁

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

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 表示法，使用 Dashboards 格式。

      如需此格式的範例，您可以使用 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 表示法，使用 Dashboards 格式。

    • 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 值，並顯示更新後的資訊主頁清單。

後續步驟