빠른 시작: Service Health API를 사용하여 프로젝트 또는 조직에 영향을 미치는 이벤트 나열

이 문서에서는 Google Cloud 프로젝트 또는 조직의 Google Cloud 제품에 영향을 미치거나 영향을 미쳤을 수 있는 Personalized Service Health 이벤트를 나열하는 방법을 설명합니다. Personalized Service Health API를 사용합니다.

시작하기 전에

  1. Service Health API가 아직 사용 설정되지 않았으면 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기

    gcloud services enable servicehealth.googleapis.com
  2. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  3. 이 가이드에 기존 프로젝트를 사용하는 경우 이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다. 새 프로젝트를 만든 경우에는 이미 필요한 권한이 있습니다.

필요한 역할

Service Health 이벤트를 나열하는 데 필요한 권한을 얻으려면 관리자에게 이벤트를 나열하려는 프로젝트 또는 조직에 대한 Personalized Service Health 뷰어(roles/servicehealth.viewer) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

참조

사용할 수 있는 메서드와 응답의 필드 의미는 Events(v1, v1beta), Impacts(v1beta), OrganizationEvents(v1, v1beta), OrganizationImpacts(v1, v1beta) API 참조를 확인하세요.

제품 또는 위치를 설정할 때 Google Cloud 제품 및 위치에서 찾은 값을 사용합니다.

프로젝트의 모든 활성 이슈 나열

특정 Google Cloud 프로젝트의 모든 Google Cloud 사고를 나열할 수 있습니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • API_VERSION: 사용할 API 버전입니다. v1 또는 v1beta을 사용합니다.
  • PROJECT_ID: 프로젝트 ID입니다.

HTTP 메서드 및 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}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

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

이벤트를 나열하는 데 필요한 권한이 없으면 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"
        }
      }
    ]
  }
}

조직의 모든 활성 이슈 나열

특정 Google Cloud 조직에서 Personalized Service Health를 사용 설정한 프로젝트에 영향을 미치는 모든 Google Cloud 이슈를 나열할 수 있습니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • API_VERSION: 사용할 API 버전입니다. v1 또는 v1beta을 사용합니다.
  • ORGANIZATION_ID: Google Cloud 조직 ID입니다.
  • PROJECT_ID: 할당량 및 결제에 사용되는 프로젝트 ID입니다.

HTTP 메서드 및 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}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

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

ORGANIZATION_ID를 가져오려면 조직 리소스 ID 가져오기를 참조하세요.

이벤트를 나열할 권한이 없으면 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"
        }
      }
    ]
  }
}

이벤트의 영향을 받을 수 있는 조직의 프로젝트 나열

특정 Google Cloud 조직에서 다음을 충족하는 모든 프로젝트를 나열할 수 있습니다.

  • 이벤트(OrganizationImpact)의 영향을 받을 수 있습니다.
  • Personalized Service Health를 사용 설정했습니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • API_VERSION: 사용할 API 버전입니다. v1 또는 v1beta을 사용합니다.
  • EVENT_ID: 조직에 영향을 미칠 수 있는 이벤트의 ID입니다.
  • ORGANIZATION_ID: Google Cloud 조직 ID입니다.
  • PROJECT_ID: 할당량 및 결제에 사용되는 프로젝트 ID입니다.

HTTP 메서드 및 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}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

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

이벤트를 나열할 권한이 없으면 다음 PERMISSION_DENIED 오류가 발생합니다.

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

프로젝트의 영향을 받는 리소스 나열

지원되는 Google Cloud 제품의 경우 Service Health 이벤트의 영향을 받는 프로젝트의 특정 Google Cloud 리소스를 나열할 수 있습니다.

영향을 받는 리소스를 나열하려면 이벤트가 시작되기 최소 24시간 전에 프로젝트에서 Service Health API(servicehealth.googleapis.com)를 사용 설정해야 하며 주 구성원에게 servicehealth.impacts.list 권한(roles/servicehealth.viewer에 포함)이 있어야 합니다.

REST API (v1beta)

프로젝트에서 영향을 받는 리소스를 나열하려면 다음 매개변수를 사용하여 Service Health API에 요청을 보냅니다.

매개변수 값 설명
parent projects/PROJECT_ID/locations/global 필수 항목입니다. 영향을 받는 리소스를 나열할 프로젝트 ID 또는 프로젝트 번호입니다.
pageSize 1~100 선택사항입니다. 페이지당 반환할 최대 영향 수입니다. 지정하지 않으면 기본값은 10입니다.
pageToken 문자열 선택사항입니다. 결과의 다음 페이지를 검색하기 위한 이전 ListImpactsResponse의 토큰입니다.
filter 문자열 선택사항입니다. 반환된 영향의 범위를 지정하는 필터 표현식입니다. 예를 들어 특정 이벤트의 영향을 받는 리소스를 나열하려면 filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID을 설정합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID 또는 프로젝트 번호입니다.

HTTP 메서드 및 URL:

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

curl을 사용하려면 GET 엔드포인트를 직접 호출합니다.

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

다음 명령어를 실행하여 프로젝트에서 영향을 받는 리소스를 나열합니다.

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

특정 이벤트의 영향을 받는 리소스만 나열하려면 --filter 플래그를 전달합니다.

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

요청이 성공하면 응답 본문에 다음과 유사한 Impact 객체 목록이 포함됩니다.

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

영향을 받는 리소스의 일반적인 필터 예시

filter 쿼리 매개변수(또는 Google Cloud CLI의 --filter)를 전달하여 반환된 Impact 레코드를 좁힐 수 있습니다.

  • 특정 이벤트의 영향을 받는 리소스 나열: filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID
  • 특정 리소스 유형의 영향을 받는 리소스 나열(예: Cloud SQL 인스턴스): filter=asset.assetType="sqladmin.googleapis.com/Instance"
  • 특정 타임스탬프 이후에 업데이트된 영향을 받는 리소스 나열: filter=updateTime>"2026-10-08T00:00:00Z"

영향을 받는 리소스에 대한 세부정보 가져오기

IMPACT_ID를 사용하여 특정 Impact 레코드를 가져올 수 있습니다.

REST API (v1beta)

영향을 받는 특정 리소스 레코드에 대한 세부정보를 가져오려면 다음 매개변수를 사용하여 요청을 전송합니다.

매개변수 값 설명
name projects/PROJECT_ID/locations/global/impacts/IMPACT_ID 필수 항목입니다. 검색할 Impact 레코드의 전체 리소스 이름입니다.

HTTP 메서드 및 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

다음 명령어를 실행하여 영향을 받은 리소스 레코드에 대한 세부정보를 가져옵니다.

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

요청이 성공하면 응답 본문에 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"
}

다음 단계

Service Health API를 사용하여 프로젝트 또는 조직별로 이벤트 정보를 가져오는 방법 알아보기