Guida rapida: elenca gli eventi che interessano un progetto o un'organizzazione utilizzando l'API Service Health

Questo documento spiega come elencare gli eventi di Personalized Service Health che potrebbero interessare o aver interessato i prodotti Google Cloud nel tuo progetto o nella tua organizzazione Google Cloud . Utilizzerai l'API Personalized Service Health.

Prima di iniziare

  1. Se non è già abilitata, abilita l'API Service Health:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore di Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    gcloud services enable servicehealth.googleapis.com
  2. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  3. Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per elencare gli eventi di Service Health, chiedi all'amministratore di concederti il ruolo IAM Personalized Service Health Viewer (roles/servicehealth.viewer) nel progetto o nell'organizzazione per cui vuoi elencare gli eventi. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Riferimenti

Consulta i riferimenti API per Eventi (v1, v1beta), Impatti (v1beta), OrganizationEvents (v1, v1beta) e OrganizationImpacts (v1, v1beta) per i metodi che puoi utilizzare e il significato dei campi nella risposta.

Quando imposti il prodotto o la località, utilizza i valori disponibili in Google Cloud products e locations.

Elenca tutti gli incidenti attivi per un progetto

Puoi elencare tutti gli incidenti Google Cloud per un progetto Google Cloud specifico.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • API_VERSION: la versione dell'API da utilizzare. Utilizza il v1 o v1beta.
  • PROJECT_ID: l'ID del progetto

Metodo 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}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "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 non disponi delle autorizzazioni richieste per elencare gli eventi, riceverai un errore 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"
        }
      }
    ]
  }
}

Elenca tutti gli incidenti attivi per un'organizzazione

Puoi elencare tutti gli incidenti Google Cloud che interessano qualsiasi progetto che ha abilitato Personalized Service Health nell'organizzazione Google Cloud specifica.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • API_VERSION: la versione dell'API da utilizzare. Utilizza il v1 o v1beta.
  • ORGANIZATION_ID: il tuo ID organizzazione Google Cloud.
  • PROJECT_ID: l'ID progetto utilizzato per la quota e la fatturazione.

Metodo 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}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per ottenere il tuo ORGANIZATION_ID, consulta Recupero dell'ID risorsa dell'organizzazione.

Se non disponi delle autorizzazioni per elencare gli eventi, riceverai un errore 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"
        }
      }
    ]
  }
}

Elenca i progetti di un'organizzazione che potrebbero essere interessati da un evento

Puoi elencare tutti i progetti di un'organizzazione Google Cloud specifica che:

  • Potrebbe essere interessato da un evento (OrganizationImpact).
  • Aver abilitato Personalized Service Health.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • API_VERSION: la versione dell'API da utilizzare. Utilizza il v1 o v1beta.
  • EVENT_ID: l'ID dell'evento che potrebbe interessare un'organizzazione.
  • ORGANIZATION_ID: il tuo ID organizzazione Google Cloud.
  • PROJECT_ID: l'ID progetto utilizzato per la quota e la fatturazione.

Metodo 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}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "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 non disponi delle autorizzazioni per elencare gli eventi, riceverai il seguente errore 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"
        }
      }
    ]
  }
}

Elenca le risorse interessate in un progetto

Per i prodotti Google Cloud supportati, puoi elencare le risorse Google Cloud specifiche del tuo progetto interessate da un evento di Service Health.

Per elencare le risorse interessate, l'API Service Health (servicehealth.googleapis.com) deve essere abilitata nel progetto almeno 24 ore prima dell'inizio dell'evento e l'entità deve disporre dell'autorizzazione servicehealth.impacts.list (inclusa in roles/servicehealth.viewer).

API REST (v1beta)

Per elencare le risorse interessate in un progetto, invia una richiesta all'API Service Health con i seguenti parametri:

Parametro Valore Descrizione
parent projects/PROJECT_ID/locations/global Obbligatorio. ID progetto o numero del progetto in cui vuoi elencare le risorse interessate.
pageSize Da 1 a 100 Facoltativo. Numero massimo di impatti da restituire per pagina. Se non specificato, il valore predefinito è 10.
pageToken string Facoltativo. Token di un ListImpactsResponse precedente per recuperare la pagina di risultati successiva.
filter string Facoltativo. Espressione di filtro per definire l'ambito degli impatti restituiti. Ad esempio, per elencare le risorse interessate da un evento specifico, imposta filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID o il numero del progetto Google Cloud.

Metodo HTTP e URL:

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

Per utilizzare curl, chiama direttamente l'endpoint 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

Esegui il comando seguente per elencare le risorse interessate in un progetto:

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

Per elencare solo le risorse interessate da un evento specifico, passa il flag --filter:

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

Se la richiesta ha esito positivo, il corpo della risposta contiene un elenco di oggetti Impact simili ai seguenti:

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

Esempi di filtri comuni per le risorse interessate

Puoi passare un parametro di query filter (o --filter in Google Cloud CLI) per restringere i record Impact restituiti:

  • Elenca le risorse interessate per un evento specifico: filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID
  • Elenca le risorse interessate di un tipo di risorsa specifico (ad esempio, le istanze Cloud SQL): filter=asset.assetType="sqladmin.googleapis.com/Instance"
  • Elenca le risorse interessate aggiornate dopo un timestamp specifico: filter=updateTime>"2026-10-08T00:00:00Z"

Visualizza i dettagli di una risorsa interessata

Puoi recuperare un record Impact specifico utilizzando il relativo IMPACT_ID.

API REST (v1beta)

Per ottenere i dettagli di un record di risorse interessato specifico, invia una richiesta con il seguente parametro:

Parametro Valore Descrizione
name projects/PROJECT_ID/locations/global/impacts/IMPACT_ID Obbligatorio. Nome completo della risorsa del record Impact da recuperare.

Metodo 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

Esegui il comando seguente per ottenere i dettagli di un record di risorse interessato:

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

Se la richiesta ha esito positivo, il corpo della risposta contiene un oggetto 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"
}

Passaggi successivi

Consulta le guide illustrative per estrarre le informazioni sugli eventi per progetto o organizzazione utilizzando l'API Service Health.