使用 API

本文說明如何使用 Cloud Monitoring API 管理服務和服務等級目標 (SLO)。

服務監控會在 Monitoring API 中新增下列資源：

本文將這些新增項目統稱為 SLO API，並說明主要用途。如要大致瞭解 SLO API 中的結構，請參閱「API 中的建構元件」。完整參考資料會顯示在「Cloud Monitoring API v3」下方。

您可以使用 SLO API 執行下列操作：

  • 建立及管理服務。

  • 根據自訂或預先定義的服務水準指標 (SLI)，為任何服務建立服務等級目標 (SLO)。

有效 ID

SLO API 中的多種方法會使用不同元素的 ID，尤其是專案和服務的 ID。這些 ID 遵循下列規則：

  • 長度：1 至 63 個字元
  • 字元：只能使用小寫英文字母、數字和連字號
  • 開頭字元：小寫字母
  • 結尾字元：小寫英文字母或數字，但不得為連字號

這些規則的規則運算式如下： [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

使用「curl」的範例

本節說明使用 curl 工具呼叫 SLO API 時所用的慣例和設定。如果您是透過用戶端程式庫使用這項 API，可以略過本節。

本頁的範例會使用 curl 工具，將 HTTP 要求傳送至 REST 端點，藉此存取 SLO API。請使用下列驗證和叫用 curl 的相關資訊，設定叫用時使用的變數。

驗證

  1. 建立環境變數，用來保存指標範圍的範圍界定專案 ID。以下範例使用 PROJECT_ID：

    PROJECT_ID=my-test-service

  2. 驗證 Google Cloud CLI：

    gcloud auth login

  3. 為避免必須在每個指令中指定專案 ID，請使用 gcloud CLI 將專案 ID 設為預設值：

    gcloud config set project ${PROJECT_ID}

  4. 建立授權權杖，並擷取至環境變數中。 這些範例會呼叫變數 ACCESS_TOKEN：

    ACCESS_TOKEN=`gcloud auth print-access-token`

    您必須定期更新存取權杖。如果原本可用的指令突然回報您未通過驗證，請重新發出這個指令。

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

    echo ${ACCESS_TOKEN}
ya29.GluiBj8o....

叫用「curl」

每次 curl 呼叫都會包含一組引數，後接 SLO API 資源的網址。常見引數包括 PROJECT_ID 和 ACCESS_TOKEN 環境變數指定的值。您可能也必須指定其他引數，例如指定 HTTP 要求的類型 (例如 -X DELETE)。預設要求為 GET，因此範例不會指定這項引數。

每次叫用 curl 時，一般結構如下：

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

舉例來說，如要列出專案中的所有服務，請發出下列 GET 要求：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services

這項要求會傳回服務說明陣列，其中包含下列項目，也就是服務 ID 為「my-test-service」的 GKE 工作負載服務：

{
  "services": [
    {
      "name": "projects/PROJECT_NUMBER/services/my-test-service",
      "displayName": "My Test GKE Workload Service",
      "basicService": {
        "serviceType": "GKE_WORKLOAD",
        "serviceLabels": {
          "cluster_name": "workload-test",
          "location": "us-central1-c",
          "namespace_name": "kube-system",
          "project_id": "lesser-weevil",
          "top_level_controller_name": "gke-metrics-controller",
          "top_level_controller_type": "DaemonSet"
        }
      },
      "gkeWorkload": {
        "projectId": "lesser-weevil",
        "location": "us-central1-c",
        "clusterName": "workload-test",
        "namespaceName": "kube-system",
        "topLevelControllerType": "DaemonSet",
        "topLevelControllerName": "gke-metrics-controller"
      },
      "source": "USER",
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/PROJECT_ID/zones/us-central1-c/clusters/workload-test/k8s/namespaces/kube-system/apps/daemonsets/gke-metrics-controller"
      }
    },
   ...
  ]
}

如要查看用於建立這項服務的設定，請參閱「建立服務」。請注意，這個清單中的 gkeWorkload 結構是衍生自用於建立服務的 basicService 結構。如要進一步瞭解服務結構，請參閱 Service。

管理服務

Service 資源是組織服務的根元素。特定服務的各個層面 (例如服務等級目標) 會依服務名稱整理。支援的服務類型如下：

  • App Engine 服務：APP_ENGINE
  • Cloud Endpoints 服務：CLOUD_ENDPOINTS
  • 標準 Istio 服務：ISTIO_CANONICAL_SERVICE
  • 叢集 Istio 服務：CLUSTER_ISTIO
  • Cloud Run 服務：CLOUD_RUN
  • 一組以 Google Kubernetes Engine 為基礎的服務：
    • GKE 服務：GKE_SERVICE
    • GKE 命名空間：GKE_NAMESPACE
    • GKE 工作負載：GKE_WORKLOAD
  • 自訂服務：CUSTOM

詳情請參閱「基本服務類型」或「基本 GKE 服務類型」。

您可以使用 API，在專案中的任何服務中加入服務等級目標。管理服務等級目標一文介紹了操作服務等級目標的指令。

服務 ID

每項服務都有完整識別碼，稱為「資源名稱」。這個 ID 會儲存在服務說明的 name 欄位中，例如：

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",

資源名稱中內嵌了服務的較短 ID，也就是資源名稱中 projects/PROJECT_NUMBER/services/ 子字串後方的部分。

如果您建立的服務資源名稱為 projects/PROJECT_NUMBER/services/my-test-service，則服務 ID 為 my-test-service。

為求簡潔和準確，許多 curl 範例會假設服務 ID 保存在環境變數 SERVICE_ID 中，方便您重複參照。

列出服務

如要擷取專案中所有服務的相關資訊，請叫用 services.list 方法。如要依服務 ID 擷取特定服務的資訊，請使用 services.get 方法：

通訊協定

如要使用 curl 列出服務相關資訊，請將 GET 要求傳送至下列網址，以叫用 services.list 或 services.get 方法：

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services 列出所有服務
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID 取得特定服務

舉例來說，下列要求會擷取環境變數 SERVICE_ID 中儲存值所識別的服務相關資訊：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

建立 Service

如要建立服務，請指定服務類型的表示法，然後傳送至 services.create 方法。您可以參閱「基本服務類型」和「基本 GKE 服務類型」一文，瞭解服務類型結構。

結構各不相同，但呼叫 API 的程序相同。 你必須指定服務的顯示名稱，以及包含服務代表的 basicService 欄位。

您可以視需要指定服務 ID。以下範例說明如何建立 {[gke_name_short}} 工作負載服務：

通訊協定

如要使用 curl 建立服務，請將 POST 訊息傳送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services 端點：

  1. 如要提供服務的 ID，請為服務 ID 建立變數：

    SERVICE_ID=my-test-service

    這個值會以網址查詢參數 service_id 提供。

  2. 建立變數，以保留說明服務的要求主體：

    CREATE_SERVICE_POST_BODY=$(cat <<EOF
{
  "displayName": "My Test GKE Workload Service",
  "basicService": {
    "serviceType": "GKE_WORKLOAD",
    "serviceLabels": {
      "cluster_name": "workload-test",
      "location": "us-central1-c",
      "namespace_name": "kube-system",
      "project_id": "PROJECT_ID",
      "top_level_controller_name": "gke-metrics-controller",
      "top_level_controller_type": "DaemonSet"
    }
  }
}
EOF
)

  3. 將要求主體發布至端點，並將服務 ID 指定為 service_id 查詢參數的值：

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SERVICE_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services?service_id=${SERVICE_ID}

如需與其他服務相關聯的結構範例，請參閱「基本服務類型」或「基本 GKE 服務類型」。

刪除服務

如要刪除您建立的服務，請叫用 services.delete 方法並指定服務 ID。

通訊協定

如要使用 curl 刪除服務，請向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID 端點傳送 DELETE 要求：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

管理服務等級目標

您可以使用 SLO API 建立、刪除及擷取 SLO。每項服務最多可有 500 個 SLO。

如要管理服務的 SLO，您必須擁有服務 ID。系統會根據服務為服務等級目標命名。 如要瞭解如何找出服務 ID，請參閱「服務 ID」。

列出服務等級目標

如要擷取與服務相關聯的所有服務等級目標資訊，請叫用 services.serviceLevelObjectives.list 方法。如要依名稱擷取特定服務水準目標的相關資訊，請使用 services.serviceLevelObjectives.get 方法：

通訊協定

如要使用 curl 列出服務相關資訊，請將 GET 要求傳送至下列網址，以叫用 services.serviceLevelObjectives.list 或 services.serviceLevelObjectives.get 方法：

  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives 列出所有服務等級目標
  • https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID 取得特定服務等級目標

舉例來說，下列要求會列出與環境變數 SERVICE_ID 中儲存的服務 ID 相關聯的所有 SLO：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

以下是從「currencyservice」服務擷取的可用性 SLO：

{
  "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
  "displayName": "98% Availability in Calendar Week"
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.98,
  "calendarPeriod": "WEEK",
},

這個服務水準目標是以可用性服務水準指標為基礎，設定 98% 的目標效能，並以一週為單位評估達成度。如要進一步瞭解可用性 SLI，請參閱「服務水準指標」。

如要進一步瞭解 SLO 的結構，請參閱 ServiceLevelObjective。

擷取特定服務等級目標

每個服務等級目標在服務中都有專屬 ID，由服務等級目標 name 欄位中 serviceLevelObjectives 後方的字串組成。在下列範例中：

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",

SLO ID 是字串 3kavNVTtTMuzL7KcXAxqCQ。

如要擷取特定服務等級目標的資訊，請依 ID 要求服務等級目標。

通訊協定

如要使用 curl 取得特定 SLO，請向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID 發出 GET 要求，叫用 services.serviceLevelObjectives.get 方法：

SLO_ID=dhefHDM4TwSRZEKIV4ZYEg

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

建立服務等級目標

如要使用 SLO API 建立 SLO，請建立 ServiceLevelObjective 物件，並將其傳遞至 serviceLevelObjectives.create 方法。

SLO 的結構包含許多內嵌結構，包括 serviceLevelIndicator 欄位值的結構。

  • 對於 Cloud Service Mesh、Google Kubernetes Engine 上的 Istio 和 App Engine 服務，系統會預先定義 SLI。 您可以使用 Cloud Service Mesh 控制台建立服務等級目標，只要指定效能目標和合規期間即可。

  • 如為其他服務，您必須使用 SLO API 定義服務等級目標。如要指定服務等級目標，您也必須為 serviceLevelIndicator 欄位建立值。如需一些技巧，請參閱「建立服務水準指標」一文；如需根據各種來源建立 SLI 的範例，請參閱「運用指標建立 SLI」一文。

您也可以使用 Google Cloud 控制台建立 SLI。詳情請參閱「建立 SLO」。

服務等級目標的架構

建立服務等級目標的基本架構如下：

{
  "displayName": string,
  "serviceLevelIndicator": {
    object (ServiceLevelIndicator)
  },
  "goal": number,

  // Union field period can be only one of the following:
  "rollingPeriod": string,
  "calendarPeriod": enum (CalendarPeriod)
  // End of list of possible types for union field period.
}

您必須指定下列項目：

  • 顯示名稱：服務水準目標的說明
  • 服務水準指標，屬於下列三種類型之一：
  • 成效目標 (百分比)
  • 達成度評估時間範圍，分為下列兩種：
    • 一段時間的滾動週期 (以秒為單位)
    • 一段日曆時間

如要進一步瞭解 SLI、效能目標和法規遵循週期，請參閱「服務監控概念」。

對於 Cloud Service Mesh、Google Kubernetes Engine 上的 Istio 和 App Engine 服務，SLI 類型為基本 SLI。

如果是其他服務，則必須建立以要求為基礎的 SLI 或以時間範圍為基礎的 SLI。如需一些技巧，請參閱「建立服務水準指標」。

範例

有了 SLI 後，您就可以建立 SLO。以下範例定義了使用基本 SLI 的服務 SLO。您可能在單一 SLI 上有多個 SLO，例如一個是 95% 可用性，另一個是 99% 可用性。以下範例是日曆週內 95% 正常運作時間的 SLO：

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.95,
  "calendarPeriod": "WEEK",
  "displayName": "95% Availability in Calendar Week"
}

這個範例指定了在 3 天的滾動期間內，可用性為 75% 的 SLO： 

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}

通訊協定

如要使用 curl 建立 SLO，請將 POST 訊息傳送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives 端點：

  1. 建立服務 ID 的變數：

    SERVICE_ID=custom:my-test-service

  2. 建立變數來保存要求主體，也就是 ServiceLevelObjective 物件的例項。這個範例使用先前所述的其中一個 SLO：

    CREATE_SLO_POST_BODY=$(cat <<EOF
{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}
EOF
)

  3. 將要求主體發布至端點：

    curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

    您也可以選擇將 SLO 的所需 ID 指定為 service_level_objective_id 查詢參數的值：

    SLO_ID=test-slo-id

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives?service_level_objective_id=${SLO_ID}

刪除服務等級目標

如要刪除 SLO，請叫用 services.serviceLevelObjectives.delete 方法，並指定專案中的 SLO ID：

通訊協定

如要使用 curl 刪除 SLO，請向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID 端點傳送 DELETE 要求：

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

存取服務等級目標時間序列

SLO 資料會儲存在時間序列中，因此您可以使用 timeSeries.list 方法擷取資料。不過，這項資料不會儲存在標準指標類型中，因此您無法使用指定指標類型篩選器的標準機制，將資料傳送至 timeSeries.list 方法。

不過，您可以透過 filter 參數的 timeSeries.list 方法指定其他類型的篩選器 (即時間序列選取器)，擷取 SLO 時間序列。如要瞭解如何使用這些選取器，請參閱「擷取服務等級目標資料」。

您也可以使用時間序列選取器，以程式輔助方式設定快訊政策。詳情請參閱「資金消耗率的快訊」。