Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Menggunakan API

Dokumen ini menjelaskan cara mengelola layanan dan tujuan tingkat layanan (SLO) menggunakan Cloud Monitoring API.

Pemantauan Layanan menambahkan resource berikut ke Monitoring API:

Dokumen ini secara kolektif menyebut penambahan ini sebagai SLO API dan mengilustrasikan penggunaan utamanya. Untuk ringkasan umum struktur dalam SLO API, lihat Konstruksi di API. Materi referensi komprehensif muncul di bagian Cloud Monitoring API v3.

Anda dapat menggunakan SLO API untuk melakukan hal berikut:

Membuat dan mengelola layanan.
Membuat tujuan tingkat layanan (SLO) berdasarkan indikator tingkat layanan (SLI) kustom atau yang telah ditentukan untuk layanan Anda.

ID yang valid

Beberapa metode dalam SLO API menggunakan ID untuk elemen yang berbeda, terutama ID untuk project dan layanan. ID ini mematuhi aturan berikut:

Panjang: 1–63 karakter
Karakter: hanya huruf kecil, angka, dan tanda hubung
Karakter awal: huruf kecil
Karakter akhir: huruf kecil atau angka, tetapi bukan tanda hubung

Ekspresi reguler untuk aturan ini adalah sebagai berikut: [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

Contoh menggunakan `curl`

Bagian ini menjelaskan konvensi dan penyiapan yang digunakan untuk memanggil SLO API menggunakan alat curl. Jika menggunakan API ini melalui library klien, Anda dapat melewati bagian ini.

Contoh di halaman ini mengakses SLO API menggunakan alat curl untuk mengirim permintaan HTTP ke endpoint REST. Gunakan informasi berikut tentang autentikasi dan tentang pemanggilan curl untuk menetapkan variabel yang digunakan dalam pemanggilan.

Autentikasi

Buat variabel lingkungan untuk menyimpan ID project cakupan cakupan metrik Anda: Contoh ini menggunakan PROJECT_ID:
```
PROJECT_ID=my-test-service
```
Lakukan autentikasi ke Google Cloud CLI:
```
gcloud auth login
```
Agar tidak perlu menentukan project ID dengan setiap perintah, tetapkan project ID sebagai default menggunakan gcloud CLI:
```
gcloud config set project ${PROJECT_ID}
```
Buat token otorisasi dan ambil token tersebut dalam variabel lingkungan. Contoh ini memanggil variabel ACCESS_TOKEN:
```
ACCESS_TOKEN=`gcloud auth print-access-token`
```
Anda harus memperbarui token akses secara berkala. Jika perintah yang berfungsi tiba-tiba melaporkan bahwa Anda tidak diautentikasi, terbitkan kembali perintah ini.
Untuk memverifikasi bahwa Anda mendapatkan token akses, tampilkan variabel ACCESS_TOKEN:
```
echo ${ACCESS_TOKEN}
ya29.GluiBj8o....
```

Memanggil `curl`

Setiap pemanggilan curl mencakup serangkaian argumen, diikuti dengan URL resource SLO API. Argumen umum mencakup nilai yang ditentukan oleh variabel lingkungan PROJECT_ID dan ACCESS_TOKEN. Anda mungkin juga harus menentukan argumen lain, misalnya, untuk menentukan jenis permintaan HTTP (misalnya, -X DELETE). Permintaan default adalah GET, sehingga contoh tidak menentukannya.

Setiap pemanggilan curl memiliki struktur umum ini:

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

Misalnya, untuk mencantumkan semua layanan dalam project Anda, kirim permintaan GET berikut:

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

Permintaan ini menampilkan array deskripsi layanan, dengan entri seperti berikut, layanan workload GKE dengan ID layanan “my-test-service”:

{
  "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"
      }
    },
   ...
  ]
}

Untuk melihat konfigurasi yang digunakan untuk membuat layanan ini, lihat Membuat layanan. Perhatikan bahwa struktur gkeWorkload dalam listingan ini berasal dari struktur basicService yang digunakan untuk membuat layanan. Lihat Service untuk mengetahui informasi selengkapnya tentang struktur layanan.

Mengelola layanan

Resource Service bertindak sebagai elemen root untuk mengatur layanan Anda. Aspek layanan tertentu, seperti SLO-nya misalnya, diatur berdasarkan nama layanan. Jenis layanan berikut didukung:

Layanan App Engine: APP_ENGINE
Layanan Cloud Endpoints: CLOUD_ENDPOINTS
Layanan Istio kanonis: ISTIO_CANONICAL_SERVICE
Layanan Istio cluster: CLUSTER_ISTIO
Layanan Cloud Run: CLOUD_RUN
Kumpulan layanan berbasis Google Kubernetes Engine:
- Layanan GKE: GKE_SERVICE
- Namespace GKE: GKE_NAMESPACE
- Workload GKE: GKE_WORKLOAD
Layanan kustom: CUSTOM

Untuk mengetahui informasi selengkapnya, lihat Jenis layanan dasar atau Jenis layanan GKE dasar.

Anda dapat menambahkan SLO ke layanan apa pun di project Anda menggunakan API. Mengelola SLO mencakup perintah untuk memanipulasi SLO.

ID Layanan

Setiap layanan memiliki ID yang sepenuhnya memenuhi syarat yang disebut nama resource. ID ini disimpan di kolom name deskripsi layanan, misalnya:

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

Disematkan dalam nama resource adalah ID yang lebih pendek untuk layanan, bagian nama resource setelah substring projects/PROJECT_NUMBER/services/

Jika Anda membuat layanan sendiri dengan nama resource projects/PROJECT_NUMBER/services/my-test-service, ID layanan adalah my-test-service.

Untuk singkat dan akurat, banyak contoh curl mengasumsikan ID layanan disimpan dalam variabel lingkungan SERVICE_ID sehingga Anda dapat merujuknya berulang kali.

Listing layanan

Untuk mengambil informasi tentang semua layanan dalam project Anda, panggil metode services.list. Untuk mengambil informasi tentang layanan tertentu berdasarkan ID layanan, gunakan services.getmetode:

Misalnya, untuk mencantumkan informasi tentang layanan menggunakan curl, panggil metode services.list atau services.get dengan mengirim permintaan GET ke:

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services untuk mencantumkan semua layanan
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID untuk mendapatkan layanan tertentu

Misalnya, permintaan berikut mengambil informasi tentang layanan yang diidentifikasi oleh nilai yang disimpan dalam variabel lingkungan SERVICE_ID:

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

Membuat layanan

Untuk membuat layanan, Anda menentukan representasi jenis layanan dan mengirimkannya ke metode services.create. Anda dapat menggunakan struktur jenis layanan yang dijelaskan dalam Jenis layanan dasar dan Jenis layanan GKE dasar.

Strukturnya bervariasi, tetapi proses untuk memanggil API sama. Anda harus menentukan nama tampilan untuk layanan dan kolom basicService yang menyimpan representasi layanan.

Secara opsional, Anda dapat menentukan ID layanan yang ingin dimiliki layanan. Contoh berikut menunjukkan pembuatan layanan workload GKE:

Misalnya, untuk membuat layanan menggunakan curl, kirim pesan POST ke endpoint https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services:

Jika ingin memberikan ID untuk layanan, buat variabel untuk ID layanan:
```
SERVICE_ID=my-test-service
```
Nilai ini diberikan dalam parameter kueri URL service_id.

Buat variabel untuk menyimpan isi permintaan yang menjelaskan layanan:

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
)

Posting isi permintaan ke endpoint, dan tentukan ID layanan sebagai nilai parameter kueri 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}

Untuk contoh struktur yang terkait dengan layanan lain, lihat Jenis layanan dasar atau Jenis layanan GKE dasar.

Menghapus layanan

Untuk menghapus layanan yang Anda buat, panggil metode services.delete dan tentukan ID layanan.

Misalnya, untuk menghapus layanan menggunakan curl, kirim permintaan DELETE ke https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID endpoint:

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

Mengelola SLO

Anda dapat membuat, menghapus, dan mengambil SLO menggunakan SLO API. Anda dapat memiliki hingga 500 SLO untuk setiap layanan.

Untuk mengelola SLO untuk layanan, Anda harus memiliki ID layanan. SLO diberi nama berdasarkan layanan yang dimilikinya. Untuk mengetahui informasi tentang cara mengidentifikasi ID layanan, lihat ID Layanan.

Mencantumkan SLO

Untuk mengambil informasi tentang semua SLO yang terkait dengan layanan, panggil metode services.serviceLevelObjectives.list. Untuk mengambil informasi tentang SLO tertentu berdasarkan nama, gunakan metode services.serviceLevelObjectives.get:

Untuk mencantumkan informasi tentang layanan menggunakan curl, panggil metode services.serviceLevelObjectives.list atau services.serviceLevelObjectives.get dengan mengirim permintaan GET ke:

https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives untuk mencantumkan semua SLO
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID untuk mendapatkan SLO tertentu

Misalnya, permintaan berikut mencantumkan semua SLO yang terkait dengan ID layanan yang disimpan dalam variabel lingkungan SERVICE_ID:

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

Berikut adalah SLO ketersediaan yang diambil dari layanan “currencyservice”:

{
  "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 ini dibuat berdasarkan SLI ketersediaan, menetapkan sasaran performa target sebesar 98 persen, dan mengukur kepatuhan selama satu minggu kalender. Untuk mengetahui informasi selengkapnya tentang SLI ketersediaan, lihat Indikator tingkat layanan.

Lihat ServiceLevelObjective untuk mengetahui informasi selengkapnya tentang struktur SLO.

Mengambil SLO tertentu

Setiap SLO memiliki ID unik dalam layanan, yang terdiri dari string yang mengikuti serviceLevelObjectives di kolom name SLO. Dalam contoh berikut:

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

ID SLO adalah string 3kavNVTtTMuzL7KcXAxqCQ.

Untuk mengambil informasi tentang SLO tertentu ini, minta SLO berdasarkan ID.

Misalnya, untuk mendapatkan SLO tertentu menggunakan curl, panggil metode services.serviceLevelObjectives.get dengan mengirim permintaan GET ke https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID:

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}

Membuat SLO

Untuk membuat SLO menggunakan SLO API, Anda harus membuat ServiceLevelObjective objek dan meneruskannya ke serviceLevelObjectives.create metode.

Struktur SLO memiliki banyak struktur yang disematkan, termasuk satu untuk nilai kolom serviceLevelIndicator.

Untuk layanan Cloud Service Mesh, Istio di Google Kubernetes Engine, dan App Engine, SLI telah ditentukan. Anda dapat menggunakan konsol Cloud Service Mesh untuk membuat SLO; yang perlu Anda lakukan hanyalah menentukan sasaran performa dan periode kepatuhan.
Untuk layanan lain, Anda harus menentukan SLO menggunakan SLO API. Untuk menentukan SLO, Anda juga harus membuat nilai untuk kolom serviceLevelIndicator. Lihat Membuat indikator tingkat layanan untuk beberapa teknik, dan Membuat SLI dari metrik untuk kumpulan contoh berdasarkan berbagai sumber.

Anda juga dapat membuat SLI menggunakan Google Cloud konsol. Untuk mengetahui informasi selengkapnya, lihat Membuat SLO.

Kerangka SLO

Kerangka dasar untuk membuat SLO adalah sebagai berikut:

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

Anda harus menentukan hal berikut:

Nama tampilan: deskripsi SLO
Indikator tingkat layanan, yang merupakan salah satu dari tiga jenis:
Sasaran performa (persentase)
Periode kepatuhan, yang merupakan salah satu dari dua jenis:
- Periode bergulir dengan panjang tertentu (dalam detik)
- Periode kalender

Untuk mengetahui informasi selengkapnya tentang SLI, sasaran performa, dan periode kepatuhan, lihat Konsep dalam pemantauan layanan.

Untuk layanan Cloud Service Mesh, Istio di Google Kubernetes Engine, dan App Engine, jenis SLI adalah SLI dasar.

Untuk layanan lain, Anda harus membuat SLI berbasis permintaan atau SLI berbasis jendela. Lihat Membuat indikator tingkat layanan untuk beberapa teknik.

Contoh

Setelah memiliki SLI, Anda dapat membuat SLO. Contoh berikut menentukan SLO untuk layanan yang menggunakan SLI dasar. Anda mungkin memiliki beberapa SLO pada satu SLI, misalnya, satu untuk ketersediaan 95% dan satu untuk ketersediaan 99%. Contoh berikut adalah SLO untuk ketersediaan 95% selama satu minggu kalender:

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

Contoh ini menentukan SLO untuk ketersediaan 75% selama periode 3 hari bergulir:

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

Misalnya, untuk membuat SLO menggunakan curl, kirim pesan POST ke https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives endpoint:

Buat variabel untuk ID layanan:
```
SERVICE_ID=custom:my-test-service
```

Buat variabel untuk menyimpan isi permintaan, instance objek ServiceLevelObjective. Contoh ini menggunakan salah satu SLOs yang dijelaskan sebelumnya:

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
)

Posting isi permintaan ke endpoint:

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

Secara opsional, Anda juga dapat menentukan ID untuk SLO sebagai nilai parameter kueri 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}

Menghapus SLO

Untuk menghapus SLO, panggil metode services.serviceLevelObjectives.deletedan tentukan ID SLO di project Anda:

Misalnya, untuk menghapus SLO menggunakan curl, kirim permintaan DELETE ke https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID endpoint:

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

Mengakses deret waktu SLO

Data SLO disimpan dalam deret waktu, sehingga Anda dapat menggunakan metode timeSeries.list untuk mengambilnya. Namun, data ini tidak disimpan dalam jenis metrik standar, sehingga Anda tidak dapat menggunakan mekanisme standar untuk menentukan filter jenis metrik ke metode timeSeries.list.

Sebagai gantinya, deret waktu SLO diambil dengan menentukan jenis filter lain, pemilih deret waktu, ke metode timeSeries.list dalam parameter filter. Lihat Mengambil data SLO untuk mengetahui informasi tentang cara menggunakan pemilih ini.

Anda juga menggunakan pemilih deret waktu untuk menyiapkan kebijakan pemberitahuan secara terprogram. Lihat Pemberitahuan tentang laju pengeluaran Anda untuk mengetahui informasi selengkapnya.

Menggunakan API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.