本頁面由 Cloud Translation API 翻譯而成。

使用 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 的相關資訊，設定叫用作業中使用的變數。

驗證

建立環境變數，用於存放指標範圍的範圍設定專案 ID：以下範例使用 PROJECT_ID：
```
PROJECT_ID=my-test-service
```
透過 Google Cloud CLI 進行驗證：
```
gcloud auth login
```
為避免每次執行指令時都需要指定專案 ID，請使用 gcloud CLI 將其設為預設值：
```
gcloud config set project ${PROJECT_ID}
```
建立授權權杖，並在環境變數中擷取權杖。以下範例會呼叫變數 ACCESS_TOKEN：
```
ACCESS_TOKEN=`gcloud auth print-access-token`
```
您必須定期更新存取權杖。如果原本有效的指令突然回報你未經過驗證，請重新發出這項指令。
如要確認您已取得存取權杖，請回應 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，稱為「資源名稱」。這個 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 端點：

如果您想為服務提供 ID，請建立服務 ID 的變數：
```
SERVICE_ID=my-test-service
```
這個值會在網址查詢參數 service_id 中提供。

建立變數，用於儲存描述服務的要求主體：

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
)

將要求主體發布至端點，並將服務 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 刪除服務，請將 DELETE 要求傳送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID 端點：

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 個服務等級目標。

如要管理服務的服務等級目標，您必須擁有服務 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 取得特定 SLO

舉例來說，下列要求會列出與環境變數 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",
},

這個 SLO 是以可用性 SLI 為基礎，設定 98% 的目標效能目標，並評估在整個日曆週內的遵循情況。如要進一步瞭解可用性 SLI，請參閱「服務水準指標」。

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

擷取特定服務等級目標

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

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

SLO ID 是字串 3kavNVTtTMuzL7KcXAxqCQ。

如要擷取這個特定 SLO 的相關資訊，請依 ID 要求 SLO。

通訊協定

如要使用 curl 取得特定 SLO，請將 GET 要求傳送至

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID

，以便叫用 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，只要指定效能目標和遵循期間即可。
針對其他服務，您必須使用 SLO API 定義 SLO。如要指定服務等級目標，您也必須為 serviceLevelIndicator 欄位建立值。如要瞭解部分技巧，請參閱「建立服務水準指標」一文，如要瞭解一系列根據不同來源建立的示例，請參閱「運用指標建立 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 或以 Windows 為基礎的 SLI。如需瞭解相關技巧，請參閱「建立服務水準指標」。

範例

取得 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"
}

本例會指定 75% 的可用性 SLO，適用於 3 天滾動期間：

{
  "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

端點：

建立服務 ID 的變數：
```
SERVICE_ID=custom:my-test-service
```

建立變數來存放要求主體 (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
)

將要求主體發布至端點：

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，請將 DELETE 要求傳送至

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID

端點：

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 時間序列。如要瞭解如何使用這些選取器，請參閱「擷取服務等級目標資料」。

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

使用 API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

有效的 ID

使用 curl 的範例

驗證

叫用 curl

管理服務

服務 ID

列出服務

通訊協定

建立 Service

通訊協定

刪除服務

通訊協定

管理服務等級目標

列出服務等級目標

通訊協定

擷取特定服務等級目標

通訊協定

建立服務等級目標

服務等級目標的骨架

範例

通訊協定

刪除服務等級目標

通訊協定

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

使用 API
透過集合功能整理內容你可以依據偏好儲存及分類內容。

使用 `curl` 的範例

叫用 `curl`