使用 API 設定指標範圍

本文件說明如何使用 Google Cloud CLI 或 Cloud Monitoring API 設定 Google Cloud 專案的指標範圍。本頁面適用於開發人員和系統管理員。

App Hub 應用程式和指標範圍

您可以管理 App Hub 主機專案的指標範圍。您可以使用 Google Cloud 控制台或 Cloud Monitoring API 管理這個範圍。

Google Cloud 會管理已啟用應用程式的資料夾指標範圍，除非指標範圍配額用盡，導致無法將專案新增至指標範圍。在這種情況下，您可以要求增加配額，然後手動將專案新增至已啟用應用程式的資料夾管理專案指標範圍。詳情請參閱「已啟用應用程式的資料夾指標範圍」。

事前準備

  • 如果您不熟悉「指標範圍」和「設定專案範圍」的用語，請參閱「指標範圍」一文。

  • 請確認您在設定範圍的專案和每個要加入或移除至指標範圍的專案中，都具備監控管理員 (roles/monitoring.admin) 角色的所有權限。詳情請參閱「指標範圍設定」。

  • 用於擷取資訊的 Cloud Monitoring API 指標範圍方法為同步，但用於變更狀態的 API 則為非同步。Google Cloud CLI 指令會阻斷，直到非同步作業完成為止。如要瞭解如何判斷非同步 API 方法何時完成，以及如何判斷其狀態，請參閱「非同步 API 方法」。

  • 如果您打算使用 curl 叫用 Cloud Monitoring API，或是想使用本頁面的範例，請完成 curl 指令設定步驟。

將專案新增至指標範圍

gcloud

如要將 Google Cloud 專案新增至指標範圍，請執行 gcloud beta monitoring metrics-scopes create 指令：

gcloud beta monitoring metrics-scopes create MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

執行上述指令前，請先執行下列操作：

  • 輸入指標範圍要修改的 Google Cloud 專案名稱或 ID，並將其存入變數 SCOPING_PROJECT_ID_OR_NUMBER。如要設定 App Hub，請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。

  • 在變數 MONITORED_PROJECT_ID_OR_NUMBER 中輸入要監控的專案 ID。格式為 projects/PROJECT_ID_OR_NUMBER。

舉例來說，下列指令會將專案 my-monitored-project 新增至名為 my-staging-projects 的專案指標範圍：

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

對上一個指令的回應會確認指令是否已成功完成：

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

如要將 Google Cloud 專案新增至指標範圍，請將 POST 要求傳送至 locations.global.metricsScopes.projects.create 端點：

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

在上述範例中，環境變數的定義如下：

  • MONITORED_PROJECT_ID_OR_NUMBER 會儲存要新增至指標範圍的專案 ID。
  • SCOPING_PROJECT_ID_OR_NUMBER 會儲存指標範圍正在更新的專案 ID。

這個非同步方法的回應為 Operation 物件。

呼叫此方法的應用程式應輪詢 operation.get 端點，直到 Operation.done 欄位的值為 true 為止。Operation.done 欄位設為 false 時，表示作業正在進行中。詳情請參閱「非同步 API 指令」。

以下是成功新增受控專案的回應範例：

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "G​C​P",
    "providerAccountId": "...",
    ...
  }
}

在先前的回應中，Operation.done 欄位已設為 true。這個值表示指令已完成。由於指令已順利完成，因此 Operation.response 欄位已設好，其值為 MonitoredProject 物件。response.name 欄位包含範圍設定專案和監控專案的 ID。providerAccountId 欄位會列出受監控專案的名稱。

叫用此方法會在稽核專案的稽核記錄中建立項目。 Google Cloud 主控台不會叫用這個 API 方法。因此，使用Google Cloud 控制台時對指標範圍所做的修改不會記錄在稽核記錄中。

從指標範圍中移除專案

gcloud

如要從指標範圍中移除 Google Cloud 專案，請執行 gcloud beta monitoring metrics-scopes delete 指令：

gcloud beta monitoring metrics-scopes delete MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

執行上述指令前，請先執行下列操作：

  • 輸入指標範圍要修改的 Google Cloud 專案名稱或 ID，並將其存入變數 SCOPING_PROJECT_ID_OR_NUMBER。如要設定 App Hub，請選取 App Hub 主機專案或啟用應用程式的資料夾管理專案。

  • 在變數 MONITORED_PROJECT_ID_OR_NUMBER 中輸入要監控的專案 ID。格式為 projects/PROJECT_ID_OR_NUMBER。

舉例來說，下列指令會從名為 my-staging-projects 的專案中，移除指標範圍內的 my-monitored-project 專案：

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

對上一個指令的回應會確認指令是否已成功完成：

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

如果範圍設定專案未監控 MONITORED_PROJECT_ID_OR_NUMBER 變數指定的專案，系統會回報以下錯誤：

NOT_FOUND: Requested entity was not found.

curl

如要從指標範圍中移除 Google Cloud 專案，請將 DELETE 要求傳送至 locations.global.metricsScopes.projects.delete 端點：

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

在上述範例中，環境變數的定義如下：

  • MONITORED_PROJECT_ID_OR_NUMBER 會儲存要從指標範圍中移除的專案 ID。
  • SCOPING_PROJECT_ID_OR_NUMBER 會儲存指標範圍正在更新的專案 ID。

這個非同步方法的回應是 Operation 物件。

呼叫此方法的應用程式應輪詢 operation.get 端點，直到 Operation.done 欄位的值為 true 為止。Operation.done 欄位設為 false 時，表示作業正在進行中。詳情請參閱「非同步 API 指令」。

以下是移除受監控專案成功的回應範例：

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

在先前的回應中，Operation.done 欄位已設為 true。這個值表示指令已完成。由於指令已順利完成，因此 Operation.response 欄位已設為包含 @type 欄位。

叫用此方法會在稽核專案的稽核記錄中建立項目。 Google Cloud 主控台不會叫用這個 API 方法。因此，使用Google Cloud 控制台時對指標範圍所做的修改不會記錄在稽核記錄中。

列出包含專案的所有指標範圍

如果您想知道哪些資源可以查看Google Cloud 專案儲存的資料，可以列出包含專案的所有指標範圍，然後查看這些範圍的詳細資料。本節提供如何列出包含特定Google Cloud 專案的指標範圍的相關資訊。

gcloud

如要取得可查看Google Cloud 專案指標的指標範圍清單，請執行 gcloud beta monitoring metrics-scopes list 指令：

gcloud beta monitoring metrics-scopes list MONITORED_PROJECT_ID_OR_NUMBER

執行指令前，請在變數 MONITORED_PROJECT_ID_OR_NUMBER 中輸入要監控的專案 ID。格式為 projects/PROJECT_ID_OR_NUMBER。

舉例來說，如要列出包含專案 my-project 的指標範圍，請執行下列指令：

gcloud beta monitoring metrics-scopes list projects/my-project

以下回應指出專案 my-project 包含在兩個指標範圍中：

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

如要取得指標範圍的詳細資訊，請執行 gcloud beta monitoring metrics-scopes describe 指令。

curl

如要取得可查看專案指標的指標範圍清單，請將 GET 要求傳送至 locations.global.metricsScopes.listMetricsScopesByMonitoredProject 端點，並加入指定專案的查詢參數。

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

在上述範例中，環境變數 PROJECT_ID_OR_NUMBER 會儲存專案 ID，而該 ID 會納入指標範圍中並進行查詢。

如果成功，回應會是 MetricsScope 物件的陣列。

這個方法不會將項目寫入限定範圍專案的稽核記錄。如要將這些動作記錄在稽核記錄中，請為 Cloud Resource Manager API 啟用「資料讀取」。詳情請參閱「設定資料存取稽核記錄」。

取得指標範圍的詳細資料

本節將說明如何查看特定指標範圍的詳細資料。

gcloud

如要取得指標範圍的詳細資訊，請執行 gcloud beta monitoring metrics-scopes describe 指令：

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

執行指令前，請在變數 METRICS_SCOPE_ID 中輸入指標範圍的完整名稱。以下是完整合格名稱的範例：

locations/global/metricsScopes/012345012345

以下是回應範例。在這個範例中，指標範圍包含一個專案，且指標範圍和專案的 ID 相同：

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

如要透過 ID 識別 Google Cloud 專案，請執行 gcloud projects list 指令，並依專案 ID 篩選。舉例來說，如要取得專案 012345012345 的名稱，請執行下列指令：

gcloud projects list --filter="012345012345" --format="value(NAME)"

curl

如要取得指標範圍的相關資訊，請將 GET 要求傳送至 locations.global.metricsScopes.get 端點：

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

在前述範例中，環境變數 SCOPING_PROJECT_ID_OR_NUMBER 會儲存指標範圍查詢專案的 ID。

如果成功，回應會是 MetricsScope 物件。

這個方法不會將項目寫入限定範圍專案的稽核記錄。如要將這些動作記錄在稽核記錄中，請為 Cloud Resource Manager API 啟用「資料讀取」。詳情請參閱「設定資料存取稽核記錄」。

非同步 API 方法

所有會變更系統狀態的 Cloud Monitoring API 指標範圍方法 (例如新增受監控專案指標範圍的指令) 都是非同步的。對於這些指令，指令回應為 Operation 物件。

呼叫非同步 API 方法的應用程式應輪詢 operation.get 端點，直到 Operation.done 欄位的值為 true：

  • 當 done 為 false 時，表示作業正在進行中。

    如要重新整理狀態資訊，請將 GET 要求傳送至 operation.get 端點：

    curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}

    在上一個指令中，OPERATION_NAME 是儲存 Operation.name 欄位值的環境變數。

  • 當 done 為 true 時，作業就會完成，並設定 error 或 response 欄位：

    • error：如果已設為此值，表示非同步作業失敗。這個欄位的值是 Status 物件，其中包含 gRPC 錯誤代碼和錯誤訊息。
    • response：設定後，非同步作業會順利完成，且值會反映結果。

curl 指令設定

本節說明在本文件中建立 curl 指令時所用的設定。本頁的每個 curl 指令都包含一組引數，後面接著 API 資源的網址：

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

設定下列環境變數，簡化 curl 指令的建立程序：

  1. 建立環境變數，用於儲存範圍專案 ID 或編號。如果您使用的是 App Hub，請將這個變數設為 App Hub 主機專案的 ID，或是啟用應用程式的資料夾管理專案 ID：

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

  2. (非必要) 如果您打算新增或移除受監控的專案，請使用受監控的專案 ID 或編號設定環境變數：

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. 透過 Google Cloud CLI 進行驗證：

    gcloud auth login

  4. (非必要) 為避免每次執行 gcloud 指令時都必須指定專案 ID，請使用 gcloud CLI 將專案 ID 設為預設值：

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. 建立授權權杖，並在環境變數中擷取權杖：

    TOKEN=`gcloud auth print-access-token`

    符記的有效期限有限。如果原本可用的指令突然回報你未經驗證，請重新發出這項指令。

  6. 如要確認您已取得存取權杖，請回應 TOKEN 變數：

    echo ${TOKEN}
ya29.GluiBj8o....

您可能還需要指定其他引數，例如指定 HTTP 要求的類型 (例如 -X DELETE)。預設要求是 GET，因此範例不會指定該引數。

後續步驟

如要瞭解如何搭配 Terraform 使用 Google Cloud ，請參閱以下資源：