Guia de início rápido: listar eventos que afetam um projeto ou organização usando a API Service Health

Neste documento, explicamos como listar eventos do Personalized Service Health que podem estar afetando ou que afetaram os produtos do Google Cloud no seu projeto ou na sua organização do Google Cloud . Você vai usar a API Personalized Service Health.

Antes de começar

  1. Ative a API Service Health, se ainda não estiver ativada:

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    gcloud services enable servicehealth.googleapis.com
  2. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  3. Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluí-lo. Se você criou um projeto, já tem as permissões necessárias.

Funções exigidas

Para receber as permissões necessárias para listar eventos do Service Health, peça ao administrador para conceder a você o papel do IAM de Leitor do Personalized Service Health (roles/servicehealth.viewer) no projeto ou na organização em que você quer listar eventos. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Referências

Consulte as referências da API Events (v1, v1beta), Impacts (v1beta), OrganizationEvents (v1, v1beta) e OrganizationImpacts (v1, v1beta) para saber quais métodos podem ser usados e o significado dos campos na resposta.

Ao definir o produto ou o local, use os valores encontrados em Google Cloud produtos e locais.

Listar todos os incidentes ativos de um projeto

É possível listar todos os incidentes do Google Cloud em um projeto específico do Google Cloud .

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • API_VERSION: a versão da API a ser usada. Use v1 ou v1beta.
  • PROJECT_ID: o ID do projeto.

Método HTTP e 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}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Se você não tiver as permissões necessárias para listar eventos, vai receber um erro 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"
        }
      }
    ]
  }
}

Listar todos os incidentes ativos de uma organização

É possível listar todos os incidentes do Google Cloud que afetam qualquer projeto que tenha ativado o Personalized Service Health na organização Google Cloud específica.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • API_VERSION: a versão da API a ser usada. Use v1 ou v1beta.
  • ORGANIZATION_ID: o ID da organização do Google Cloud.
  • PROJECT_ID: o ID do projeto usado para cota e faturamento.

Método HTTP e 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}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Para conseguir o ORGANIZATION_ID, consulte Como conseguir o ID do recurso da sua organização.

Se você não tiver permissões para listar eventos, vai receber um erro 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"
        }
      }
    ]
  }
}

Listar projetos em uma organização que podem ser afetados por um evento

É possível listar todos os projetos em uma organização Google Cloud específica que:

  • Pode ser afetado por um evento (OrganizationImpact).
  • Ativou o Personalized Service Health.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • API_VERSION: a versão da API a ser usada. Use v1 ou v1beta.
  • EVENT_ID: o ID do evento que pode estar afetando uma organização.
  • ORGANIZATION_ID: o ID da organização do Google Cloud.
  • PROJECT_ID: o ID do projeto usado para cota e faturamento.

Método HTTP e 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}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Se você não tiver as permissões para listar eventos, vai receber o seguinte erro 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"
        }
      }
    ]
  }
}

Listar recursos afetados em um projeto

Para produtos Google Cloud compatíveis, é possível listar os recursos específicos do Google Cloud projeto que são afetados por um evento do Service Health.

Para listar os recursos afetados, a API Service Health (servicehealth.googleapis.com) precisa estar ativada no projeto pelo menos 24 horas antes do início do evento, e o principal precisa ter a permissão servicehealth.impacts.list (incluída em roles/servicehealth.viewer).

API REST (v1beta)

Para listar os recursos afetados em um projeto, envie uma solicitação à API Service Health com os seguintes parâmetros:

Parâmetro Valor Descrição
parent projects/PROJECT_ID/locations/global Obrigatório. ID do projeto ou número do projeto em que você quer listar os recursos afetados.
pageSize 1 a 100 Opcional. Número máximo de impactos a serem retornados por página. Quando não especificado, o padrão é 10.
pageToken string Opcional. Token de um ListImpactsResponse anterior para recuperar a próxima página de resultados.
filter string Opcional. Expressão de filtro para definir o escopo dos impactos retornados. Por exemplo, para listar recursos afetados por um evento específico, defina filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID ou número do projeto do Google Cloud.

Método HTTP e URL:

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

Para usar o curl, chame o endpoint GET diretamente:

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

Execute o seguinte comando para listar os recursos afetados em um projeto:

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

Para listar apenas os recursos afetados por um evento específico, transmita a flag --filter:

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

Se a solicitação for bem-sucedida, o corpo da resposta vai conter uma lista de objetos Impact semelhantes a esta:

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

Exemplos de filtros comuns para recursos afetados

É possível transmitir um parâmetro de consulta filter (ou --filter na Google Cloud CLI) para restringir os registros Impact retornados:

  • Listar recursos afetados por um evento específico: filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID
  • Listar recursos afetados de um tipo específico (por exemplo, instâncias do Cloud SQL): filter=asset.assetType="sqladmin.googleapis.com/Instance"
  • Listar os recursos afetados atualizados após um carimbo de data/hora específico: filter=updateTime>"2026-10-08T00:00:00Z"

Receber detalhes sobre um recurso afetado

É possível recuperar um registro Impact específico usando o IMPACT_ID dele.

API REST (v1beta)

Para saber mais sobre um registro de recurso afetado específico, envie uma solicitação com o seguinte parâmetro:

Parâmetro Valor Descrição
name projects/PROJECT_ID/locations/global/impacts/IMPACT_ID Obrigatório. Nome completo do recurso do registro Impact a ser recuperado.

Método HTTP e 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

Execute o comando a seguir para ver detalhes sobre um registro de recurso afetado:

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

Se a solicitação for bem-sucedida, o corpo da resposta vai conter um objeto 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"
}

A seguir

Confira instruções sobre como extrair informações de eventos por projeto ou organização usando a API Service Health.