Panduan memulai: Mencantumkan peristiwa yang memengaruhi project atau organisasi menggunakan Service Health API

Dokumen ini menjelaskan cara mencantumkan peristiwa Personalized Service Health yang mungkin memengaruhi atau telah memengaruhi produk Google Cloud di project atau organisasi Google Cloud Anda. Anda akan menggunakan Personalized Service Health API.

Sebelum memulai

  1. Aktifkan Service Health API, jika belum diaktifkan:

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    gcloud services enable servicehealth.googleapis.com
  2. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

  3. Jika Anda menggunakan project yang sudah ada untuk panduan ini, pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini. Jika berhasil membuat project baru, berarti Anda sudah memiliki izin yang diperlukan.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mencantumkan peristiwa Service Health, minta administrator untuk memberi Anda peran IAM Personalized Service Health Viewer (roles/servicehealth.viewer) di project atau organisasi yang ingin Anda cantumkan peristiwanya. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Referensi

Lihat referensi API Events (v1, v1beta), Impacts (v1beta), OrganizationEvents (v1, v1beta), dan OrganizationImpacts (v1, v1beta) untuk mengetahui metode yang dapat Anda gunakan dan arti kolom dalam respons.

Saat menetapkan produk atau lokasi, gunakan nilai yang ditemukan di Google Cloud produk dan lokasi.

Mencantumkan semua insiden aktif untuk sebuah project

Anda dapat mencantumkan semua insiden Google Cloud untuk project Google Cloud tertentu.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • API_VERSION: Versi API yang akan digunakan. Gunakan v1 atau v1beta.
  • PROJECT_ID: ID project.

Metode HTTP dan URL:

GET https://servicehealth.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/global/events?filter=state=ACTIVE%20category=INCIDENT&page_size=2&page_token={page_token}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "events": [
    {
      "name": "projects/PROJECT_ID/locations/global/events/event-123",
      "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "The issue with Google Cloud SQL has been resolved for all affected projects. We thank you for your patience while we worked on resolving the issue.",
      "category": "INCIDENT",
      "detailedCategory": "CONFIRMED_INCIDENT",
      "state": "ACTIVE",
      "detailedState": "CONFIRMED",
      "eventImpacts": [
        {
          "product": {
            "productName": "Google Cloud SQL",
            "id": "hV87iK5DcEXKgWU2kDri",
          },
          "location": {
            "locationName": "asia-east2",
          }
        },
        {
          "product": {
            "productName": "Google Cloud SQL",
            "id": "hV87iK5DcEXKgWU2kDri",
          },
          "location": {
            "locationName": "asia-southeast1",
          }
        }
      ],
      "relevance": "RELATED",
      "updateTime": "2022-10-18T17:44:05.690761Z",
      "startTime": "2022-10-18T17:41:20.112287Z",
    },
    {
      "name": "projects/PROJECT_ID/locations/global/events/event-567",
      "title": "Cloud Firestore may experience errors.",
      "description": "Mitigation work is currently underway by our engineering team. The mitigation is expected to complete by 2022-10-07T16:30:00Z.",
      "category": "INCIDENT",
      "detailedCategory": "CONFIRMED_INCIDENT",
      "state": "ACTIVE",
      "detailedState": "CONFIRMED",
      "eventImpacts": [
        {
          "product": {
            "productName": "Cloud Firestore",
            "id": "CETSkT92V21G6A1x28me",
          },
          "location": {
            "locationName": "us-central1-a",
          }
        }
      ],
      "relevance": "RELATED",
      "updateTime": "2022-10-07T15:19:59.409530Z",
      "startTime": "2022-10-07T15:10:35.887125Z",
      "nextUpdateTime": "2022-10-07T16:30:00Z"
    }
  ],
  "nextPageToken": "CgwIw8bDmgYQz4nUlgMQChomcHJvamVjdHMvcHNoLW1hbnVhbC"
}

Jika tidak memiliki izin yang diperlukan untuk mencantumkan peristiwa, Anda akan mendapatkan error PERMISSION_DENIED.

{
  "error": {
    "code": 403,
    "message": "Permission 'servicehealth.events.list' denied on resource '//servicehealth.googleapis.com/projects/PROJECT_ID/locations/global' (or it may not exist).",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "IAM_PERMISSION_DENIED",
        "domain": "servicehealth.googleapis.com",
        "metadata": {
          "resource": "projects/PROJECT_ID/locations/global",
          "permission": "servicehealth.events.list"
        }
      }
    ]
  }
}

Mencantumkan semua insiden aktif untuk organisasi

Anda dapat mencantumkan semua insiden Google Cloud yang memengaruhi project apa pun yang telah mengaktifkan Personalized Service Health di organisasi Google Cloud tertentu.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • API_VERSION: versi API yang akan digunakan. Gunakan v1 atau v1beta.
  • ORGANIZATION_ID: ID organisasi Google Cloud Anda.
  • PROJECT_ID: project ID yang digunakan untuk kuota dan penagihan.

Metode HTTP dan URL:

GET https://servicehealth.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/locations/global/organizationEvents?filter=state=ACTIVE%20category=INCIDENT&page_size=2&page_token={page_token}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "organization_events": [
    {
      "name": "organizations/ORGANIZATION_ID/locations/global/organizationEvents/event-123",
      "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "The issue with Google Cloud SQL has been resolved for all affected projects. We thank you for your patience while we worked on resolving the issue.",
      "category": "INCIDENT",
      "detailedCategory": "CONFIRMED_INCIDENT",
      "state": "ACTIVE",
      "detailedState": "CONFIRMED",
      "eventImpacts": [
        {
          "product": {
            "productName": "Google Cloud SQL",
            "id": "hV87iK5DcEXKgWU2kDri",
          },
          "location": {
            "locationName": "asia-east2",
          }
        },
        {
          "product": {
            "productName": "Google Cloud SQL",
            "id": "hV87iK5DcEXKgWU2kDri",
          },
          "location": {
            "locationName": "asia-southeast1",
          }
        }
      ],
      "updateTime": "2022-10-18T17:44:05.690761Z",
      "startTime": "2022-10-18T17:41:20.112287Z",
    },
    {
      "name": "organizations/ORGANIZATION_ID/locations/global/organizationEvents/event-567",
      "title": "Cloud Firestore may experience errors.",
      "description": "Mitigation work is currently underway by our engineering team. The mitigation is expected to complete by 2022-10-07T16:30:00Z.",
      "category": "INCIDENT",
      "detailedCategory": "CONFIRMED_INCIDENT",
      "state": "ACTIVE",
      "detailedState": "CONFIRMED",
      "eventImpacts": [
        {
          "product": {
            "productName": "Cloud Firestore",
            "id": "CETSkT92V21G6A1x28me",
          },
          "location": {
            "locationName": "us-central1-a",
          }
        }
      ],
      "updateTime": "2022-10-07T15:19:59.409530Z",
      "startTime": "2022-10-07T15:10:35.887125Z",
      "nextUpdateTime": "2022-10-07T16:30:00Z"
    }
  ],
  "nextPageToken": "CgwIw8bDmgYQz4nUlgMQChomcHJvamVjdHMvcHNoLW1hbnVhbC"
}

Untuk mendapatkan ORGANIZATION_ID, lihat Mendapatkan ID resource organisasi.

Jika Anda tidak memiliki izin untuk mencantumkan peristiwa, Anda akan mendapatkan error PERMISSION_DENIED.

{
  "error": {
    "code": 403,
    "message": "Permission 'servicehealth.organizationEvents.list' denied on resource '//servicehealth.googleapis.com/organizations/ORGANIZATION_ID/locations/global' (or it may not exist).",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "IAM_PERMISSION_DENIED",
        "domain": "servicehealth.googleapis.com",
        "metadata": {
          "resource": "organizations/<var class="readonly">ORGANIZATION_ID</var>/locations/global",
          "permission": "servicehealth.organizationEvents.list"
        }
      }
    ]
  }
}

Membuat daftar project dalam organisasi yang mungkin terpengaruh oleh peristiwa

Anda dapat mencantumkan semua project di bawah Google Cloud organisasi tertentu yang:

  • Mungkin terpengaruh oleh acara (OrganizationImpact).
  • Telah mengaktifkan Personalized Service Health.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • API_VERSION: versi API yang akan digunakan. Gunakan v1 atau v1beta.
  • EVENT_ID: ID peristiwa yang mungkin memengaruhi organisasi.
  • ORGANIZATION_ID: ID organisasi Google Cloud Anda.
  • PROJECT_ID: project ID yang digunakan untuk kuota dan penagihan.

Metode HTTP dan URL:

GET https://servicehealth.googleapis.com/API_VERSION/organizations/ORGANIZATION_ID/locations/global/organizationImpacts?filter=events:organizations%2FORGANIZATION_ID%2Flocations%2Fglobal%2FEVENT_ID&page_size=2&page_token={page_token}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "organization_impacts": [
    {
      "name": "organizations/ORGANIZATION_ID/locations/global/organizationImpacts/impact-123",
      "events": [
        "organizations/ORGANIZATION_ID/locations/global/organizationEvents/EVENT_ID",
      ],
      "asset": {
        "assetName": "//cloudresourcemanager.googleapis.com/projects/{PROJECT_NUMBER_1}",
        "assetType": "cloudresourcemanager.googleapis.com/Project",
      },
      "updateTime": "2022-10-18T17:44:05.690761Z",
    },
    {
      "name": "organizations/ORGANIZATION_ID/locations/global/organizationImpacts/impact-234",
      "events": [
        "organizations/ORGANIZATION_ID/locations/global/organizationEvents/EVENT_ID",
      ],
      "asset": {
        "assetName": "//cloudresourcemanager.googleapis.com/projects/{PROJECT_NUMBER_2}",
        "assetType": "cloudresourcemanager.googleapis.com/Project",
      },
      "updateTime": "2022-10-18T17:44:05.690761Z",
    }
  ],
  "nextPageToken": "CgwIw8bDmgYQz4nUlgMQChomcHJvamVjdHMvcHNoLW1hbnVhbC"
}

Jika Anda tidak memiliki izin untuk mencantumkan peristiwa, Anda akan mendapatkan error PERMISSION_DENIED berikut.

{
  "error": {
    "code": 403,
    "message": "Permission 'servicehealth.organizationImpacts.list' denied on resource '//servicehealth.googleapis.com/organizations/ORGANIZATION_ID/locations/global' (or it may not exist).",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "IAM_PERMISSION_DENIED",
        "domain": "servicehealth.googleapis.com",
        "metadata": {
          "resource": "organizations/ORGANIZATION_ID/locations/global",
          "permission": "servicehealth.organizationImpacts.list"
        }
      }
    ]
  }
}

Mencantumkan resource yang terpengaruh dalam project

Untuk produk yang didukung Google Cloud , Anda dapat mencantumkan resource Google Cloud tertentu dalam project Anda yang terpengaruh oleh peristiwa Service Health.

Untuk mencantumkan resource yang terpengaruh, Service Health API (servicehealth.googleapis.com) harus diaktifkan di project setidaknya 24 jam sebelum peristiwa dimulai, dan principal Anda harus memiliki izin servicehealth.impacts.list (disertakan dalam roles/servicehealth.viewer).

REST API (v1beta)

Untuk mencantumkan resource yang terpengaruh dalam project, kirim permintaan ke Service Health API dengan parameter berikut:

Parameter Nilai Deskripsi
parent projects/PROJECT_ID/locations/global Wajib. Project ID atau nomor project tempat Anda ingin mencantumkan resource yang terpengaruh.
pageSize 1 sampai 100 Opsional. Jumlah maksimum dampak yang akan ditampilkan per halaman. Jika tidak ditentukan, setelan defaultnya adalah 10.
pageToken string Opsional. Token dari ListImpactsResponse sebelumnya untuk mengambil halaman hasil berikutnya.
filter string Opsional. Ekspresi filter untuk mencakup dampak yang ditampilkan. Misalnya, untuk mencantumkan resource yang terpengaruh oleh peristiwa tertentu, tetapkan filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID atau nomor project Google Cloud Anda.

Metode HTTP dan URL:

GET https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts

Untuk menggunakan curl, panggil endpoint GET secara langsung:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts"

gcloud

Jalankan perintah berikut untuk mencantumkan resource yang terpengaruh dalam project:

gcloud beta service-health impacts list \
    --project=PROJECT_ID \
    --location=global

Untuk mencantumkan hanya resource yang terpengaruh oleh peristiwa tertentu, teruskan flag --filter:

gcloud beta service-health impacts list \
    --project=PROJECT_ID \
    --location=global \
    --filter="events:projects/PROJECT_ID/locations/global/events/EVENT_ID"

Jika permintaan berhasil, isi respons akan berisi daftar objek Impact yang mirip dengan berikut ini:

{
  "impacts": [
    {
      "name": "projects/my-project/locations/global/impacts/f9a8b7c6-d5e4-4f3a-9b2c-1d0e9f8a7b6c",
      "events": [
        "projects/my-project/locations/global/events/1234567890abcdef"
      ],
      "asset": {
        "assetName": "//cloudsql.googleapis.com/projects/9876543210/instances/prod-orders-db",
        "assetType": "sqladmin.googleapis.com/Instance"
      },
      "description": "Instance experienced elevated connection errors during regional network disruption.",
      "createTime": "2026-10-08T14:12:05.120450Z",
      "updateTime": "2026-10-08T14:12:05.120450Z"
    }
  ]
}

Contoh filter umum untuk resource yang terpengaruh

Anda dapat meneruskan parameter kueri filter (atau --filter di Google Cloud CLI) untuk mempersempit data Impact yang ditampilkan:

  • Mencantumkan resource yang terpengaruh untuk peristiwa tertentu: filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID
  • Mencantumkan resource yang terpengaruh dari jenis resource tertentu (misalnya, instance Cloud SQL): filter=asset.assetType="sqladmin.googleapis.com/Instance"
  • Mencantumkan resource yang terpengaruh yang diperbarui setelah stempel waktu tertentu: filter=updateTime>"2026-10-08T00:00:00Z"

Mendapatkan detail tentang resource yang terpengaruh

Anda dapat mengambil data Impact tertentu menggunakan IMPACT_ID-nya.

REST API (v1beta)

Untuk mendapatkan detail tentang data resource tertentu yang terpengaruh, kirim permintaan dengan parameter berikut:

Parameter Nilai Deskripsi
name projects/PROJECT_ID/locations/global/impacts/IMPACT_ID Wajib. Nama resource lengkap data Impact yang akan diambil.

Metode HTTP dan URL:

GET https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts/IMPACT_ID
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts/IMPACT_ID"

gcloud

Jalankan perintah berikut untuk mendapatkan detail tentang data resource yang terpengaruh:

gcloud beta service-health impacts describe IMPACT_ID \
    --project=PROJECT_ID \
    --location=global

Jika permintaan berhasil, isi respons akan berisi objek Impact:

{
  "name": "projects/my-project/locations/global/impacts/f9a8b7c6-d5e4-4f3a-9b2c-1d0e9f8a7b6c",
  "events": [
    "projects/my-project/locations/global/events/1234567890abcdef"
  ],
  "asset": {
    "assetName": "//cloudsql.googleapis.com/projects/9876543210/instances/prod-orders-db",
    "assetType": "sqladmin.googleapis.com/Instance"
  },
  "description": "Instance experienced elevated connection errors during regional network disruption.",
  "createTime": "2026-10-08T14:12:05.120450Z",
  "updateTime": "2026-10-08T14:12:05.120450Z"
}

Langkah berikutnya

Lihat petunjuk untuk menarik informasi peristiwa berdasarkan project atau organisasi menggunakan Service Health API.