Gestire le norme per i consumatori

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

ConsumerPolicy è una risorsa dell'API Service Usage che si trova a ogni livello della gerarchia di risorseGoogle Cloud . Questa risorsa, sempre denominata default, contiene enableRules che definiscono i servizi abilitati. Anziché attivare o disattivare un servizio specifico, puoi modificare la risorsa ConsumerPolicy. Quando un nome di servizio è presente nell'elenco, il servizio è abilitato a quel livello della gerarchia.

Questo documento mostra come utilizzare Google Cloud CLI per gestire le policy per i consumatori per progetti, cartelle e organizzazioni.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the 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. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  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. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Service Usage API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable serviceusage.googleapis.com

  9. Install the Google Cloud CLI.

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

  11. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  12. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

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

  14. Verify that billing is enabled for your Google Cloud project.

  15. Enable the Service Usage API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable serviceusage.googleapis.com

  16. Se non indichi la risorsa Google Cloud che vuoi gestire, i comandi in questo documento vengono impostati per impostazione predefinita sul progetto corrente. Ad esempio, gcloud beta services policies get --policy-name=default restituisce la policy consumer per il progetto corrente.

    Puoi recuperare l'ID progetto attuale:

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

    17. Ruoli obbligatori

    Per ottenere le autorizzazioni necessarie per gestire le policy dei consumatori, chiedi all'amministratore di concederti il ruolo IAM Service Usage Admin (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 le policy per i consumatori. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

    Autorizzazioni obbligatorie

    Per gestire le policy per i consumatori sono necessarie le seguenti autorizzazioni:

    • Recupera una policy per i consumatori: serviceusage.consumerpolicy.get
    • Aggiorna una policy per i consumatori:
      • serviceusage.consumerpolicy.analyze
      • serviceusage.consumerpolicy.update
    • Acquisisci una policy efficace: serviceusage.effectivepolicy.get
    • Controlla se un servizio è abilitato: serviceusage.values.test

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

    Recupera una policy consumer

    Puoi recuperare ConsumerPolicy per un progetto, una cartella o un'organizzazione utilizzando il comando gcloud beta services policies get.

    Questo comando restituisce il valore enableRules impostato a quel livello di risorsa esatto e non le regole ereditate. Per una visualizzazione più completa che includa le regole ereditate, puoi recuperare le norme effettive. È supportato solo il nome del criterio default.

    Progetto

    gcloud beta services policies get --policy-name=default \
    --project=PROJECT_ID \
    --output-file=OUTPUT_FILE

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo Google Cloud ID progetto. In alternativa, ometti il flag per impostare come predefinito il progetto corrente.
    • OUTPUT_FILE: (facoltativo) il percorso di un file di output in cui è possibile salvare i contenuti delle norme per i consumatori. I formati di file supportati sono JSON e YAML.

    Cartella

    gcloud beta services policies get --policy-name=default \
    --folder=FOLDER_ID \
    --output-file=OUTPUT_FILE

    Sostituisci quanto segue:

    • FOLDER_ID: il tuo Google Cloud ID cartella.
    • OUTPUT_FILE: (facoltativo) il percorso di un file di output in cui è possibile salvare i contenuti delle norme per i consumatori. I formati di file supportati sono JSON e YAML.

    Organizzazione

    gcloud beta services policies get --policy-name=default \
    --organization=ORGANIZATION_ID \
    --output-file=OUTPUT_FILE

    Sostituisci quanto segue:

    • ORGANIZATION_ID: l'Google Cloud ID risorsa organizzazione.
    • OUTPUT_FILE: (facoltativo) il percorso di un file di output in cui è possibile salvare i contenuti delle norme per i consumatori. I formati di file supportati sono JSON e YAML.

    Aggiorna una policy consumer

    Puoi aggiornare un ConsumerPolicy utilizzando il comando gcloud beta services policies update. In questo modo puoi sostituire la policy attuale e utilizzare un file YAML per aggiornare molti servizi abilitati contemporaneamente.

    Questo comando non attiva automaticamente le dipendenze del servizio. Devi elencare esplicitamente tutte le dipendenze del servizio nel file di input. Puoi utilizzare il flag --validate-only per visualizzare l'anteprima delle modifiche prima di applicarle.

    gcloud beta services policies update --consumer-policy-file=PATH_TO_CONSUMER_POLICY

    Sostituisci PATH_TO_CONSUMER_POLICY con il percorso del file YAML che contiene la policy per i consumatori, ad esempio:

    gcloud beta services policies update --consumer-policy-file=/path/to/the/file.yaml

    Flag supportati:

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

    • --bypass-dependency-check per ignorare il controllo delle dipendenze. Quando aggiungi un servizio, tutte le dipendenze del servizio devono essere presenti nel criterio. Quando rimuovi un servizio, nessun altro servizio nella policy può dipendere da esso. In caso contrario, l'aggiornamento non va a buon fine e viene restituito un errore.

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

    Tieni presente quanto segue:

    • Per ottenere un modello YAML per il file delle norme, prima recupera le norme per i consumatori e utilizza il flag --output-file per salvare le norme in un file. Quindi, modifica questo file e utilizzalo come input per il comando di aggiornamento. Modello di esempio:

      name: projects/PROJECT_ID/consumerPolicies/default
enableRules:
  services:
    - services/SERVICE
    - ...
    - ...

      Sostituisci quanto segue:

      • PROJECT_ID: il tuo Google Cloud ID progetto. Altri nomi di risorse supportati seguono un formato simile, ad esempio: folders/FOLDER_ID/consumerPolicies/default.

      • SERVICE: il nome del servizio, ad esempio: bigquery.googleapis.com.

    Ottenere una policy efficace

    Puoi recuperare la policy effettiva per una risorsa utilizzando il comando gcloud beta services policies get-effective.

    Il criterio effettivo combina ConsumerPolicy della risorsa con i criteri di tutti i suoi antenati. In questo modo, puoi visualizzare tutti i servizi abilitati, inclusi quelli abilitati direttamente sulla risorsa e quelli ereditati dai relativi antenati.

    Progetto

    gcloud beta services policies get-effective --project=PROJECT_ID \
    --view=VIEW

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo Google Cloud ID progetto. In alternativa, ometti il flag per impostare come predefinito il progetto corrente.
    • VIEW: BASIC per recuperare un insieme limitato di metadati o FULL per recuperare l'insieme completo di metadati, incluso il punto in cui ogni servizio è stato attivato nella gerarchia. Il valore predefinito è BASIC.

    Cartella

    gcloud beta services policies get-effective --folder=FOLDER_ID \
    --view=VIEW

    Sostituisci quanto segue:

    • FOLDER_ID: il tuo Google Cloud ID cartella.
    • VIEW: BASIC per recuperare un insieme limitato di metadati o FULL per recuperare l'insieme completo di metadati, incluso il punto in cui ogni servizio è stato attivato nella gerarchia. Il valore predefinito è BASIC.

    Organizzazione

    gcloud beta services policies get-effective --organization=ORGANIZATION_ID \
    --view=VIEW

    Sostituisci quanto segue:

    • ORGANIZATION_ID: l'Google Cloud ID risorsa organizzazione.
    • VIEW: BASIC per recuperare un insieme limitato di metadati o FULL per recuperare l'insieme completo di metadati, incluso il punto in cui ogni servizio è stato attivato nella gerarchia. Il valore predefinito è BASIC.

    Controllare se un servizio è abilitato

    Puoi controllare se un servizio è abilitato su una risorsa utilizzando il comando gcloud beta services policies test-enabled.

    Quando controlla lo stato di un servizio, questo comando considera la policy effettiva e la gerarchia completa delle risorse. Google Cloud

    Progetto

    gcloud beta services policies test-enabled SERVICE \
    --project=PROJECT_ID

    Sostituisci quanto segue:

    • SERVICE: il nome del servizio che vuoi controllare.
    • PROJECT_ID: il tuo Google Cloud ID progetto. In alternativa, ometti il flag per impostare come predefinito il progetto corrente.

    Cartella

    gcloud beta services policies test-enabled SERVICE \
    --folder=FOLDER_ID

    Sostituisci quanto segue:

    Organizzazione

    gcloud beta services policies test-enabled SERVICE \
    --organization=ORGANIZATION_ID

    Sostituisci quanto segue:

    Esempi

    Recupero delle norme per i consumatori

    • Recupero delle norme per i consumatori per il progetto attuale: 
      gcloud beta services policies get

      Output:

      name: projects/PROJECT_ID/consumerPolicies/default
enableRules:
 services:
  - services/apikeys.googleapis.com
  - services/compute.googleapis.com
  - services/oslogin.googleapis.com
  - services/serviceusage.googleapis.com
updateTime: 2025-09-11T23:05:22.758394Z
createTime: 2025-01-31T20:17:37.272343Z
etag: W/"W9nsVJK0V1m7ee7tM7pFDg=="

    Aggiornamento della policy per i consumatori

    • Aggiornamento della policy consumer riuscito: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

      Output:

      Operation [operations/ucpat.p39-581601899707-86fe7e37-c7f9-4624-90c4-d54754d57eed] complete. Result: {
    "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
    "createTime":"1970-01-01T00:00:00Z",
    "enableRules":[
        {
            "services":[
                "services/apikeys.googleapis.com"
            ]
        }
    ],
    "name":"projects/PROJECT_ID/consumerPolicies/default",
    "updateTime":"1970-01-01T00:00:00Z"
}
    • Aggiornamento senza esito dei criteri consumer: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.json

      Messaggio di errore:

      ERROR: (gcloud.beta.services.policies.update) Invalid consumer_policy_file format. Please provide path to a yaml file.
    • Tentativo di aggiornamento delle norme per i consumatori quando il servizio è stato utilizzato o attivato di recente: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

      Output:

      The operation "operations/ucpat.p39-581601899707-4884bdb0-d899-49ac-9c83-38457950ef33" resulted in a failure "The services apikeys.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. Help Token: AVSZLmtCfGwMm4oHmOyExdDEFRQ0pFiBrl879nbZlY2JkfVzeU63u66ApXYr6MIEAoig..."
    • Aggiornamento delle norme per i consumatori quando il servizio è stato utilizzato o attivato di recente ignorando il controllo dell'utilizzo: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml --bypass-api-usage-check

      Output:

      Operation [operations/ucpat.p39-581601899707-8ffda670-ed04-4776-8d43-d2f8e1817e00] complete. Result: {
    "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
    "createTime":"1970-01-01T00:00:00Z",
    "enableRules":[
        {
            "services":[
                "services/serviceusage.googleapis.com"
            ]
        }
    ],
    "name":"projects/PROJECT_ID/consumerPolicies/default",
    "updateTime":"1970-01-01T00:00:00Z"
}

    Recupero della policy effettiva

    • Recupero della visualizzazione BASIC della norma vigente per il progetto attuale: 
      gcloud beta services policies get-effective

      Output:

      EnabledRules:
 Services:
  -   services/apikeys.googleapis.com
  -   services/compute.googleapis.com
  -   services/computescanning.googleapis.com
  -   services/containeranalysis.googleapis.com
  -   services/containerscanning.googleapis.com
  -   services/gkebackup.googleapis.com
  -   services/osconfig.googleapis.com
  -   services/oslogin.googleapis.com
  -   services/serviceusage.googleapis.com
    • Recupero della visualizzazione FULL della norma effettiva per il progetto attuale: 
      gcloud beta services policies get-effective --view=FULL

      Output:

      EnabledRules:
 Services:
  -   services/apikeys.googleapis.com
  -   services/compute.googleapis.com
  -   services/computescanning.googleapis.com
  -   services/containeranalysis.googleapis.com
  -   services/containerscanning.googleapis.com
  -   services/gkebackup.googleapis.com
  -   services/osconfig.googleapis.com
  -   services/oslogin.googleapis.com
  -   services/serviceusage.googleapis.com

Metadata of effective policy:
EnabledService: services/apikeys.googleapis.com
EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']

EnabledService: services/bcidcloudenforcer-pa.googleapis.com
EnabledPolicies: ['folders/FOLDER_ID/consumerPolicies/default']

EnabledService: services/compute.googleapis.com
EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']
...

    Verificare se un servizio è abilitato

    • Controllo dello stato del servizio di chiavi API abilitate per il progetto corrente: 
      gcloud beta services policies test-enabled apikeys.googleapis.com

      Output:

      Service apikeys.googleapis.com is ENABLED for resource projects/test-project Hierarchical Service Activation.
    • Controllo dello stato del servizio App Hub disattivato per il progetto corrente: 
      gcloud beta services policies test-enabled apphub.googleapis.com

      Output:

      Service apphub.googleapis.com is NOT ENABLED for resource projects/test-project Hierarchical Service Activation.

    Passaggi successivi