Gerenciar políticas do consumidor

Pré-lançamento — Hierarchical service activation

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

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

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.

Install the Google Cloud CLI.

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

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

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.

Verify that billing is enabled for your Google Cloud project.

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

Install the Google Cloud CLI.

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

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

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.

Verify that billing is enabled for your Google Cloud project.

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

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

   Para 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 enableRules definido exatamente nesse nível de 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 de atualização. 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 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:

• SERVICE: o nome do serviço que você quer verificar.
• FOLDER_ID: o ID da pastaGoogle Cloud .

Organização

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

Substitua:

• SERVICE: o nome do serviço que você quer verificar.
• ORGANIZATION_ID: o ID do recurso da organizaçãoGoogle Cloud .

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.

• Tentativa de 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

• Para ativar e desativar serviços, consulte Gerenciar a ativação de serviços.
• Para inspecionar as dependências do serviço, consulte Listar dependências do serviço.