Gerenciar políticas do consumidor

Com a ativação hierárquica de serviços, é possível gerenciar a ativação de serviços que são herdados pela hierarquia de recursos Google Cloud . Para mais informações, consulte a visão geral.

O ConsumerPolicy é um recurso da API Service Usage encontrado em cada nível da hierarquia de recursosGoogle Cloud . Esse recurso, sempre chamado de default, contém o enableRules que define quais serviços estão ativados. Em vez de ativar ou desativar um serviço específico, você pode modificar o recurso ConsumerPolicy. Quando um nome de serviço está na lista, ele é ativado nesse nível da hierarquia.

Este documento mostra como usar a Google Cloud CLI para gerenciar políticas de consumidores em projetos, pastas e organizações.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. Instale a CLI do Google Cloud.

  3. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  4. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  5. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

    • Selecione o projeto Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  6. Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

  7. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  8. Ative a API Service Usage:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

    gcloud services enable serviceusage.googleapis.com

  9. Instale a CLI do Google Cloud.

  10. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  11. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  12. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

    • Selecione o projeto Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  13. Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

  14. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  15. Ative a API Service Usage:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

    gcloud services enable serviceusage.googleapis.com
    16.

  16. Se você não indicar o recurso Google Cloud que quer gerenciar, os comandos neste documento vão usar o projeto atual por padrão. Por exemplo, gcloud beta services policies get --policy-name=default retorna a política do consumidor para o projeto atual.

    Você pode recuperar o ID do projeto atual:

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

Funções exigidas

Para receber as permissões necessárias para gerenciar políticas de consumo, peça ao administrador para conceder a você o papel do IAM de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin) no recurso de destino. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para gerenciar políticas do consumidor. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para gerenciar políticas de consumo:

  • Receber uma política do consumidor: serviceusage.consumerpolicy.get
  • Atualize uma política do consumidor:
    • serviceusage.consumerpolicy.analyze
    • serviceusage.consumerpolicy.update
  • Receber uma política efetiva: serviceusage.effectivepolicy.get
  • Verifique se um serviço está ativado: serviceusage.values.test

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Receber uma política do consumidor

Você pode recuperar o ConsumerPolicy de um projeto, uma pasta ou uma organização usando o comando gcloud beta services policies get.

Esse comando retorna o conjunto enableRules no nível exato do recurso, e não regras herdadas. Para uma visão mais completa que inclua regras herdadas, recupere a política efetiva. Somente o nome da política default é aceito.

Projeto

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

Substitua:

  • PROJECT_ID: o ID do projetoGoogle Cloud . Ou omita a flag para usar o projeto atual como padrão.
  • OUTPUT_FILE: (opcional) o caminho para um arquivo de saída em que o conteúdo da política do consumidor pode ser salvo. Os formatos de arquivo aceitos são JSON e YAML.

Pasta

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

Substitua:

  • FOLDER_ID: o ID da pastaGoogle Cloud .
  • OUTPUT_FILE: (opcional) o caminho para um arquivo de saída em que o conteúdo da política do consumidor pode ser salvo. Os formatos de arquivo aceitos são JSON e YAML.

Organização

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

Substitua:

  • ORGANIZATION_ID: o ID do recurso da organizaçãoGoogle Cloud .
  • OUTPUT_FILE: (opcional) o caminho para um arquivo de saída em que o conteúdo da política do consumidor pode ser salvo. Os formatos de arquivo aceitos são JSON e YAML.

Atualizar uma política do consumidor

É possível atualizar um ConsumerPolicy usando o comando gcloud beta services policies update. Isso permite substituir a política atual e usar um arquivo YAML para atualizar vários serviços ativados de uma só vez.

Esse comando não ativa automaticamente as dependências de serviço. É necessário listar todas as dependências de serviço explicitamente no arquivo de entrada. Use a flag --validate-only para visualizar as mudanças antes de aplicá-las.

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

Substitua PATH_TO_CONSUMER_POLICY pelo caminho para o arquivo YAML que contém a política do consumidor. Por exemplo:

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

Flags aceitas:

  • --bypass-api-usage-check para ignorar as verificações de uso. Caso contrário, o sistema retornará um erro se algum serviço que você quer desativar foi usado nos últimos 30 dias ou ativado nos últimos 3 dias.

  • --bypass-dependency-check para ignorar a verificação de dependências. Ao adicionar um serviço, todas as dependências dele precisam estar presentes na política. Ao remover um serviço, nenhum outro serviço na política pode depender dele. Caso contrário, a atualização não será concluída, e um erro será retornado.

  • --validate-only para validar a atualização sem realizar a operação.

Observe o seguinte:

  • Para receber um modelo YAML do arquivo de política, primeiro recupere a política do consumidor e use a flag --output-file para salvar a política em um arquivo. Em seguida, modifique esse arquivo e use-o como entrada para o comando update. Modelo de exemplo:

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

    Substitua:

    • PROJECT_ID: o ID do projetoGoogle Cloud . Outros nomes de recursos compatíveis seguem um formato semelhante. Por exemplo: folders/FOLDER_ID/consumerPolicies/default.

    • SERVICE: o nome do serviço. Por exemplo: bigquery.googleapis.com.

Receber uma política em vigor

Use o comando gcloud beta services policies get-effective para recuperar a política efetiva de um recurso.

A política efetiva combina o ConsumerPolicy do recurso com as políticas de todos os ancestrais. Isso oferece uma visão completa de todos os serviços ativados, incluindo os ativados diretamente no recurso e os herdados dos ancestrais dele.

Projeto

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

Substitua:

  • PROJECT_ID: o ID do projetoGoogle Cloud . Ou omita a flag para usar o projeto atual como padrão.
  • VIEW: BASIC para recuperar um conjunto limitado de metadados ou FULL para recuperar o conjunto completo de metadados, incluindo onde cada serviço foi ativado na hierarquia. O padrão é BASIC.

Pasta

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

Substitua:

  • FOLDER_ID: o ID da pastaGoogle Cloud .
  • VIEW: BASIC para recuperar um conjunto limitado de metadados ou FULL para recuperar o conjunto completo de metadados, incluindo onde cada serviço foi ativado na hierarquia. O padrão é BASIC.

Organização

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

Substitua:

  • ORGANIZATION_ID: o ID do recurso da organizaçãoGoogle Cloud .
  • VIEW: BASIC para recuperar um conjunto limitado de metadados ou FULL para recuperar o conjunto completo de metadados, incluindo onde cada serviço foi ativado na hierarquia. O padrão é BASIC.

Verificar se um serviço está ativado

Use o comando gcloud beta services policies test-enabled para verificar se um serviço está ativado em um recurso.

Ao verificar o status de um serviço, esse comando considera a política efetiva e a hierarquia completa de recursos do Google Cloud .

Projeto

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

Substitua:

  • SERVICE: o nome do serviço que você quer verificar.
  • PROJECT_ID: o ID do projetoGoogle Cloud . Ou omita a flag para usar o projeto atual como padrão.

Pasta

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

Substitua:

Organização

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

Substitua:

Exemplos

Como recuperar a política do consumidor

  • Recuperando a política do consumidor para o projeto atual: 
    gcloud beta services policies get

    Saída:

    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=="

Como atualizar a política do consumidor

  • A política do consumidor foi atualizada: 
    gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

    Saída:

    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"
}
  • Falha ao atualizar a política do consumidor: 
    gcloud beta services policies update --consumer-policy-file=/tmp/test.json

    Mensagem de erro:

    ERROR: (gcloud.beta.services.policies.update) Invalid consumer_policy_file format. Please provide path to a yaml file.
  • Tentar atualizar a política do consumidor quando o serviço foi usado ou ativado recentemente: 
    gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

    Saída:

    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..."
  • Atualizar a política do consumidor quando o serviço foi usado ou ativado recentemente sem verificar o uso: 
    gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml --bypass-api-usage-check

    Saída:

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

Como recuperar a política em vigor

  • Recuperando a visualização BASIC da política efetiva para o projeto atual: 
    gcloud beta services policies get-effective

    Saída:

    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
  • Recuperando a visualização FULL da política efetiva para o projeto atual: 
    gcloud beta services policies get-effective --view=FULL

    Saída:

    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']
...

Como verificar se um serviço está ativado

  • Verificando o status do serviço de chaves de API ativadas para o projeto atual: 
    gcloud beta services policies test-enabled apikeys.googleapis.com

    Saída:

    Service apikeys.googleapis.com is ENABLED for resource projects/test-project Hierarchical Service Activation.
  • Verificando o status do serviço desativado do App Hub para o projeto atual: 
    gcloud beta services policies test-enabled apphub.googleapis.com

    Saída:

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

A seguir