Gestisci l'abilitazione dei servizi

L'attivazione gerarchica dei servizi ti consente di gestire l'abilitazione dei servizi ereditata tramite la gerarchia delle risorse Google Cloud . Per saperne di più, consulta la panoramica.

Questo documento mostra come utilizzare Google Cloud CLI per gestire l'abilitazione dei servizi per progetti, cartelle e organizzazioni.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. Installa Google Cloud CLI.

  3. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  4. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  5. Crea o seleziona un progetto Google Cloud .

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Crea un progetto Google Cloud :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

  6. 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.

  7. Installa Google Cloud CLI.

  8. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  9. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  10. Crea o seleziona un progetto Google Cloud .

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Crea un progetto Google Cloud :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

  11. 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.

  12. Se non indichi la risorsa Google Cloud che vuoi gestire, i comandi in questo documento vengono applicati per impostazione predefinita al progetto corrente. Ad esempio, gcloud beta services list --enabled restituisce un elenco di servizi abilitati per il progetto corrente.

    Puoi recuperare l'ID progetto attuale:

    gcloud config list --format='text(core.project)'

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire l'abilitazione dei servizi, chiedi all'amministratore di concederti il ruolo IAM Amministratore di Service Usage (roles/serviceusage.serviceUsageAdmin) sulla risorsa di destinazione. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per gestire l'abilitazione dei servizi. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per gestire l'abilitazione dei servizi sono necessarie le seguenti autorizzazioni:

  • Elenca i servizi:
    • serviceusage.effectivepolicy.get
    • serviceusage.services.list
    • serviceusage.services.get
  • Abilita i servizi:
    • serviceusage.consumerpolicy.get
    • serviceusage.consumerpolicy.update
    • serviceusage.groups.listExpandedMembers
  • Disabilita i servizi:
    • serviceusage.consumerpolicy.get
    • serviceusage.consumerpolicy.update
    • serviceusage.consumerpolicy.analyze

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Elenca servizi

Puoi elencare le API e i servizi di Google abilitati o disponibili per un progetto, una cartella o un'organizzazione utilizzando il comando gcloud beta services list.

L'abilitazione e la disponibilità dei servizi possono essere ereditate dagli antenati delle risorse. I servizi abilitati di una risorsa includono i servizi abilitati sulla risorsa stessa e su tutti i suoi predecessori.

gcloud beta services list --enabled \
    --RESOURCE_TYPE=RESOURCE_ID

Sostituisci quanto segue:

  • RESOURCE_TYPE: il tipo di risorsa per cui vuoi elencare i servizi. I valori validi sono project, folder e organization. Puoi omettere questo flag per restituire i risultati per il progetto corrente.

  • RESOURCE_ID: l'ID progetto, l'ID cartella o l'ID organizzazione, a seconda del valore utilizzato per RESOURCE_TYPE.

Tieni presente quanto segue:

  • Devi specificare uno dei seguenti flag:

    • --available per elencare i servizi che possono essere attivati per l'utilizzo.
    • --enabled per elencare i servizi abilitati per l'utilizzo.

  • Puoi utilizzare altri flag per filtrare e limitare i servizi elencati.

Attiva i servizi

Puoi attivare uno o più servizi per un progetto, una cartella o un'organizzazione utilizzando il comando gcloud beta services enable.

Questo comando aggiorna ConsumerPolicy nella risorsa di destinazione. Per saperne di più, consulta Gestisci le policy dei consumer.

gcloud beta services enable SERVICE \
    --RESOURCE_TYPE=RESOURCE_ID

Sostituisci quanto segue:

  • SERVICE: il nome del servizio che vuoi attivare. Per abilitare più servizi, utilizza i nomi dei servizi delimitati da spazi. Ad esempio, il comando seguente abilita sia le chiavi API sia i servizi BigQuery:

    gcloud beta services enable apikeys.googleapis.com bigquery.googleapis.com

  • RESOURCE_TYPE: il tipo di risorsa per cui vuoi attivare i servizi. I valori validi sono project, folder e organization. Puoi omettere questo flag per abilitare i servizi per il progetto corrente.

  • RESOURCE_ID: l'ID progetto, l'ID cartella o l'ID organizzazione, a seconda del valore utilizzato per RESOURCE_TYPE.

Flag supportati:

  • --async per terminare immediatamente, senza attendere il completamento dell'operazione in corso.

  • --skip-dependency per saltare l'attivazione di eventuali dipendenze dei servizi. In caso contrario, tutte le dipendenze dei servizi sono abilitate per impostazione predefinita.

    Puoi esaminare le dipendenze dei servizi. Per saperne di più, consulta Elenca le dipendenze dei servizi.

  • --validate-only per convalidare l'attivazione senza eseguire effettivamente l'operazione.

Tieni presente quanto segue:

  • Se provi ad attivare un servizio già attivo, riceverai un errore che indica che il servizio è già attivo e presente nella policy consumer. Se il servizio è già abilitato, ma le sue dipendenze non lo sono, il comando verrà eseguito correttamente.

  • Il vincolo della policy dell'organizzazione constraints/serviceuser.services non è compatibile con l'attivazione gerarchica dei servizi e non deve essere utilizzato con questa funzionalità. Utilizza invece il vincolo constraints/gcp.restrictServiceUsage per controllare quali servizi possono essere abilitati per una risorsa. Per saperne di più, consulta Limitazione dell'utilizzo delle risorse.

    • Se la tua organizzazione ha già utilizzato constraints/serviceuser.services e ricevi un errore quando provi a utilizzare l'attivazione dei servizi gerarchici, contatta l'assistenza clienti Google Cloud.

  • Google Cloud crea e gestisce i service account per molti serviziGoogle Cloud . Questi service account sono noti come agenti di servizio. Se si verifica un errore service account not found, potrebbe essere necessario creare un agente di servizio utilizzando il comando gcloud beta services identity create.

Disattiva i servizi

Puoi disattivare uno o più servizi per un progetto, una cartella o un'organizzazione utilizzando il comando gcloud beta services disable.

Questo comando aggiorna ConsumerPolicy nella risorsa di destinazione. Per saperne di più, consulta Gestisci le policy dei consumer.

gcloud beta services disable SERVICE \
    --RESOURCE_TYPE=RESOURCE_ID

Sostituisci quanto segue:

  • SERVICE: il nome del servizio che vuoi disattivare. Per disattivare più servizi, utilizza i nomi dei servizi delimitati da spazi. Ad esempio:

    gcloud beta services disable apikeys.googleapis.com bigquery.googleapis.com

  • RESOURCE_TYPE: il tipo di risorsa per cui vuoi disattivare i servizi. I valori validi sono project, folder e organization. Puoi omettere questo flag per disattivare i servizi per il progetto corrente.

  • RESOURCE_ID: l'ID progetto, l'ID cartella o l'ID organizzazione, a seconda del valore utilizzato per RESOURCE_TYPE. In alternativa, ometti il flag per impostare il progetto attuale come predefinito.

Flag supportati:

  • --async per terminare immediatamente, senza attendere il completamento dell'operazione in corso.

  • --bypass-api-usage-check per ignorare i controlli di utilizzo. In caso contrario, il sistema restituisce un errore se il servizio che vuoi disattivare è stato utilizzato negli ultimi 30 giorni o attivato negli ultimi 3 giorni.

  • Puoi specificare uno dei seguenti flag:

    • --bypass-dependency-service-check per ignorare il controllo delle dipendenze; tutti i servizi abilitati che dipendono dal servizio che stai disabilitando rimangono abilitati.
    • --disable-dependency-services per procedere con la disattivazione del servizio e di tutti i servizi abilitati che dipendono dal servizio che stai disattivando.

    Puoi esaminare le dipendenze dei servizi. Per saperne di più, consulta Elenca le dipendenze dei servizi.

  • --force per procedere anche se sono presenti servizi abilitati che dipendono dal servizio o se il servizio è stato utilizzato negli ultimi 30 giorni o abilitato negli ultimi 3 giorni. Anche i servizi dipendenti sono disattivati.

    I flag --bypass-api-usage-check, --bypass-dependency-service-check e --disable-dependency-services hanno tutti la precedenza sul flag --force.

    L'utilizzo di entrambi i flag --disable-dependency-services e --bypass-api-usage-check equivale all'utilizzo del flag --force. Il servizio e le relative dipendenze vengono disattivati senza verificarne l'utilizzo.

  • --validate-only per convalidare la disattivazione senza eseguire effettivamente l'operazione.

Esempi

Attivazione di un servizio

  • Attivazione del servizio BigQuery senza le relative dipendenze: 
    gcloud beta services enable bigquery.googleapis.com --skip-dependency

    Output:

    Operation [operations/ucpat.p39-581601899707-73a57d57-aa46-4d0b-a5ee-57034a42f2b3] complete. Result: {
      "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
      "createTime":"2025-01-31T20:17:37.272343Z",
      "enableRules":[
          {
              "services":[
                  "services/apikeys.googleapis.com",
                  "services/compute.googleapis.com",
                  "services/oslogin.googleapis.com",
                  "services/serviceusage.googleapis.com",
                  "services/bigquery.googleapis.com"
              ]
          }
      ],
      "etag":"W/\"W9nsVJK0V1m7ee7tM7pFDg==\"",
      "name":"projects/PROJECT_ID/consumerPolicies/default",
      "updateTime":"2025-09-11T23:05:22.758394Z"
  }
  • Attivazione del servizio BigQuery con le relative dipendenze: 
    gcloud beta services enable bigquery.googleapis.com

    Output:

    Operation [operations/ucpat.p39-581601899707-73192b0f-053c-46ee-911a-7eca6b8fe899] complete. Result: {
      "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
      "createTime":"2025-01-31T20:17:37.272343Z",
      "enableRules":[
          {
              "services":[
                  "services/apikeys.googleapis.com",
                  "services/compute.googleapis.com",
                  "services/oslogin.googleapis.com",
                  "services/serviceusage.googleapis.com",
                  "services/cloudresourcemanager.googleapis.com",
                  "services/dataplex.googleapis.com",
                  "services/bigquery.googleapis.com",
                  "services/bigquerystorage.googleapis.com",
                  "services/bigqueryconnection.googleapis.com",
                  "services/analyticshub.googleapis.com",
                  "services/bigquerymigration.googleapis.com",
                  "services/dataform.googleapis.com",
                  "services/bigquerydatapolicy.googleapis.com",
                  "services/bigquerydatatransfer.googleapis.com",
                  "services/bigqueryreservation.googleapis.com"
              ]
          }
      ],
      "etag":"W/\"FDXMAIdsBW7BrXjL7oP6FA==\"",
      "name":"projects/PROJECT_ID/consumerPolicies/default",
      "updateTime":"2025-09-12T19:44:23.675769Z"
  }

Disattivazione di un servizio

  • Tentativo di disattivare il servizio BigQuery con dipendenze attive: 
    gcloud beta services disable bigquery.googleapis.com

    Messaggio di errore:

    ERROR: (gcloud.beta.services.disable) The services are depended on by the following active service(s) {"bigquery.googleapis.com": ["services/bigquerystorage.googleapis.com"]} . Please remove the active dependent services or provide the --disable-dependency-services flag to disable them, or --bypass-dependency-service-check to ignore this check.
  • Tentativo di disattivare il servizio BigQuery con utilizzo recente: 
    gcloud beta services disable bigquery.googleapis.com --disable-dependency-services

    Messaggio di errore:

    ERROR: (gcloud.beta.services.disable) The operation "operations/ucpat.p39-581601899707-d35c2e2b-d2a3-47af-a1c0-033ed65df236" resulted in a failure "The services bigquery.googleapis.com,bigquerystorage.googleapis.com have usage in the last 30 days or were enabled in the past 3 days. Please specify force if you want to proceed with the destructive policy change.
  • Disattivazione del servizio BigQuery e delle relative dipendenze e bypass del controllo di utilizzo: 
    gcloud beta services disable bigquery.googleapis.com --disable-dependency-services --bypass-api-usage-check

    Output:

    Operation [operations/ucpat.p39-581601899707-5c02aa04-7ad7-4eb6-a6a1-dc68653bcdb4] complete. Result: {
    "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
    "createTime":"2025-01-31T20:17:37.272343Z",
    "enableRules":[
        {
            "services":[
                "services/analyticshub.googleapis.com",
                "services/apikeys.googleapis.com",
                "services/bigqueryconnection.googleapis.com",
                "services/bigquerydatapolicy.googleapis.com",
                "services/bigquerydatatransfer.googleapis.com",
                "services/bigquerymigration.googleapis.com",
                "services/bigqueryreservation.googleapis.com",
                "services/cloudresourcemanager.googleapis.com",
                "services/compute.googleapis.com",
                "services/dataform.googleapis.com",
                "services/dataplex.googleapis.com",
                "services/oslogin.googleapis.com",
                "services/serviceusage.googleapis.com"
            ]
        }
    ],
    "etag":"W/\"TqbPaELDHlZQOj7As1P06g==\"",
    "name":"projects/PROJECT_ID/consumerPolicies/default",
    "updateTime":"2025-09-30T21:39:40.746125Z"
}

Passaggi successivi